API 개요

control plane은 러너와 각 러너에 적용되는 정책을 관리하는 REST API를 제공합니다. 이 페이지에서는 모든 엔드포인트에 공통으로 적용되는 behavior(인증, 버전 관리, 오류 형식, 페이지 매김)를 설명합니다. 정책의 모든 필드에 대한 스키마는 정책 레퍼런스를 참조하세요. 이러한 엔드포인트를 사용하는 작업 중심의 워크스루는 샌드박스 정책 설정하기 및 러너 배포 및 관리하기를 참조하세요.

기본 URL 및 버전 관리

https://api.coreweave.com/v1/sandbox

이것은 control plane base URL입니다. 이 URL은 이 페이지에서 설명하는 러너 엔드포인트를 호스팅하며, 이를 통해 러너를 배포하고, 각 러너에 적용할 정책을 설정하고, 상태를 쿼리할 수 있습니다. 이는 cwsandbox Python client가 샌드박스를 시작하고 명령어와 출력을 스트림하는 데 사용하는 샌드박스 data plane(Sandbox.run(), sb.exec(), 파일 오퍼레이션)과는 별개입니다. control plane 오퍼레이션은 샌드박스를 생성하는 인프라를 만들고 설정하며, data plane 오퍼레이션은 실행 중인 샌드박스와 상호 작용합니다. API 버전은 v1입니다. 하위 호환성을 유지하는 추가 변경 사항은 v1 내에서 제공됩니다. 호환성이 깨지는 변경 사항은 새 버전 접두사로 제공되며, CoreWeave는 릴리스 전에 이를 미리 공지합니다. 이전 v1beta2 API도 여전히 사용 가능하며, 프로필 템플릿과 프로필 바인딩은 이 API에서 제공됩니다. 이 기능들은 정책으로 대체되었으며 v1에는 추가되지 않습니다. 새 인테그레이션은 v1을 기준으로 구현하세요.

인증

모든 요청은 TLS를 통한 Bearer 토큰 인증을 사용합니다. [API-ACCESS-TOKEN]을 CoreWeave API 액세스 토큰으로 바꾸세요.

Authorization: Bearer [API-ACCESS-TOKEN]

cloud console의 토큰 페이지에서 API Access 토큰을 생성하세요. 토큰은 소속된 사용자의 권한을 상속하며, 서버는 모든 요청에서 해당 권한을 강제 적용합니다. CoreWeave Sandboxes에는 다음 두 가지 IAM 액션이 적용됩니다.

SANDBOX_ADMIN: 러너를 생성, 조회, 업데이트, 삭제하고, 러너가 전달하는 정책을 설정합니다. 이 페이지에 설명된 모든 엔드포인트는 조회를 포함해 이 액션이 필요합니다. SANDBOX_USER를 포함합니다.
SANDBOX_USER: 샌드박스를 생성하고 운영합니다. 이 페이지의 엔드포인트에 대한 액세스 권한은 부여하지 않습니다.

cloud console의 Access Policies 페이지에서 액션 중 하나를 부여하세요. Access Policies의 작동 방식과 단계별 부여 흐름에 대한 배경 정보는 Identity and Access Management (IAM) 및 Manage Access Policies를 참조하세요. 토큰에 대한 자세한 내용은 API 액세스 토큰 관리를 참조하세요. 인증되지 않은 요청은 google.rpc.Status 형태의 본문과 함께 401 Unauthenticated를 반환합니다. CoreWeave Intelligent CLI (cwic)는 이러한 REST 엔드포인트를 래핑합니다. CLI 사용자는 cwic auth login으로 한 번 인증하며, cwic는 토큰을 로컬 cwic 설정에 저장합니다. CLI 워크플로는 샌드박스 정책 설정를 참조하세요.

콘텐츠 유형

모든 요청 및 응답 본문은 JSON 형식입니다.

Content-Type: application/json

API는 connectrpc를 통해 HTTP/2로 실행되지만, 표준 curl 또는 fetch 스타일 클라이언트가 투명하게 작동합니다. gRPC 클라이언트는 필요하지 않습니다. 이 엔드포인트의 기반이 되는 게시된 Protobuf 정의와 이를 바탕으로 생성된 SDK는 Protobuf를 참조하세요.

