Skip to main content
이 가이드는 리소스, 마운트된 파일, 포트, 어노테이션, timeout을 포함한 샌드박스 설정 옵션을 다룹니다. 워크로드의 요구 사항에 맞게 샌드박스의 런타임 환경을 조정해야 할 때(예: GPU 용량 예약, 서비스 노출, 오퍼레이션 timeout 설정) 레퍼런스로 사용하세요. 이 페이지는 cwsandbox Python SDK를 사용하여 샌드박스를 시작하고 관리하는 개발자를 위한 것입니다.

인증 선택

섹션에서 CKS를 지정하지 않는 한 이 예시는 서버리스 용량에서 실행됩니다. 샌드박스를 소유한 계정의 사용자 인증 정보를 선택하세요. 키 또는 토큰을 획득하려면 사용자 인증 정보 선택 및 조회를 참조하세요. 설치 명령어는 활성화된 Python 가상 환경에서 실행하세요. 사용 중인 사용자 인증 정보 탭의 Python 코드를 sandbox_auth.py로 저장하고, 이 페이지에서 실행할 Python script와 같은 위치에 두세요. 이 파일에는 사용자 인증 정보 자체가 아니라 어떤 인증 방식을 사용할지만 저장됩니다. 예시에서는 이 파일에서 AUTH를 임포트한 뒤 새 샌드박스나 세션을 만들 때마다 명시적으로 전달합니다.
SDK의 W&B 인증 전략으로 Forge API 키를 사용하세요.
sandbox_auth.py
CKS 배치를 사용하려면 CoreWeave 토큰을 선택하고 러너를 활성화한 다음, 샌드박스를 생성할 때 또는 SandboxDefaults에서 placement_mode="cks"를 설정하세요. auth=AUTH로 세션을 생성하면 해당 세션이 소유한 샌드박스도 함께 인증됩니다. 샌드박스에 다시 연결하거나 목록을 조회하거나 정리할 때도 동일한 사용자 인증 정보를 사용하세요.

개요

샌드박스 설정은 세 곳에서 지정할 수 있으며, 범위가 가장 넓은 것부터 가장 구체적인 것 순으로 나열하면 다음과 같습니다.
  • SandboxDefaults: 세션 내 모든 샌드박스에 공통으로 적용되는 기본값입니다.
  • Sandbox.run() kwargs: 샌드박스별로 기본값을 재정의합니다.
  • @session.function() kwargs: 함수별 설정입니다.
다음 섹션에서는 각 설정 영역을 상세히 설명합니다.

리소스

ResourceOptions dataclass 또는 일반 딕셔너리를 사용하여 CPU, 메모리, GPU 리소스를 설정하세요. 서버리스는 기본 배치 모드입니다. 서버리스 샌드박스에서는 CPU와 메모리의 요청량과 제한을 동일하게 설정하세요. 요청량과 제한이 다른 경우, 이를 허용하는 정책을 가진 러너와 함께 CKS 배치를 사용하세요. 적절한 값을 선택하는 방법은 샌드박스 CPU 및 메모리 사이징을 참조하세요. 서버리스가 서로 다른 값을 알아서 맞춰 줄 것이라고 기대하지 마세요. 요청량과 제한이 다른 상태로 생성에 성공했더라도 리소스 버스팅이 지원된다는 뜻은 아닙니다. 다음 예시에서는 동일한 요청량과 제한을 사용합니다:
두 형식은 동일합니다: SDK는 내부적으로 dict를 ResourceOptions로 자동 변환합니다. ResourceOptions는 리소스 요청량과 제한을 분리합니다. 요청량은 스케줄러에게 샌드박스가 필요한 것을 알려줍니다. 제한은 사용할 수 있는 최대치를 설정합니다. Kubernetes가 요청량과 제한을 사용하여 Quality of Service classes를 부여하는 방법에 대한 배경 지식은 Kubernetes 문서를 참조하세요.

ResourceOptions 필드

클라이언트에서는 모든 필드가 선택이며 기본값은 None입니다. 최종 확정된 할당은 적용되는 정책을 충족해야 합니다. 리소스 할당을 생략하면 해당 정책에 정의된 완전한 양수 CPU 및 메모리 기본값이 요청량과 제한으로 모두 사용됩니다.

Guaranteed QoS

