SandboxDefaults

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)

• request_timeout_seconds: How long to wait for API responses (client-side)
• max_lifetime_seconds: How long the sandbox runs before auto-termination (server-side) If not set, the backend controls the default lifetime.

• container_image (str) : Docker image for the sandbox container. Default: DEFAULT_CONTAINER_IMAGE.
• command (str) : Entrypoint command to run. Default: DEFAULT_COMMAND.
• args (tuple[str, ...]) : Arguments passed to the command. Default: DEFAULT_ARGS.
• base_url (str) : CWSandbox API endpoint URL. Default: DEFAULT_BASE_URL.
• auth (AuthConfig | None) : Authentication selection. Accepts an AuthStrategy, resolved AuthHeaders, or an AuthProvider. None preserves a legacy process-global override when installed and otherwise uses AuthStrategy.COREWEAVE_API_KEY. Default: field(default=None, repr=False).
• request_timeout_seconds (float) : Client-side HTTP timeout in seconds for most RPCs. Poll Get RPCs use poll_rpc_timeout_seconds instead. Default: DEFAULT_REQUEST_TIMEOUT_SECONDS.
• poll_retry_budget_seconds (float) : Wall-clock budget per retry burst (one trip to a stable status). The budget resets on any successful response, so a long-lived sandbox that hits a transient error, recovers, then hits another much later gets a fresh budget each time. Retryable transient codes are UNAVAILABLE, DEADLINE_EXCEEDED, and RESOURCE_EXHAUSTED. Set to 0.0 to disable retries entirely. Default: DEFAULT_POLL_RETRY_BUDGET_SECONDS.
• poll_rpc_timeout_seconds (float) : Per-call timeout for poll Get RPCs. Kept separate from request_timeout_seconds so a wedged poll fails fast instead of blocking on the broader request timeout. Default: DEFAULT_POLL_RPC_TIMEOUT_SECONDS.
• max_lifetime_seconds (float | None) : Server-side sandbox lifetime limit in seconds. None lets the backend control the default. Default: DEFAULT_MAX_LIFETIME_SECONDS.
• temp_dir (str) : Temp directory path inside the sandbox. Default: DEFAULT_TEMP_DIR.
• tags (tuple[str, ...]) : Tags for filtering and organizing sandboxes. Default: field(default_factory=tuple).
• runner_ids (tuple[str, ...] | None) : Restrict to specific runner IDs (CKS). Pass an empty list to explicitly clear any default; pass None (the default) to inherit any configured default. Incompatible with serverless placement.
• placement_mode (PlacementMode | str | None) : PlacementMode (serverless / cks) or string.
• placement_spillover (PlacementSpillover | str) : PlacementSpillover policy for a one-shot create retry on the alternate mode when the primary fails with a spillable capacity/placement reason. Default STRICT (no spill). Template sandboxes require STRICT. Default: PlacementSpillover.STRICT.
• resources (ResourceOptions | dict[str, Any] | None) : Resource configuration. Accepts ResourceOptions for separate requests/limits, or a flat dict for backward-compatible Guaranteed QoS.
• network (NetworkOptions | None) : Deny-flag network options and optional create-time hostname grants via NetworkOptions.
• services (tuple[Service, ...] | None) : Typed service ports (Service) for PUBLIC/PRIVATE/CUSTOM.
• volumes (tuple[ScratchVolumeOptions | RegisteredVolumeOptions, ...] | None) : Scratch or registered volumes (ScratchVolumeOptions or RegisteredVolumeOptions).
• runtime_class (str | None) : Optional runtime-class pin (e.g. "gvisor").
• security_context (SecurityContext | dict[str, Any] | None) : In-guest privilege for the single-container path. Not applied when containers= or defaults.containers is used.
• working_dir (str | None) : Working directory for the single-container path. Not applied when a container list is used.
• object_storage_access (ObjectStorageAccess | dict[str, Any] | None) : Temporary object-storage credentials.
• file_system_snapshot (FileSystemSnapshotOptions | dict[str, Any] | None) : Convenience single-mount FSS options via FileSystemSnapshotOptions. Shareable mount defaults (mount_path, size); an explicit run() value replaces it wholesale. Prefer volumes= for multi-volume setups.
• containers (tuple[Container, ...] | None) : Optional multi-container spec (Container). Mutually exclusive with single-container fields on Sandbox.run(). When this list is used, secrets, environment_variables, security_context, and working_dir on these defaults are not applied; set them on each Container.
• secrets (tuple[Secret, ...] | None) : Secrets for the single-container path. Not applied when containers= or defaults.containers is used.
• environment_variables (dict[str, str]) : Environment variables for the single-container path. Not applied when a container list is used. Default: field(default_factory=dict).
• annotations (dict[str, str]) : Kubernetes pod annotations (key-value string pairs). Merged with per-sandbox annotations; explicit values override defaults. Use for non-sensitive metadata only. Default: field(default_factory=dict).
• data_plane_mode (DataPlaneMode | str) : Transport policy for exec, logs, and file operations. auto (default) prefers direct mTLS and falls back to the gateway; gateway disables direct access; direct requires it. Default: DataPlaneMode.AUTO.

​

Methods

​

merge_tags

merge_tags(additional: Iterable[str] | None) -> list[str]

​

merge_environment_variables

merge_environment_variables(additional: dict[str, str] | None) -> dict[str, str]

​

merge_annotations

merge_annotations(additional: dict[str, str] | None) -> dict[str, str]

​

with_overrides

with_overrides(**kwargs: Any = {}) -> SandboxDefaults

​

from_dict

from_dict(d: Mapping[str, Any] | None) -> SandboxDefaults

• network dict -> NetworkOptions
• secrets list of dicts -> tuple of Secret
• services list of dicts -> tuple of Service
• volumes list of dicts -> tuple of scratch/registered volume options
• containers list of dicts -> tuple of Container
• security_context dict -> SecurityContext
• object_storage_access dict -> ObjectStorageAccess
• args, tags, runner_ids, services, volumes, containers lists -> tuples
• resources, environment_variables -> plain dict