Create options
SandboxCreateOptions and what it holds: cloud options, readiness probes and sidecar containers.
SandboxCreateOptions and what it holds: cloud options, readiness probes and sidecar containers.
Sandboxes.create takes one SandboxCreateOptions. Every field means the same thing locally and in the cloud; on picks where the sandbox runs, kind and runtime what runs it.
Python programs usually use the high-level API instead: Sandbox.create parameters.
SandboxCreateOptions record#Options for Sandboxes.create.
| Field | Type | Default | Description |
|---|---|---|---|
on | Option<String> | None | Where it runs: local, cloud, direct:<addr> (an existing machine running cua-spacesd) or a registered provider. None (the default): the cloud when cloud options (or the deprecated flat cloud fields) are set, else the user default (default.on in ~/.cua/config.toml, CUA_DEFAULT_ON, else local). local together with cloud is an InvalidArgument. |
kind | Option<String> | None | What kind of machine: auto, container or vm. None: the user default (default.kind, else auto: macOS and Windows images are VMs, an image with a container rootfs is a container, a disk-only image is a VM). |
runtime | Option<String> | None | Which engine: auto or one the location offers for the kind (local gvisor, runc, qemu, lume; cloud gvisor, kubevirt). None: the user default (default.runtime, else auto, the safest available). A local sandbox with sidecars needs runc where gVisor would run. A combination that does not exist is InvalidPlacement, listing the valid values. |
image | String | "" | Image reference. Locally, pool:<name> runs that cloud pool's template image. |
name | Option<String> | None | Name. None: ephemeral (cloud: released with the sandbox; the managed capacity stays for reuse). |
token | Option<String> | None | spacesd token. |
pool | Option<String> | None | Fleet: claim from this existing (user-owned) pool. Unset: a managed, autoscaled pool keyed by image and shape. Local (with an empty image): run this Fleet pool's template locally. |
os | Option<String> | None | Guest OS (linux, macos, windows). |
cpus | Option<u32> | None | vCPUs. |
memory_mb / memoryMb | Option<u64> | None | Memory (MiB). |
ports | Vec<u16> | [] | Extra guest ports (local: published; Fleet: port-<n> services). |
services | HashMap<String, u16> | [:] | Named services (name → guest port). env defaults to 3211. |
wait_for / waitFor | Vec<ReadinessProbe> | [] | Readiness probes. |
ready_timeout_ms / readyTimeoutMs | Option<u32> | None | Readiness budget (default 10 min). |
env | HashMap<String, String> | [:] | Guest environment (local: container environment or cloud-init; cloud: the template environment with processMode: Run, on gVisor and KubeVirt; values are not secrets). |
fleet_replicas / fleetReplicas | Option<u32> | None | Deprecated: initial replicas of a new managed pool (> 0 = warm). |
fleet_ttl_seconds / fleetTtlSeconds | Option<u32> | None | Deprecated: use cloud.claim_ttl_seconds. |
warm | Option<bool> | None | Deprecated: use cloud.warm. |
max_pool_size / maxPoolSize | Option<u32> | None | Deprecated: use cloud.max_pool_size. |
command | Option<Vec<String>> | None | The sandbox's command (argv), replacing the image's entrypoint. Same meaning local (container ENTRYPOINT, or run by cloud-init in a Linux VM) and in the cloud (the template command with processMode: Run, on gVisor and KubeVirt). |
cloud | Option<CloudOptions> | None | Advanced cloud options (warm capacity, limits, TTL, runtime, a dedicated pool). They win over the deprecated flat fields. |
sidecars | Vec<Container> | [] | Sidecar containers, addressed by name (see Container). |
registry_secret / registrySecret | Option<RegistrySecret> | None | Credentials for a private image (and sidecar images on its registry). |
build | Option<ImageBuild> | None | Image layers built on top of image (cloud: a remote build; local: a build into the container engine; both cached by content). |
network | Option<String> | None | Guest network: "default" (unset) gives outbound network, like a Docker container; "none" cuts it while published ports still work. Only local QEMU VMs honour "none"; containers, Lume and cloud sandboxes reject it. |
overlays | Vec<Overlay> | [] | Binaries to inject once the sandbox is up, so tests run the build under test and not the copy the image bundles (see Overlay; the same as calling Sandbox.overlay after create). Needs cua-spacesd in the image, or a local container. |
keep_on_failure / keepOnFailure | bool | false | Keep a named sandbox whose readiness check fails (its cloud claim, VM or container, and its record) to debug it. false (the default): a failed create deletes what it made and releases the claim. Ephemeral sandboxes are always deleted. |
gpu | Option<String> | None | A GPU option of the runtime it runs on (Spaces.gpu_support lists them): paravirtual (a macOS VM on Lume: GPU acceleration, experimental), virgl (QEMU on Linux), nvidia (a runc container on Linux), a contrib provider's GPU type; auto picks the runtime's own. None (the default): no GPU. |
CloudOptions record#Advanced options for cloud sandboxes (warm capacity, limits, TTL, a
dedicated pool). Leave unset for the defaults. Setting them with on
unset means the cloud; with on = "local" they are an error.
| Field | Type | Default | Description |
|---|---|---|---|
warm | Option<bool> | None | Keep one warm replica of this image ready (faster next start). |
max_pool_size / maxPoolSize | Option<u32> | None | Most sandboxes of this image at once (default 10). |
claim_ttl_seconds / claimTtlSeconds | Option<u32> | None | Seconds the sandbox outlives this process without a keep-alive (renewed while held; default 15 min). |
pool | Option<String> | None | Dedicated capacity: claim from this existing pool. The sandbox fields given alongside (image, command, env, services, sidecars, cpus, memory) must match its template, or creation fails with PoolSpecMismatch and a diff. |
apply | bool | false | With pool: update the pool's template to the given fields instead of failing on a mismatch (Fleet.apply semantics for the template; the pool's capacity is kept). Managed pools refuse it. |
ReadinessProbe record#A user-declared readiness probe. With no probes a sandbox is ready as soon as its provider reports it running; nothing assumes a guest daemon.
Name a declared service (service = "mcp") or a guest port.
| Field | Type | Default | Description |
|---|---|---|---|
port | u16 | 0 | Guest port (0 with service). |
http_path / httpPath | Option<String> | None | HTTP path; None is a TCP connect probe. |
http_status / httpStatus | Option<u16> | None | Exact HTTP status to wait for; None accepts any 2xx. |
service | Option<String> | None | A declared service whose guest port to probe (instead of port). |
Container record#An extra container next to a sandbox (a compose-style sidecar),
addressed by name on every runtime: the sandbox reaches it at its
name (on its ports), it reaches the sandbox at main, and
services may name its ports ({"db": 5432}). Local containers run it
in the sandbox's network namespace (localhost works too; needs
runtime="runc"); cloud gVisor sandboxes run it in the same pod; cloud
VM (KubeVirt) sandboxes run it in a companion pod named in the guest's
/etc/hosts. Local VM sandboxes refuse sidecars. With sidecars the
service names main, sidecars and sc are reserved.
| Field | Type | Default | Description |
|---|---|---|---|
image | String | Image reference. | |
command | Option<Vec<String>> | None | argv replacing the image's entrypoint. |
env | HashMap<String, String> | [:] | Environment (plain values, not secrets). |
ports | Vec<u16> | [] | Ports it listens on. |
name | Option<String> | None | Name, unique within the sandbox, and its hostname (not main). Unset: from the image (redis). |