Guaranteed Quality of Service는 파드에 있는 모든 컨테이너의 리소스에 따라 결정됩니다. 컨테이너 수준 할당을 사용하는 경우, 모든 컨테이너에 0보다 큰 CPU 및 메모리 요청량을 설정하고, 각 리소스의 제한을 요청량과 동일하게 설정해야 합니다. 이는 init 컨테이너와 사이드카에도 적용됩니다. 워크로드 컨테이너에만 값을 동일하게 설정해서는 샌드박스 파드 전체의 QoS 클래스가 결정되지 않습니다. 다만 제한보다 많은 CPU를 사용하려는 샌드박스는 이 경우에도 스로틀링됩니다.
요청량과 제한이 같은 경우 평면 dict 단축 표현이 사용 가능합니다. SDK는 요청량과 제한을 모두 동일한 값으로 설정하여 평면 dict를 정규화합니다.

Burstable QoS

CKS 러너의 정책이 요청량과 제한을 다르게 허용하는 경우, 낮은 요청량은 샌드박스에 Burstable Quality of Service 클래스를 부여합니다. 낮은 요청량을 사용하면 스케줄러가 더 많은 샌드박스를 bin-pack할 수 있지만, 각 샌드박스는 용량이 사용 가능하다면 limit까지 burst할 수 있습니다. 자체 컴퓨팅 사용을 완료하고 CWSANDBOX_API_KEY를 CoreWeave API 액세스 토큰으로 설정하세요. [RUNNER-ID]를 요청량과 제한을 허용하는 CKS 러너의 ID로 교체하세요:

CPU 값

CPU를 밀리코어 또는 전체 코어 단위로 지정하세요. 자세한 내용은 Kubernetes의 리소스 단위를 참조하세요.

메모리 값

메모리는 표준 Kubernetes 메모리 단위를 사용합니다:

GPU

CPU 및 메모리와 함께 GPU 리소스를 요청하세요. GPU 요청은 GPU만 예약하므로 CPU와 메모리를 명시적으로 설정하세요.
GPU 설정 키: type과 memory_gb는 대안입니다. 둘 중 하나만 설정하세요.

Inspect confirmed resources

샌드박스가 시작된 후, 확인된 리소스 할당을 검사하세요. 이 예제는 CKS에서 불균등한 requests와 limits를 사용합니다. CKS 설정을 완료하고 CWSANDBOX_API_KEY를 CoreWeave API access token으로 설정하세요. [RUNNER-ID]를 GPU 용량이 있고 이러한 리소스를 허용하는 정책이 있는 CKS 러너의 ID로 교체하세요:

설정 라이브러리 상호 운용성

모든 설정 유형(NetworkOptions, Secret, ResourceOptions)은 dataclass 또는 일반 딕셔너리를 허용합니다. 이는 설정을 dict 또는 dict-like 객체로 해결하는 ML 설정 라이브러리가 수동 변환 없이 SDK에 값을 직접 전달할 수 있음을 의미합니다. SandboxDefaults.from_dict()는 일반 딕셔너리 또는 OmegaConf DictConfig를 허용하며 중첩된 필드를 자동으로 강제 변환합니다. 네트워크 및 시크릿 설정은 해당 SDK 유형으로 변환하고, 리소스 매핑은 일반 딕셔너리로 변환합니다. 이후 SDK는 샌드박스를 생성할 때 이 리소스 dict를 ResourceOptions로 정규화합니다.
개별 필드는 Sandbox.run() 또는 session.sandbox()에 직접 전달할 때 dict도 허용합니다. 리소스에 대한 중첩 dict 형식은 ResourceOptions 필드에 매핑됩니다. 평면 dict 형식({"cpu": "1", "memory": "1Gi"})은 워크로드 컨테이너의 CPU 및 메모리 요청량과 제한을 동일한 값으로 설정합니다. 이 경우에도 Guaranteed QoS 요구 사항은 파드의 모든 컨테이너에 적용됩니다.

마운트된 파일

마운트된 파일을 사용하면 시작 시 샌드박스에 설정 파일, 스크립트 또는 기타 읽기 전용 에셋을 제공할 수 있으며, 이를 컨테이너 이미지에 포함하지 않아도 됩니다.

마운트 옵션

마운트된 파일은 읽기 전용입니다. 수정이 필요한 파일에는 write_file()을 사용하세요.

포트

