> ## 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

> Immutable configuration defaults for sandbox creation.

Source: [src/cwsandbox/\_defaults.py:136](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/_defaults.py#L136)

```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, 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(), profile_ids: tuple[str, ...] | None = None, profile_names: tuple[str, ...] | None = None, runner_ids: tuple[str, ...] | None = None, resources: ResourceOptions | dict[str, Any] | None = None, network: NetworkOptions | None = None, secrets: tuple[Secret, ...] | None = None, environment_variables: dict[str, str] = dict(), annotations: dict[str, str] = dict())
```

Immutable configuration defaults for sandbox creation.

All fields have sensible defaults. Override only what you need.

There are two separate timeout concepts:

* 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.

Tags enable filtering and organizing sandboxes. They are propagated to
the backend and can be used to query sandboxes by tag.

**Attributes**

* `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`.
* `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)`.
* `profile_ids` (`tuple[str, ...] | None`) : Legacy selector accepting profile IDs. Prefer
  `profile_names`. Resolves independently of `profile_names`.
  Setting one explicitly does not suppress the other's default.
  Pass an empty list to explicitly clear any default; pass None
  (the default) to inherit any configured default.
* `profile_names` (`tuple[str, ...] | None`) : Select sandboxes by profile name. Resolves
  independently of `profile_ids`. Both may be combined.
  Pass an empty list to explicitly clear any default; pass None
  (the default) to inherit any configured default.
* `runner_ids` (`tuple[str, ...] | None`) : Restrict to specific runner IDs. Pass an empty list to
  explicitly clear any default; pass None (the default) to inherit
  any configured default.
* `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`) : Network configuration via `NetworkOptions`.
* `secrets` (`tuple[Secret, ...] | None`) : Secrets to inject as environment variables.
* `environment_variables` (`dict[str, str]`) : Environment variables injected into the sandbox. 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)`.

## Methods

### merge\_tags

```python theme={"system"}
merge_tags(additional: list[str] | None) -> list[str]
```

Combine default tags with additional tags.

Tags from both sources are included. Order is: defaults first,
then additional tags appended.

### merge\_environment\_variables

```python theme={"system"}
merge_environment_variables(additional: dict[str, str] | None) -> dict[str, str]
```

Combine default environment variables with additional ones.

Additional environment variables override defaults with the same key.

### merge\_annotations

```python theme={"system"}
merge_annotations(additional: dict[str, str] | None) -> dict[str, str]
```

Combine default annotations with additional ones.

Additional annotations override defaults with the same key.

### with\_overrides

```python theme={"system"}
with_overrides(**kwargs: Any = {}) -> SandboxDefaults
```

Create new defaults with some values overridden.

### from\_dict

```python theme={"system"}
from_dict(d: Mapping[str, Any] | None) -> SandboxDefaults
```

Build `SandboxDefaults` from a mapping, coercing nested fields.

Accepts plain dicts or OmegaConf `DictConfig` objects.  Unknown
keys are silently ignored so callers can pass a config section
that may contain extra fields.

Coercions applied:

* `network` dict -> `NetworkOptions`
* `secrets` list of dicts -> tuple of `Secret`
* `args`, `tags`, `profile_ids`, `profile_names`,
  `runner_ids` lists -> tuples
* `resources`, `environment_variables` -> plain `dict`