> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SandboxDefaults
> 샌드박스 생성을 위한 변경 불가능한 기본 설정입니다.
소스: [src/cwsandbox/\_defaults.py:261](https://github.com/coreweave/cwsandbox-client/blob/v1.14.2/src/cwsandbox/_defaults.py#L261)
```python theme={"system"}
class SandboxDefaults(container_image: str = DEFAULT_CONTAINER_IMAGE, command: str = DEFAULT_COMMAND, args: tuple[str, ...] = DEFAULT_ARGS, base_url: str = DEFAULT_BASE_URL, auth: AuthConfig | None = None, request_timeout_seconds: float = DEFAULT_REQUEST_TIMEOUT_SECONDS, poll_retry_budget_seconds: float = DEFAULT_POLL_RETRY_BUDGET_SECONDS, poll_rpc_timeout_seconds: float = DEFAULT_POLL_RPC_TIMEOUT_SECONDS, max_lifetime_seconds: float | None = DEFAULT_MAX_LIFETIME_SECONDS, temp_dir: str = DEFAULT_TEMP_DIR, tags: tuple[str, ...] = tuple(), runner_ids: tuple[str, ...] | None = None, placement_mode: PlacementMode | str | None = None, placement_spillover: PlacementSpillover | str = PlacementSpillover.STRICT, resources: ResourceOptions | dict[str, Any] | None = None, network: NetworkOptions | None = None, services: tuple[Service, ...] | None = None, volumes: tuple[ScratchVolumeOptions | RegisteredVolumeOptions, ...] | None = None, runtime_class: str | None = None, security_context: SecurityContext | dict[str, Any] | None = None, working_dir: str | None = None, object_storage_access: ObjectStorageAccess | dict[str, Any] | None = None, file_system_snapshot: FileSystemSnapshotOptions | dict[str, Any] | None = None, containers: tuple[Container, ...] | None = None, secrets: tuple[Secret, ...] | None = None, environment_variables: dict[str, str] = dict(), annotations: dict[str, str] = dict(), data_plane_mode: DataPlaneMode | str = DataPlaneMode.AUTO)
```
샌드박스 생성을 위한 불변 설정 기본값입니다.
모든 필드에는 적절한 기본값이 지정되어 있습니다. 필요한 항목만 재정의하세요.
timeout에는 서로 다른 두 가지 개념이 있습니다:
* request\_timeout\_seconds: API 응답을 기다리는 시간 (클라이언트 측)
* max\_lifetime\_seconds: 샌드박스가 자동으로 종료되기 전까지 실행되는 시간 (서버 측)
설정하지 않으면 백엔드에서 기본 실행 시간을 결정합니다.
태그를 사용하면 샌드박스를 필터링하고 정리할 수 있습니다. 태그는
백엔드로 전달되며, 태그를 기준으로 샌드박스를 쿼리하는 데 사용할 수 있습니다.
**속성**
* `container_image` (`str`) : 샌드박스 컨테이너에 사용할 도커 이미지입니다. 기본값: `DEFAULT_CONTAINER_IMAGE`.
* `command` (`str`) : 실행할 엔트리포인트 명령입니다. 기본값: `DEFAULT_COMMAND`.
* `args` (`tuple[str, ...]`) : 명령에 전달되는 인수입니다. 기본값: `DEFAULT_ARGS`.
* `base_url` (`str`) : CWSandbox API endpoint URL입니다. 기본값: `DEFAULT_BASE_URL`.
* `auth` (`AuthConfig | None`) : 인증 방식을 선택합니다. `AuthStrategy`, 확인된
`AuthHeaders` 또는 `AuthProvider`를 받습니다. `None`이면 레거시
프로세스 전역 재정의가 설치된 경우 이를 유지하고, 그렇지 않으면
`AuthStrategy.COREWEAVE_API_KEY`를 사용합니다. 기본값: `field(default=None, repr=False)`.
* `request_timeout_seconds` (`float`) : 대부분의 RPC에 적용되는 클라이언트 측 HTTP timeout(초)입니다.
폴링 조회 RPC에는 이 값 대신 `poll_rpc_timeout_seconds`가 적용됩니다. 기본값: `DEFAULT_REQUEST_TIMEOUT_SECONDS`.
* `poll_retry_budget_seconds` (`float`) : 재시도 버스트(안정 상태에 도달하기까지의 한 번의 과정)당
허용되는 실제 경과 시간 예산입니다. 예산은 응답이 성공할 때마다 초기화되므로,
오래 실행되는 샌드박스가 일시적 오류에서 복구된 뒤 한참 후에
다시 오류가 발생하더라도 매번 새 예산을 받습니다. 재시도 대상인
일시적 오류 코드는 UNAVAILABLE, DEADLINE\_EXCEEDED,
RESOURCE\_EXHAUSTED입니다. 재시도를 완전히 비활성화하려면 0.0으로 설정하세요. 기본값: `DEFAULT_POLL_RETRY_BUDGET_SECONDS`.
* `poll_rpc_timeout_seconds` (`float`) : 폴링 조회 RPC의 호출당 timeout입니다.
`request_timeout_seconds`와 별도로 관리되므로, 멈춘 폴링이 더 긴
요청 timeout 동안 대기하지 않고 빠르게 실패합니다. 기본값: `DEFAULT_POLL_RPC_TIMEOUT_SECONDS`.
* `max_lifetime_seconds` (`float | None`) : 서버 측 샌드박스 수명 제한(초)입니다.
None이면 백엔드가 기본값을 결정합니다. 기본값: `DEFAULT_MAX_LIFETIME_SECONDS`.
* `temp_dir` (`str`) : 샌드박스 내부의 임시 디렉터리 경로입니다. 기본값: `DEFAULT_TEMP_DIR`.
* `tags` (`tuple[str, ...]`) : 샌드박스를 필터링하고 정리하는 데 사용하는 태그입니다. 기본값: `field(default_factory=tuple)`.
* `runner_ids` (`tuple[str, ...] | None`) : 특정 러너 ID(CKS)로 제한합니다. 기본값을 명시적으로
지우려면 빈 목록을 전달하고, 설정된 기본값을 상속하려면 None(기본값)을
전달하세요. serverless 배치와 함께 사용할 수 없습니다.
* `placement_mode` (`PlacementMode | str | None`) : `PlacementMode`(`serverless` / `cks`) 또는 문자열입니다.
* `placement_spillover` (`PlacementSpillover | str`) : 기본(primary) 모드가 스필 가능한 용량/배치 사유로
실패했을 때 대체 모드에서 생성을 한 번 재시도할지 결정하는 `PlacementSpillover` 정책입니다.
기본값은 `STRICT`(스필 없음)입니다. 템플릿
샌드박스에는 `STRICT`를 사용해야 합니다. 기본값: `PlacementSpillover.STRICT`.
* `resources` (`ResourceOptions | dict[str, Any] | None`) : 리소스 설정입니다. requests/limits를 별도로 지정하려면 `ResourceOptions`를,
이전 버전과 호환되는 Guaranteed QoS를 사용하려면 평면 dict를 전달하세요.
* `network` (`NetworkOptions | None`) : `NetworkOptions`로 지정하는 거부 플래그 네트워크 옵션 및 선택적 생성 시점 호스트 이름
허용 설정입니다.
* `services` (`tuple[Service, ...] | None`) : PUBLIC/PRIVATE/CUSTOM용 타입 지정 서비스 포트(`Service`)입니다.
* `volumes` (`tuple[ScratchVolumeOptions | RegisteredVolumeOptions, ...] | None`) : 스크래치 볼륨 또는 등록된 볼륨(`ScratchVolumeOptions` 또는
`RegisteredVolumeOptions`)입니다.
* `runtime_class` (`str | None`) : 고정할 runtime-class입니다(선택, 예: `"gvisor"`).
* `security_context` (`SecurityContext | dict[str, Any] | None`) : 단일 컨테이너 경로의 게스트 내부 권한입니다.
`containers=` 또는 `defaults.containers`를 사용하는 경우에는 적용되지 않습니다.
* `working_dir` (`str | None`) : 단일 컨테이너 경로의 작업 디렉터리입니다.
컨테이너 목록을 사용하는 경우에는 적용되지 않습니다.
* `object_storage_access` (`ObjectStorageAccess | dict[str, Any] | None`) : 임시 오브젝트 스토리지 자격 증명입니다.
* `file_system_snapshot` (`FileSystemSnapshotOptions | dict[str, Any] | None`) : `FileSystemSnapshotOptions`로 지정하는 편의용 단일 마운트 FSS
옵션입니다. 공유 가능한 마운트 기본값(mount\_path,
size)이며, `run()`에 값을 명시하면 이 값 전체가 대체됩니다. 여러 볼륨을
구성할 때는 `volumes=`를 사용하는 것이 좋습니다.
* `containers` (`tuple[Container, ...] | None`) : 선택적 다중 container 사양 (`Container`). `Sandbox.run()`의 단일 container 필드와
상호 배타적입니다.
이 목록을 사용하면 `secrets`, `environment_variables`,
`security_context`, `working_dir`는 이러한 defaults에
적용되지 않습니다. 각 `Container`에 설정하세요.
* `secrets` (`tuple[Secret, ...] | None`) : 단일 container 경로의 시크릿입니다. `containers=` 또는
`defaults.containers`를 사용할 때는 적용되지 않습니다.
* `environment_variables` (`dict[str, str]`) : 단일 container 경로의
환경 변수입니다. container 목록을 사용할 때는 적용되지 않습니다. Default: `field(default_factory=dict)`.
* `annotations` (`dict[str, str]`) : Kubernetes 파드 어노테이션 (키-값 문자열 쌍).
샌드박스별 어노테이션과 병합되며, 명시적 값은 defaults를 오버라이드합니다.
민감하지 않은 메타데이터에만 사용하세요. Default: `field(default_factory=dict)`.
* `data_plane_mode` (`DataPlaneMode | str`) : exec, logs, file operations에 대한 Transport policy.
`auto` (default)는 direct mTLS를 우선하고 게이트웨이로 폴백합니다.
`gateway`는 직접 액세스를 비활성화합니다. `direct`는 이를 요구합니다. Default: `DataPlaneMode.AUTO`.
메서드
```python theme={"system"}
merge_tags(additional: Iterable[str] | None) -> list[str]
```
기본 태그와 추가 태그를 결합합니다.
두 소스의 태그가 모두 포함됩니다. 순서는: defaults가 먼저,
그 다음에 additional 태그가 추가됩니다.
merge\_environment\_variables
```python theme={"system"}
merge_environment_variables(additional: dict[str, str] | None) -> dict[str, str]
```
기본 환경 변수를 추가 환경 변수와 결합합니다.
추가 환경 변수는 동일한 키를 가진 기본값을 재정의합니다.
merge\_annotations
```python theme={"system"}
merge_annotations(additional: dict[str, str] | None) -> dict[str, str]
```
기본 어노테이션과 추가 어노테이션을 병합합니다.
추가 어노테이션은 키가 같은 기본값을 재정의합니다.
with\_overrides
```python theme={"system"}
with_overrides(**kwargs: Any = {}) -> SandboxDefaults
```
일부 값을 재정의한 새 기본값을 생성합니다.
from\_dict
```python theme={"system"}
from_dict(d: Mapping[str, Any] | None) -> SandboxDefaults
```
매핑을 기반으로 `SandboxDefaults`를 구축하면서 중첩된 필드의 타입을 강제 변환합니다.
일반 딕셔너리 또는 OmegaConf `DictConfig` 객체를 허용합니다. 알 수 없는
키는 별도의 알림 없이 무시되므로 호출자는 추가 필드가 포함된 설정 섹션을 전달할 수 있습니다.
적용되는 강제 변환:
* `network` 딕셔너리 -> `NetworkOptions`
* `secrets` 딕셔너리 목록 -> `Secret` 튜플
* `services` 딕셔너리 목록 -> `Service` 튜플
* `volumes` 딕셔너리 목록 -> 스크래치/등록된 볼륨 옵션 튜플
* `containers` 딕셔너리 목록 -> `Container` 튜플
* `security_context` 딕셔너리 -> `SecurityContext`
* `object_storage_access` 딕셔너리 -> `ObjectStorageAccess`
* `args`, `tags`, `runner_ids`, `services`, `volumes`,
`containers` 목록 -> 튜플
* `resources`, `environment_variables` -> 일반 `dict`