services=[Service(...)]로 포트를 선언하세요. visibility와 endpoint를 모두 설정하지 않은 Service(port=8080, name="web") 같은 선언은 컨테이너 내부에서만 사용되며 외부 노출을 요청하지 않습니다. 인터넷 클라이언트에 HTTP를 서빙하려면 공개 HTTPS 엔드포인트를 요청하세요. 이 예제는 서버리스 용량에서 실행되며, 포트 8080에서 HTTP 서버를 시작한 다음 로컬 머신에서 부여된 HTTPS URL로 요청을 보냅니다. 플랫폼이 TLS를 종료하고 HTTP를 컨테이너 포트로 전달합니다. 이 예제는 EndpointAuth.OPEN을 사용하므로 URL을 아는 사람은 누구나 사용자 인증 정보 없이 액세스할 수 있습니다. 또한 데모 컨테이너의 /tmp 디렉터리를 문서 루트로 사용합니다. auth=AUTH로 전달하는 사용자 인증 정보는 샌드박스 생성 및 삭제 권한을 부여하는 데 사용되며, 이 OPEN 엔드포인트에 요청을 보낼 때는 필요하지 않습니다.
이 스크립트는 URL과 HTTP 서버가 준비 완료될 때까지 재시도하고, 성공하면 HTTP 200: directory listing received를 출력하며, 액세스 시도가 끝나면 샌드박스를 삭제합니다. 또한 5분의 수명 제한이 있으므로 샌드박스는 최대 5분까지만 실행됩니다. ports 매개변수는 cwsandbox 1.x에서 제거되었습니다. 값을 전달하면 TypeError가 발생합니다. 대신 services=[Service(...)]를 사용하세요.

서비스 필드

각 sandbox.service_urls 항목은 (port, name, url) 튜플입니다. 샌드박스가 아직 CREATING 상태여도 URL이 표시될 수 있습니다. URL이 부여되었다고 해서 애플리케이션이 수신 대기 중이라는 보장은 없습니다. 일반 서비스에는 endpoint 값이 없습니다. 하나의 샌드박스에서 일반 서비스와 엔드포인트를 함께 사용할 때의 규칙은 엔드포인트 선언을 참조하세요. HTTPS에서 EndpointAuth.OPEN은 인증 없는 액세스를 허용합니다. EndpointAuth.SHARE_TOKEN을 사용하려면 생성 시 반환되는 공유 토큰, Python SDK 1.16.0 이상, 그리고 공유 토큰 HTTPS를 지원하는 배포가 필요합니다. TLS 패스스루에서는 엔드포인트 인증이 설정되지 않으며, TLS 종료와 액세스 제어는 워크로드에서 직접 처리합니다. 엔드포인트 라우팅과 인증에 대한 자세한 내용은 공개 엔드포인트를 참조하세요. 자동 생성된 Service 레퍼런스와 Endpoint 레퍼런스는 SDK 버전 1.14.2를 기준으로 합니다. 이 버전은 OPEN은 지원하지만 SHARE_TOKEN이 도입되기 이전 버전입니다.

네트워크

NetworkOptions dataclass나 일반 딕셔너리를 사용해 아웃바운드 및 인바운드 트래픽을 설정하세요. 이그레스 및 ingress 규칙은 기본적으로 모든 트래픽을 거부하는 베이스라인에 액세스 권한을 추가로 부여합니다. 비어 있지 않은 egress 목록을 지정하면 러너 정책의 기본 대상 권한 부여를 대체합니다. 호스트 이름 기반 권한 부여를 사용하려면 호스트 이름 기반 HTTPS 이그레스를 지원하는 러너와 요청한 모든 대상을 허용하는 정책이 필요합니다. CKS 배치의 경우 Admin에게 러너의 네트워크 제약 조건을 확인해 달라고 요청하세요. 서버리스 배치의 경우 CoreWeave가 풀과 풀의 정책을 관리합니다. 풀에서 이러한 호스트 이름 규칙을 거부하는 경우 CoreWeave 지원팀에 문의하세요. PyPI에서 패키지를 다운로드하려면 패키지 인덱스용 pypi.org와 패키지 파일용 files.pythonhosted.org를 모두 허용하세요. pypi.org 및 *.pypi.org 권한 부여에는 files.pythonhosted.org가 포함되지 않습니다.
두 형식은 동일하게 동작합니다. SDK가 내부적으로 dict를 NetworkOptions로 자동 변환하기 때문입니다.