리소스 패밀리

control plane은 managed runner를 관리용 리소스로 노출합니다.

패밀리	기본 경로	오퍼레이션
Managed runner	`/v1/sandbox/managedRunners`	Create, Get, List, Update, Delete, `:applyAvailableUpdate`

정책은 독립적으로 주소를 지정할 수 없습니다. 정책은 러너의 필드이므로, 러너를 가져와서 조회하고 policy로 마스킹한 러너 업데이트로 기록합니다. 쓰기 작업을 할 때마다 문서 전체가 대체됩니다. 워크플로는 Configure a sandbox policy를 참조하세요. 프로필 템플릿은 러너의 profile_bindings 필드와 함께 v1beta2 인터페이스의 /v1beta2/sandbox/profile-templates에서 계속 사용할 수 있습니다. 프로필 템플릿은 정책으로 대체되었으며, v1 모델에 포함되지 않고 앞으로도 추가되지 않습니다. 개념 모델과 게이트웨이가 런타임 요청을 중개하는 방식은 Sandboxes architecture를 참조하세요. 이 페이지에서는 엔드포인트 계약을 설명합니다.

페이지 매김

목록 엔드포인트는 커서 기반 페이지 매김을 지원합니다:

pageSize: 페이지 크기입니다. 기본값은 50, 최대 100입니다.
pageToken: 이전 페이지에서 nextPageToken으로 반환된 커서입니다. 빈 문자열은 더 이상 페이지가 없음을 의미합니다.

Paginate managed runners

curl -H "Authorization: Bearer $TOKEN" \
  'https://api.coreweave.com/v1/sandbox/managedRunners?pageSize=50'

# 커서 따르기
curl -H "Authorization: Bearer $TOKEN" \
  'https://api.coreweave.com/v1/sandbox/managedRunners?pageSize=50&pageToken=[NEXT-PAGE-TOKEN]'

CoreWeave Intelligent CLI는 cwic sandbox runner get과 같은 목록 명령어의 결과를 자동으로 페이지로 나눕니다.

업데이트 시 필드 마스크

업데이트 엔드포인트는 선택적 update_mask를 허용합니다. 존재할 경우, 마스크에 나열된 필드만 적용되며, API는 요청 객체의 다른 모든 항목을 무시합니다. 존재하지 않을 경우, 요청 객체의 모든 비어 있지 않은 변경 가능한 필드가 적용됩니다. 경로는 점 표기법과 snake_case 필드 이름을 사용합니다(표준 google.protobuf.FieldMask 규칙). 일반적으로 사용되는 변경 가능한 경로:

Path	Applies to	Purpose
`spec.release_channel`	Managed runner	릴리스 채널을 전환합니다(`RELEASE_CHANNEL_STABLE` 또는 `RELEASE_CHANNEL_RAPID`).
`spec.maintenance_policy`	Managed runner	자동 업데이트 유지 관리 윈도우를 조정합니다.
`spec.overrides`	Managed runner	러너 파드의 tolerations, 노드 셀렉터, 런타임 클래스를 조정합니다.
`spec.enforce_resource_limits`	Managed runner	러너의 샌드박스가 CPU와 메모리 limits를 선언하도록 강제 적용합니다.
`policy`	Managed runner	전체 정책 문서를 교체합니다. policy에 대해 구현된 유일한 마스크 경로입니다.
`profile_bindings`	Managed runner	profile bindings의 전체 목록을 교체합니다. 레거시이며, `v1beta2` 전용입니다. `v1` 쓰기에서는 거부됩니다.

REST 표면에서, 마스크를 단일 쉼표로 구분된 updateMask 쿼리 매개변수로 제공하고, 각 경로의 JSON (camelCase) 형식을 사용하며, 리소스 자체를 래퍼 없이 요청 본문으로 전송합니다:

curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/[RUNNER-ID]?updateMask=spec.releaseChannel,spec.maintenancePolicy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "spec": { "releaseChannel": "RELEASE_CHANNEL_RAPID" } }'

per-endpoint 레퍼런스는 각 리소스에 대한 변경 가능한 경로를 나열합니다.

