샌드박스 TypeScript 클라이언트

@coreweave/cwsandbox TypeScript 클라이언트로 CoreWeave 샌드박스를 생성하고 관리할 수 있습니다. 이 가이드에서는 클라이언트를 생성하고, 샌드박스에서 명령어를 실행하고, SDK 오류를 처리하는 방법을 설명합니다. 샌드박스 TypeScript 예시와 API 참조는 버전 1.0.0을 기준으로 합니다. 가이드를 따라 하려면 이 버전을 설치하세요.

사전 요구 사항

Node.js 22 이상과 ECMAScript 모듈(ESM) 프로젝트를 사용하세요. 예시를 tsx로 실행하려면 .mts 파일로 저장하세요. 사용자 인증 정보 선택 및 가져오기에서 사용할 사용자 인증 정보를 선택하세요. 예시에서는 서버리스 용량을 사용합니다. CoreWeave Kubernetes Service(CKS)에 배치하려면 러너를 활성화하고, runnerIds 배열이 비어 있지 않은 CoreWeave API 액세스 토큰을 사용하세요. SDK를 설치하세요.

npm install @coreweave/cwsandbox@1.0.0

클라이언트 생성

사용하는 사용자 인증 정보에 맞는 진입점을 선택하세요. 두 팩토리 모두 SandboxClient를 반환합니다. 루트 @coreweave/cwsandbox 진입점은 유형, 상수, 오류만 내보내므로 클라이언트는 /wandb 또는 /node를 통해 생성하세요. 선택한 탭의 코드를 다른 예시 파일과 같은 위치에 sandbox-client.mts 파일로 저장하세요. 이 코드는 인증 방식을 선택하고 클라이언트를 내보냅니다. 사용자 인증 정보는 코드가 아닌 환경 변수에 보관됩니다.

Forge API 키
CoreWeave API 액세스 토큰

[WANDB-API-KEY]를 Forge API 키로 바꾸세요.

export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";

export const client = createSandboxClientFromEnv();

Forge 팀을 지정하려면 WANDB_ENTITY를 설정하세요. 옵션을 명시적으로 지정하는 방법은 Forge 클라이언트 팩토리를 참조하세요.

[API-ACCESS-TOKEN]을 토큰으로 바꾸세요.

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

export const client = createSandboxClientFromEnv();

이 팩토리는 CWSANDBOX_BASE_URL도 읽으며, 기본값은 https://api.cwsandbox.com 입니다. 옵션을 명시적으로 지정하는 방법은 Node 클라이언트 팩토리를 참조하세요.

명령어 실행

callback이 끝나면 함께 중지되어야 하는 작업에는 withSandbox()를 사용하세요. 이 함수는 샌드박스가 준비 상태가 될 때까지 기다렸다가 callback을 호출하며, callback이 반환되거나 예외를 던지면 샌드박스를 중지합니다.

hello.mts

import { client } from "./sandbox-client.mjs";

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run(["echo", "Hello!"]),
  {
    containerImage: "python:3.11",
    resources: { cpu: "1", memory: "1Gi" },
  },
);

console.log(result.stdout);

스크립트를 실행하세요.

npx --yes --package=tsx tsx hello.mts

스크립트는 Hello!를 출력한 후 샌드박스를 중지합니다. tsx로 실행하거나 TypeScript로 컴파일하면 ./sandbox-client.mjs 임포트는 로컬 sandbox-client.mts 파일로 해석됩니다. commands.run()은 표준 출력(stdout)과 표준 오류(stderr)를 버퍼링한 뒤 exitCode가 포함된 ProcessResult를 반환합니다. 출력을 스트리밍하려면 commands.start()를 사용하세요. 여러 오퍼레이션에서 샌드박스를 계속 사용하려면 client.create()로 생성한 다음 finally 블록에서 중지하세요. 자세한 내용은 샌드박스 라이프사이클 레퍼런스를 참조하세요.

오류 처리

isCWSandboxError()를 사용해 알 수 없는 오류의 타입을 좁힌 다음 code를 확인하세요.

import { isCWSandboxError } from "@coreweave/cwsandbox";
import { client } from "./sandbox-client.mjs";

try {
  await client.withSandbox(async (sandbox) => {
    await sandbox.commands.run(["false"], { check: true });
  });
} catch (error) {
  if (isCWSandboxError(error)) {
    console.error(error.code, error.message);
  } else {
    throw error;
  }
}

check: true를 지정하면 명령어가 0이 아닌 종료 코드로 끝날 때 CWSandboxExecutionError 예외가 발생합니다. 오류 계층 구조와 사용 가능한 메타데이터는 오류를 참조하세요.

API 레퍼런스

이 레퍼런스 문서는 메서드 오버로드, 매개변수 및 반환 유형, 선택적 필드, 상속된 유형을 포함하여 게시된 선언을 그대로 유지합니다. SDK 주석에는 검토를 거친 수정 사항이 반영되어 있습니다.

레퍼런스	내용
클라이언트 및 검색	샌드박스를 생성, 재연결, 나열, 정리하고 템플릿 또는 Compose 파일에서 시작합니다.
샌드박스 및 라이프사이클	샌드박스 핸들, 시작 옵션, 스냅샷, 라이프사이클 상태를 다룹니다.
명령어 및 터미널	명령어 실행, 프로세스 핸들, 표준 입력(stdin), 대화형 터미널을 다룹니다.
파일	버퍼 방식 및 스트리밍 방식의 파일 작업과 마운트된 파일을 다룹니다.
로그	샌드박스 로그를 조회하고 스트리밍합니다.
네트워크 및 서비스	네트워크 규칙, 서비스, 엔드포인트를 다룹니다.
리소스 및 시크릿	리소스 요청량 및 제한, 시크릿 입력을 다룹니다.
요청 옵션 및 기본값	timeout, 취소, 데이터 영역 모드, 기본 상수를 다룹니다.
오류	오류 클래스, 코드, 백엔드 사유 상수를 다룹니다.
Node 클라이언트 팩토리	CoreWeave 토큰 인증과 클라이언트 생성을 다룹니다.
Forge 클라이언트 팩토리	Forge 인증과 팀 선택을 다룹니다.

Compose 예시는 TypeScript에서 샌드박스 생성하기를 참조하세요.

샌드박스

샌드박스 사용하기

샌드박스 관리

레퍼런스

샌드박스 TypeScript 클라이언트

사전 요구 사항

클라이언트 생성

명령어 실행

오류 처리

API 레퍼런스

​사전 요구 사항

​클라이언트 생성

​명령어 실행

​오류 처리

​API 레퍼런스

사전 요구 사항

클라이언트 생성

명령어 실행

오류 처리

API 레퍼런스