NetworkOptions 필드

모든 필드는 선택 사항이며 기본값은 None입니다. 규칙 목록이 비어 있고 해당 거부 플래그가 설정되지 않았거나 False이면 러너 정책 기본값이 적용됩니다. 포트 노출은 NetworkOptions가 아니라 services로 설정합니다. EgressRule 및 IngressRule의 전체 필드는 네트워크 규칙을 참조하세요. EgressRule에는 dns_name, cidr, tenant, any, selector 중 정확히 하나의 대상을 지정해야 합니다. DNS 권한 부여에는 정확한 이름을 지정하거나, *.pypi.org처럼 맨 왼쪽에 와일드카드 하나만 사용한 이름을 지정할 수 있습니다. IngressRule에는 cidr, tenant, any 중 정확히 하나의 소스를 지정해야 합니다. egress_mode, ingress_mode, exposed_ports 필드는 cwsandbox 1.x에서 지원되지 않습니다. 대신 위의 필드를 사용하고, 포트는 services로 선언하세요. deny_egress=True가 완전한 네트워크 격리를 의미하지는 않습니다. 플랫폼에 필요한 트래픽은 계속 허용될 수 있으며, 아웃바운드 DNS는 별도로 제어됩니다. Python NetworkOptions 유형은 dnsEgress를 노출하지 않습니다. 이 모드를 변경하려면 NetworkConfig API를 사용하세요(지원되는 경우).
Python SDK는 샌드박스를 생성할 때 네트워크 옵션을 적용하며, 실행 중인 샌드박스의 네트워크 정책을 업데이트하는 메서드는 제공하지 않습니다. API 워크플로는 동적 네트워크 정책을 참조하세요. 노출된 포트와 서비스 공개 범위는 생성 시점에만 설정할 수 있습니다.

SandboxDefaults에서 네트워크 설정

모든 샌드박스에 대한 기본 네트워크 설정을 설정하세요:
샌드박스별 network는 SandboxDefaults.network 값과 병합되지 않고 해당 값을 대체합니다. 위 예시에서 sb3는 대상 권한 부여를 차단하며, DNS는 계속 별도로 제어됩니다.

어노테이션

샌드박스에 Kubernetes 파드 어노테이션을 추가하세요. 어노테이션은 기본 파드에 연결된 키-값 문자열 쌍으로, 스케줄러, 비용 할당 도구 또는 외부 자동화와 같이 파드 메타데이터를 조회하는 인테그레이션에 유용합니다.

세션 수준 기본값

세션의 모든 샌드박스에 대한 기본 어노테이션을 설정하세요:

병합 동작

SandboxDefaults.annotations와 샌드박스별 annotations를 모두 제공하면 SDK가 이를 병합합니다. 키 충돌 시 명시적인 샌드박스별 값이 우선하며, 이는 environment_variables와 동일한 의미 체계를 따릅니다.

SUNK 인테그레이션

SUNK 인테그레이션을 위해 Slurm 컨텍스트를 파드 어노테이션으로 전달하려면 SUNK Pod Scheduler 인테그레이션 가이드를 참조하세요.

검증

SDK는 어노테이션 키나 값을 검증하지 않습니다. 서버는 예약된 키 접두사, 값 형식, 최대 엔트리 수에 대한 검증을 처리합니다.

시크릿

Forge 팀 시크릿 주입, 인증 요구 사항 및 Python과 TypeScript 예시에 대해서는 Forge 시크릿 사용을 참조하세요.

timeout

샌드박스와 그 오퍼레이션이 실행되는 시간을 제어하는 세 가지 설정이 있습니다. 이름이 비슷하므로 다음 table은 각 설정이 무엇을 제한하는지 매핑합니다. max_lifetime_seconds만 샌드박스를 종료합니다. 나머지 두 가지는 개별 요청을 제한하고 샌드박스는 계속 실행되도록 둡니다. max_timeout_seconds 매개변수는 cwsandbox 1.x에서 제거되었습니다. 이 매개변수에 값을 전달하면 TypeError가 발생하므로, 클라이언트 요청 timeout을 설정하려면 request_timeout_seconds를 사용하세요.

max_lifetime_seconds