오류

오류는 적절한 HTTP 상태 코드와 google.rpc.Status 본문을 반환합니다.

{
  "code":    3,
  "message": "runner.identity.zone is required",
  "details": []
}

다음 table에는 일반적인 매핑이 나와 있습니다.

HTTP	`code`	의미
400	3 (`INVALID_ARGUMENT`)	필수 필드가 누락되었거나, 입력 형식이 잘못되었거나, 사양이 유효하지 않습니다.
401	16 (`UNAUTHENTICATED`)	API 토큰이 없거나 유효하지 않습니다.
403	7 (`PERMISSION_DENIED`)	토큰에 해당 액션을 수행하는 데 필요한 권한이 없습니다.
404	5 (`NOT_FOUND`)	리소스가 존재하지 않습니다.
409	6 (`ALREADY_EXISTS`)	`displayName` 또는 `runnerId`가 중복되었거나, 동일한 클러스터에 두 번째 러너를 생성하려고 했습니다.
503	14 (`UNAVAILABLE`)	의존성(예: 클러스터 검증)을 일시적으로 사용할 수 없습니다. 안전하게 재시도할 수 있습니다.
500	13 (`INTERNAL`)	예기치 않은 서버 오류입니다. 지수 백오프를 적용하여 재시도하세요.

검증 메시지는 안정적으로 유지되는 인터페이스의 일부이므로 최종 사용자에게 그대로 표시해도 됩니다.

멱등성

control plane API는 다음과 같은 멱등성을 보장합니다.

Delete* 엔드포인트는 멱등성을 가집니다. 이미 삭제된 리소스에 DELETE를 호출하면 부작용 없이 404를 반환합니다.
Create* 엔드포인트는 멱등성을 가지지 않습니다. 동일한 runnerId 또는 displayName을 두 번 지정하면 409 Conflict를 반환합니다. 안전하게 재시도하려면 GET으로 리소스가 이미 존재하는지 먼저 확인하세요.
Update* 엔드포인트는 필드 마스크를 사용하여 변경하려는 필드만 설정하면 안전하게 재시도할 수 있습니다.

Heartbeats

러너 heartbeats는 러너 liveness를 추적합니다. control plane이 liveness 윈도우 내에 heartbeat를 수신하지 못하면, 러너의 connectionStatus가 DISCONNECTED로 전환됩니다. 러너가 연결 불가능해진 시점과 control plane이 이를 반영하는 시점 사이에 최대 30초의 지연이 발생할 수 있습니다. 러너 조회 응답에서 connectionStatus와 관련 installStatus 필드를 모두 조회할 수 있습니다.

참고 항목

샌드박스 아키텍처: 네 가지 리소스 분류 체계와 게이트웨이가 런타임 요청을 중개하는 방식을 설명합니다.
정책 개요: 샌드박스가 정책에 따라 어떻게 결정되는지 설명합니다.
샌드박스 정책 설정: CoreWeave Intelligent CLI 워크플로와 프로필 사양의 필드별 워크스루를 제공합니다.
러너 배포 및 관리: 러너 라이프사이클에 대한 CoreWeave Intelligent CLI 및 REST 워크스루를 제공합니다.
정책 레퍼런스: 프로필에 설정할 수 있는 모든 필드를 설명합니다.
Protobuf: 게시된 Protobuf 모듈의 위치, 각 서비스를 제공하는 호스트, 생성된 SDK의 설치 방법을 설명합니다.

샌드박스

샌드박스 사용하기

샌드박스 관리

레퍼런스

기본 URL 및 버전 관리

인증

콘텐츠 유형

리소스 패밀리

업데이트 시 필드 마스크

오류

멱등성

Heartbeats

참고 항목

​기본 URL 및 버전 관리

​인증

​콘텐츠 유형

​리소스 패밀리

​페이지 매김

​업데이트 시 필드 마스크

​오류

​멱등성

​Heartbeats

​참고 항목

기본 URL 및 버전 관리

인증

콘텐츠 유형

리소스 패밀리

페이지 매김

업데이트 시 필드 마스크

오류

멱등성

Heartbeats

참고 항목