cua sandbox
Create, list, connect to, suspend and delete sandboxes, local or in the cloud.
Create, list, connect to, suspend and delete sandboxes, local or in the cloud.
| Command | Description |
|---|---|
cua sandbox create | Create a sandbox: cua sb create IMAGE [--on local|cloud|direct:<addr>] [--kind auto|container|vm] [--runtime auto|gvisor|runc|qemu|lume|kubevirt]. |
cua sandbox launch | Deprecated alias of create that defaults to --on cloud. |
cua sandbox connect | Reattach to a sandbox (NAME or a ref such as cloud:NAME) and print it. |
cua sandbox ls | List sandboxes: local, direct and cloud (live Fleet claims) by default, each with its location; --local or --cloud filters. |
cua sandbox info | Show one sandbox (or a Fleet pool of that name). |
cua sandbox suspend | Suspend (local: pause/snapshot; Fleet managed pool: release the claim and keep the record; explicit Fleet pool: scale to zero). |
cua sandbox resume | Resume (Fleet managed pool: claim a fresh sandbox of the same shape). |
cua sandbox restart | Restart. |
cua sandbox keep-alive | Extend a Fleet claim's lease. |
cua sandbox rm | Delete a sandbox (Fleet: release the claim; managed pools are kept for reuse). |
Every command also accepts the global options.
Sandboxes: local, cloud or an existing machine (direct).
cua sandbox [OPTIONS] <COMMAND>Alias: cua sb.
cua sandbox create#Create a sandbox: cua sb create IMAGE [--on local|cloud|direct:<addr>] [--kind auto|container|vm] [--runtime auto|gvisor|runc|qemu|lume|kubevirt].
cua sandbox create [OPTIONS] [IMAGE] [-- <COMMAND>...]| Argument | Type | Default | Description |
|---|---|---|---|
<IMAGE> | string | optional | Image: a registry reference (ghcr.io/org/image:tag), an alias (linux, ubuntu, windows, macos[:tahoe|sequoia], omarchy), or locally pool:<name> to run that cloud pool's template image with its firmware, services and readiness probe (fleet:<name> is the deprecated spelling). |
<COMMAND>... | string | optional | The sandbox's command, after -- (replaces the image's entrypoint): cua sb create python:3.12-slim --service mcp=8765 -- python -m srv. Repeatable. |
| Flag | Type | Default | Env var | Description |
|---|---|---|---|---|
--on | string | Where it runs: local, cloud, direct:<addr> (an existing machine running cua-spacesd), or a registered provider. Default: cua config get default.on (CUA_DEFAULT_ON), else local. | ||
--kind | string | What kind of machine: auto (from the image: a container when it has a container rootfs; macOS, Windows and disk-only images are VMs), container or vm. | ||
--runtime | string | Which engine: auto (the safest available) or one the location offers for the kind. Local: gvisor or runc (containers), qemu or lume (VMs). Cloud: gvisor (containers), kubevirt (VMs). A local sandbox with --sidecar needs --runtime runc where gVisor would run (separate gVisor containers cannot share a network namespace). | ||
--tier | string | Image tier for an alias: slim, full (default) or macOS xcode. | ||
--name | string | Sandbox name (generated when omitted). | ||
--open | string | With --browser: open this URL. | ||
--install | string | Install these into the sandbox once it is up: harness ids (claude-code) or installables (blender, vscode, node), pinned and checksum-verified (cua agent ensure later does the same). Repeatable. | ||
--cpu | integer | vCPUs. Alias: --cpus. | ||
--memory | string | Memory, e.g. 8GB or 4096MB (a bare number is GB). | ||
--network | default | none | Guest network: default (outbound network, like a Docker container) or none (no egress; published ports still work). none needs a local QEMU VM; containers, Lume and cloud sandboxes reject it. | ||
--disk | string | Disk size (accepted; the image decides today). | ||
--port | string | Expose a guest port: NAME=PORT (a named service) or PORT (repeatable). Alias: --service. | ||
--wait | string | Wait until ready: tcp:SERVICE, http:SERVICE/path, a guest port (tcp:PORT, http:PORT/path), or desktop (the desktop session takes input: display, window manager and cua-driver) (repeatable). Alias: --wait-for. | ||
--ready-timeout | integer | Readiness budget in seconds, the wait for the image's cua-spacesd included (default 600, with at most 120 of it for cua-spacesd). | ||
--overlay | string | Inject a freshly built binary once the sandbox is up: NAME=PATH (cua-driver, cua-spacesd) or NAME=PATH:GUEST_PATH (repeatable). It replaces the guest file atomically, is recorded with its sha256 (checked by cua doctor) and what runs it is restarted. Needs cua-spacesd in the image. | ||
--env | string | Environment KEY=VALUE for the sandbox (repeatable). | ||
--sidecar | string | A sidecar container, reachable from the sandbox at its name (it reaches the sandbox at main): IMAGE[,port=PORT][,env=K=V][,name=NAME] (repeatable; port= and env= repeat too). Local containers and every cloud sandbox; locally it needs --runtime runc where gVisor would run. With sidecars the service names main, sidecars and sc are reserved. | ||
--registry-secret | string | Credentials for a private image: env:USER_VAR:PASSWORD_VAR (read from this environment) or aws-ecr[:REGION] (the AWS CLI's login token). | ||
--max-pool-size | integer | Cloud: most sandboxes of this image at once. | ||
--claim-ttl | integer | Cloud: how long the sandbox outlives this command without a keep-alive (15m, 900); renewed while the daemon holds it. | ||
--pool | string | Cloud: use this dedicated pool instead of shared capacity. The sandbox fields given (IMAGE, --cmd, --env, --port, --sidecar, --cpu, --memory) must match its template, or creation fails with the diff. | ||
--token | string | CUA_ENV_TOKEN | spacesd token (direct: sandboxes). | |
--gpu | string | A GPU: the runtime's own (--gpu), or an option cua spaces gpus lists (paravirtual: GPU acceleration for a macOS VM on Lume, experimental; virgl: QEMU on Linux; nvidia: a runc container on Linux; a provider's GPU type). | ||
--browser | boolean | false | Start Chromium in it for the cua-driver browser tools (IMAGE defaults to linux). | |
--warm | boolean | false | Cloud: keep one warm sandbox of this image ready (the default for the canonical linux/windows/macos images). | |
--no-warm | boolean | false | Cloud: no warm sandbox, even for a canonical image. | |
--apply | boolean | false | Cloud, with --pool: update the pool's template to the given fields instead of failing when they differ. | |
--view | boolean | false | Open the desktop in the HTML5 viewer once the sandbox is ready (cua sb view). | |
--keep-on-failure | boolean | false | Keep the sandbox (its cloud claim, VM or container) when it fails to become ready, to debug it; the ref and how to delete it are printed. Default: a failed create deletes it and releases its claim. |
Examples
# A Linux desktop on this machine (a gVisor container)
cua sb create linux --name dev
# The same image in the cloud, as a VM
cua sb create linux --on cloud --kind vm --name dev
# A web server container, ready when its HTTP service answers
cua sb create python:3.12-slim --service web=8000 --wait http:web/ -- python -m http.server 8000cua sandbox launch#Deprecated alias of create that defaults to --on cloud.
cua sandbox launch [OPTIONS] [IMAGE]Examples
# A cloud Linux sandbox (same as `cua sb create linux --on cloud`)
cua sb launch linux --name devcua sandbox connect#Reattach to a sandbox (NAME or a ref such as cloud:NAME) and print it.
cua sandbox connect [OPTIONS] <NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | required | Sandbox name or ref (local:NAME, cloud:NAME). |
| Flag | Type | Default | Description |
|---|---|---|---|
--local | boolean | false | Look NAME up among local sandboxes only (same as local:NAME). |
--cloud | boolean | false | Look NAME up among cloud sandboxes only (same as cloud:NAME). |
Examples
cua sb connect dev
cua sb connect cloud:devcua sandbox ls#List sandboxes: local, direct and cloud (live Fleet claims) by default, each with its location; --local or --cloud filters.
cua sandbox ls [OPTIONS]Alias: cua sandbox list.
| Flag | Type | Default | Description |
|---|---|---|---|
--local | boolean | false | Only local sandboxes. |
--cloud | boolean | false | Only cloud sandboxes, listed live from Fleet. |
--no-size | boolean | false | Skip the SIZE column (disk used by each local sandbox), which reads the VM, container and Lume stores. |
Examples
cua sb ls
cua sb ls --cloud --jsoncua sandbox info#Show one sandbox (or a Fleet pool of that name).
cua sandbox info [OPTIONS] <NAME>Alias: cua sandbox get.
| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | required | Sandbox name or ref (local:NAME, cloud:NAME). |
| Flag | Type | Default | Description |
|---|---|---|---|
--local | boolean | false | Look NAME up among local sandboxes only (same as local:NAME). |
--cloud | boolean | false | Look NAME up among cloud sandboxes only (same as cloud:NAME). |
Examples
cua sb info dev
cua sb info cloud:dev --jsoncua sandbox suspend#Suspend (local: pause/snapshot; Fleet managed pool: release the claim and keep the record; explicit Fleet pool: scale to zero).
cua sandbox suspend [OPTIONS] <NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | required | Sandbox name or ref (local:NAME, cloud:NAME). |
| Flag | Type | Default | Description |
|---|---|---|---|
--local | boolean | false | Look NAME up among local sandboxes only (same as local:NAME). |
--cloud | boolean | false | Look NAME up among cloud sandboxes only (same as cloud:NAME). |
Examples
cua sb suspend devcua sandbox resume#Resume (Fleet managed pool: claim a fresh sandbox of the same shape).
cua sandbox resume [OPTIONS] <NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | required | Sandbox name or ref (local:NAME, cloud:NAME). |
| Flag | Type | Default | Description |
|---|---|---|---|
--local | boolean | false | Look NAME up among local sandboxes only (same as local:NAME). |
--cloud | boolean | false | Look NAME up among cloud sandboxes only (same as cloud:NAME). |
Examples
cua sb resume devcua sandbox restart#Restart.
cua sandbox restart [OPTIONS] <NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | required | Sandbox name or ref (local:NAME, cloud:NAME). |
| Flag | Type | Default | Description |
|---|---|---|---|
--local | boolean | false | Look NAME up among local sandboxes only (same as local:NAME). |
--cloud | boolean | false | Look NAME up among cloud sandboxes only (same as cloud:NAME). |
Examples
cua sb restart devcua sandbox keep-alive#Extend a Fleet claim's lease.
cua sandbox keep-alive [OPTIONS] <NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | required | Sandbox name or ref (local:NAME, cloud:NAME). |
| Flag | Type | Default | Description |
|---|---|---|---|
--for | integer | 15m | Lease from now (15m, 2h, 900). |
--local | boolean | false | Look NAME up among local sandboxes only (same as local:NAME). |
--cloud | boolean | false | Look NAME up among cloud sandboxes only (same as cloud:NAME). |
Examples
# Keep the claim for two more hours
cua sb keep-alive cloud:dev --for 2hcua sandbox rm#Delete a sandbox (Fleet: release the claim; managed pools are kept for reuse).
cua sandbox rm [OPTIONS] <NAME>Alias: cua sandbox delete.
| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | required | Sandbox name or ref (local:NAME, cloud:NAME). |
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--force | -f | boolean | false | Skip the confirmation prompt. Required when there is no terminal to ask on (scripts, agents): without it nothing is deleted. |
--local | boolean | false | Look NAME up among local sandboxes only (same as local:NAME). | |
--cloud | boolean | false | Look NAME up among cloud sandboxes only (same as cloud:NAME). |
Examples
cua sb rm dev
# Without the prompt (required in scripts and agents)
cua sb rm cloud:dev --force| Code | Meaning |
|---|---|
0 | Success. |
1 | Failure, or cua do reported an error. |
2 | Invalid argument, or an ambiguous sandbox name (qualify it: local:NAME, cloud:NAME). |
3 | Not found: sandbox, window, skill or image (or an image not published yet). |
4 | Not supported, or not configured (for example no Fleet credentials). |
5 | No cua-spacesd answered, or a transport failure. |
6 | Unauthenticated or permission denied (by Cua, Fleet or your cloud account). |
7 | Not enough free disk space (see cua cache). |
130 | Cancelled (Ctrl-C during a create): what it made was removed. |