max_lifetime_seconds는 샌드박스의 전체 wall-clock 수명을 설정합니다. 샌드박스가 이 나이에 도달하면, 작업이 진행 중이더라도 플랫폼이 샌드박스를 종료합니다. max_lifetime_seconds를 설정하지 않으면 러너 정책의 기본값이 적용됩니다. 정책 기본값에 양수 수명이 지정되어 있지 않으면 플랫폼은 10분을 사용합니다. 오래 실행되는 작업에는 값을 명시적으로 설정하세요:
세션이 생성하는 모든 샌드박스에 동일한 수명을 적용하려면 SandboxDefaults에서 설정하세요:
Sandbox.run()의 명시적인 max_lifetime_seconds 인수는 defaults의 값보다 우선합니다. 인수의 기본값이 None이므로, defaults에 이미 설정된 수명을 제거하는 데 이 인수를 사용할 수 없습니다. 요청할 수 있는 수명은 서버리스 배치와 CKS 배치 모두 30일(2,592,000초)입니다. 플랫폼은 이보다 긴 요청을 거부합니다.
샌드박스가 시작된 후에는 max_lifetime_seconds를 변경할 수 없습니다. 실행 중인 샌드박스의 수명을 연장하는 API는 없으므로, 생성할 때 값을 선택하세요. 제한 시간을 넘어서도 작업을 계속하려면 필요한 내용을 캡처하고 수명을 30일 이내로 설정한 새 샌드박스를 시작하세요.
생성 예시와 CKS 러너 정책 기본값은 장기 실행 샌드박스 실행을 참조하세요.

수명 만료 시 동작

플랫폼은 샌드박스의 기반 Kubernetes Job에 기한을 설정하는 방식으로 수명을 강제 적용합니다. 기한에 도달하면 작업이 아직 진행 중이더라도 워크로드 종료가 트리거됩니다. 만료되기 전에 결과나 체크포인트를 샌드박스 외부에 저장하세요. Python SDK는 백엔드가 보고한 사유를 Sandbox.status_reason으로 제공하며, 이 값은 가장 최근의 API 응답을 기준으로 캐시됩니다. 수명이 만료되면 사유가 DeadlineExceeded로 시작할 수 있습니다. SDK에서 SandboxFailedError 예외가 발생하면 해당 예외의 status_reason 속성에도 백엔드가 보고한 사유가 담깁니다. 사유가 비어 있을 수도 있으므로 장시간 실행되는 샌드박스는 경과 시간도 함께 추적하세요. 수명은 예상 작업 시간보다 넉넉하게 설정하세요. 작업을 마치면 만료에 의존하지 말고 샌드박스를 명시적으로 중지하세요.

timeout_seconds

timeout_seconds는 실행 중인 샌드박스에서 단일 오퍼레이션의 시간 제한을 설정합니다:
클라이언트가 응답을 기다리는 시간을 제어합니다. 대기 시간이 timeout을 초과하면 SDK는 SandboxTimeoutError 예외를 발생시킵니다. 샌드박스는 계속 실행됩니다. 시간 측정은 샌드박스가 RUNNING 상태에 도달한 후에만 시작되므로 시작 시간은 포함되지 않습니다. timeout_seconds를 샌드박스의 max_lifetime_seconds보다 낮게 설정하세요. timeout이 샌드박스의 남은 최대 실행 시간을 초과하는 명령은 샌드박스가 종료될 때 중지됩니다.

request_timeout_seconds

request_timeout_seconds는 대부분의 RPC에 적용되는 클라이언트 측 HTTP timeout이며, 호출에 자체 timeout_seconds가 전달되지 않으면 이 값이 대신 사용됩니다. SandboxDefaults에서 설정하세요.
반면 상태 폴링에는 poll_rpc_timeout_seconds가 사용되므로, 응답이 멈춘 폴링은 전체 요청 timeout 동안 차단되지 않고 빠르게 실패합니다. 클라이언트 측 튜닝 옵션 전체 목록은 SandboxDefaults 레퍼런스를 참조하세요.

전체 예제

다음 예시는 기본값, 샌드박스별 재정의, 마운트된 파일, 서비스 선언을 결합합니다. PyPI에서 패키지를 다운로드한 다음 임포트하여 설치 여부를 확인합니다. 서버리스 풀은 호스트 이름 허용 요구 사항을 충족해야 합니다. 이 예제는 서비스 포트를 선언하지만 서버를 시작하거나 공개 엔드포인트를 생성하지는 않습니다.
마지막 수정일 2026년 11월 4일