POST /v1/sandboxes:createFromFile는 업로드된 파일에서 샌드박스를 시작합니다. 파일 유형과 파일 바이트를 전송하면, 샌드박스 게이트웨이가 문서를 샌드박스 사양으로 변환하고 POST /v1/sandboxes와 동일한 생성 경로를 실행합니다.
도커 Compose(SANDBOX_FILE_TYPE_COMPOSE)가 유일하게 허용되는 파일 유형입니다. 파일의 모든 서비스는 단일 샌드박스의 컨테이너가 되며, 사용자가 지정한 하나의 서비스가 샌드박스 주 서비스가 됩니다. 게이트웨이는 파일 바이트를 저장하지 않습니다. GET /v1/sandboxes/{sandboxId}는 변환된 사양을 반환합니다.
이 가이드에서는 사전 빌드되어 pull 가능한 이미지를 사용하는 Compose 파일을 다룹니다. 기존 프로젝트를 임포트하기 전에 Compose 지원를 읽어보십시오.
시작하기 전에
사용자 인증 정보 선택 및 가져오기에서 사용할 사용자 인증 정보를 선택하세요. Bash에서 아래 탭 중 하나의 명령어를 실행한 다음, 같은 셸에서 요청을 실행하세요. 서버리스 배치를 사용하는 경우 서버리스 샌드박스 액세스 권한이 있는 계정의 사용자 인증 정보를 사용하세요. CoreWeave Kubernetes Service(CKS) 배치를 사용하려면 Sandbox User 역할이 있는 CoreWeave 토큰과 같은 조직에 설정된 러너가 필요합니다.- Forge API 키
- CoreWeave API 액세스 토큰
[WANDB-API-KEY]를 API 키로 바꾸세요.[WANDB-ENTITY]를 팀 이름으로 바꾸고 배열에 -H "x-entity-id: [WANDB-ENTITY]"를 추가하세요.https://api.cwsandbox.com의 샌드박스 런타임 API를 호출합니다. 러너 관리 API는 https://api.coreweave.com을 사용하며, Sandbox Admin 역할이 있는 CoreWeave 토큰이 필요합니다.
요청 필드
이 요청에는
mode, maxLifetimeSeconds, tags, network, objectStorageAccess, annotations, runnerIds, requestId도 지정할 수 있으며, 각 필드의 의미는 POST /v1/sandboxes와 동일합니다. networkIds를 지정하면 UNIMPLEMENTED가 반환됩니다.
CKS에 배치하려면 CoreWeave 토큰 탭을 선택하고 러너를 활성화하세요. 그런 다음 생성 예시의 jq 객체에서 mode를 "SANDBOX_MODE_CKS"로 변경하세요. 특정 러너를 지정하려면 runnerIds: ["[RUNNER-ID]"]도 추가하고 플레이스홀더를 해당 러너의 ID로 바꾸세요. 객체 저장소 사전 요구 사항은 샌드박스에 AI Object Storage 액세스 권한 부여를 참조하세요.
이 필드 목록 외의 필드는 지원되지 않습니다. 볼륨, instance type, 런타임 클래스, 이미지 pull 사용자 인증 정보, 게시된 서비스는 이 엔드포인트에서 사용할 수 없습니다. 이러한 항목이 필요하면 POST /v1/sandboxes를 사용하세요.
샌드박스 만들기
Compose 파일을 작성하세요:Write compose.yaml
contents를 base64로 인코딩하여 POST 요청으로 전송하세요:
Create a sandbox from compose.yaml
STATE_CREATING 상태의 샌드박스입니다. STATE_RUNNING 또는 종료 상태에 도달할 때까지 해당 sandboxId를 폴링하세요:
Poll the sandbox
main은 주 컨테이너로 표시되고 HELPER_HOST는 여전히 helper로 설정되어 있습니다. 샌드박스 내부에서 helper는 127.0.0.1로 해석됩니다.
생성을 안전하게 재시도하려면 requestId를 보내세요. 동일한 requestId와 동일하게 선언된 입력을 보내면 기존 샌드박스가 반환됩니다. 동일한 requestId에 공백만 변경한 경우를 포함하여 다른 바이트를 보내면 사유가 CWSANDBOX_REQUEST_ID_CONFLICT인 ALREADY_EXISTS가 반환됩니다.
TypeScript에서 샌드박스 만들기
TypeScript 소프트웨어 개발 키트(SDK) 1.0.0은runFromFile() 및 withSandboxFromFile()을 통해 Compose를 지원합니다. 먼저 TypeScript 클라이언트 설정을 완료하고 sandbox-client.mts 파일을 이 스크립트와 같은 디렉터리에 저장하세요.
샌드박스 만들기에서 만든 compose.yaml 파일을 사용하세요. withSandboxFromFile()은 샌드박스가 준비 완료 상태가 될 때까지 기다렸다가 callback을 실행하고, callback이 반환하거나 예외를 발생시키면 샌드박스를 중지합니다:
compose.mts
Compose sandbox ready를 출력한 후 샌드박스를 중지합니다.
문자열 인수는 항상 파일 경로로 처리됩니다. 인라인 YAML을 제공하려면 new TextEncoder().encode(yaml)로 UTF-8 바이트를 전달하세요. SDK는 바이트를 다시 포맷하지 않고 그대로 전송합니다. 파일 크기는 API 제한인 256 KiB를 넘지 않아야 합니다.
버전 1.0.0에서는 primaryService가 필수이며, 파일에 정의된 서비스 이름을 지정해야 합니다. defaultResources는 프로젝트 전체가 아닌 서비스별로 CPU와 메모리를 지정하며, GPU 리소스는 지원하지 않습니다. 원래 빌드가 필요한 서비스에는 imageOverrides를 사용해 pull 가능한 이미지를 지정하세요. Compose 지원의 제한 사항은 SDK에도 동일하게 적용됩니다.
라이프사이클을 직접 관리하려면 샌드박스 핸들을 반환하는 runFromFile()을 사용하고, finally 블록에서 샌드박스를 중지하세요. 두 메서드의 시그니처는 SandboxClient를 참조하세요. 지원되는 옵션은 SandboxRunFromFileOptions를 참조하세요.
Compose 지원
모든 서비스는 하나의 파드와 하나의 네트워크 namespace를 공유합니다. 서비스 이름은127.0.0.1로 확인되므로 HELPER_HOST: helper 및 API_BASE: http://main:8080과 같은 값은 파일을 다시 작성하지 않고도 작동합니다. 샌드박스에는 서비스별 IP 주소, 브리지 네트워크 또는 레플리카가 없습니다.
다음 동작은 도커 Compose와 다릅니다:
- 시작은 순차적입니다. 주 서비스가 아닌 모든 서비스는 주 서비스보다 먼저 하나씩 시작됩니다. 이를 위해
maxLifetimeSeconds를 설정하세요. 준비되지 않는 서비스는 샌드박스를STATE_CREATING상태로 남겨둡니다. RUNNING은 주 서비스만 추적합니다. 시작 후 크래시가 발생한 헬퍼는 샌드박스를 실패로 만들지 않습니다.healthcheck는 exec 전용 시작 프로브가 됩니다.test는 문자열,CMD,CMD-SHELL또는NONE이어야 하며, 지속 시간은 정수 초여야 합니다. 프로브가 재시도 횟수를 모두 소진하면 컨테이너는 unhealthy로 표시되지 않고 중지됩니다.- 포트는 파드에 남아 있습니다.
expose와ports는 수신 포트를 선언하지만 외부에 게시되지는 않습니다. - 사전 빌드된 이미지를 사용하세요. 파일의
image:또는imageOverrides항목을 통해 모든 서비스에 pull 가능한 이미지를 지정하세요. 여전히build:가 필요한 서비스는UNIMPLEMENTED를 반환합니다. command와entrypoint는 도커의 shell 및 exec 형식을 따릅니다. 생략하면 이미지 기본값을 사용합니다. 명시적인null과[]은 거부됩니다.- GPU는 주 서비스 전용이며,
gpu기능과 양의 정수 개수를 가진deploy.resources.reservations.devices를 통해 할당됩니다. - 이름은 DNS-1123 레이블(
my-app,My_App이 아님)이어야 하며, 예약된cw-object-store-agent,cw-object-store-agent-restore또는dns-egress접두사를 사용할 수 없습니다.
지원되지 않는 키
문서는 자체 포함되어야 합니다: 게이트웨이는 디스크를 읽지 않으며 환경을 확장하지 않습니다. 인식되지 않는 키는 무시되는 대신 문제가 되는 필드 경로와 함께 거부됩니다.
게이트웨이는
version, 프로젝트 name, labels, x-* 확장 키를 무시합니다. labels가 샌드박스에 도달할 것이라고 기대하지 마십시오.
일반적인 오류
필드 위반은 경로와 제한을 명시하는BadRequest 세부 정보로 도착합니다. 문서를 인용하지 않습니다.
참고
- 시작하기: 첫 번째 샌드박스를 사양에서 생성하세요.
- 러너 관리 API: CoreWeave API 액세스 토큰과 Sandbox Admin 역할로 러너를 관리하세요.
- 샌드박스 환경 변수: 플랫폼이 모든 컨테이너에 주입하는 내용.