Sandboxes and images

Create, reach and delete sandboxes; pull, build and push images; local runtimes, disk cleanup, your own cloud account and the sandbox viewer.

Command	Description
`cua sandbox`	Sandboxes: local or an existing machine (direct).
`cua sandbox create`	Create a sandbox: `cua sb create IMAGE [--on local\|direct:<addr>] [--kind auto\|container\|vm] [--runtime auto\|gvisor\|runc\|qemu\|lume]`.
`cua sandbox launch`	Deprecated alias of `create`.
`cua sandbox connect`	Reattach to a sandbox (NAME or a ref such as `local:NAME`) and print it.
`cua sandbox ls`	List sandboxes: local and direct, each with its `location`; `--local` filters.
`cua sandbox info`	Show one sandbox.
`cua sandbox suspend`	Suspend (pause/snapshot).
`cua sandbox resume`	Resume.
`cua sandbox restart`	Restart.
`cua sandbox rm`	Delete a sandbox.
`cua sandbox exec`	Run a command (joined into one shell line, as `sh -c`).
`cua sandbox shell`	Interactive shell (PTY), or run a command in a PTY.
`cua sandbox cp`	Copy files: `cp NAME:/guest/path LOCAL` or `cp LOCAL NAME:/guest/path` (NAME may be a ref: `cp local:box:/tmp/x .`).
`cua sandbox overlay`	Inject freshly built binaries into a running sandbox (see `create --overlay`): NAME=PATH or NAME=PATH:GUEST_PATH.
`cua sandbox logs`	Show logs: the backend console (QEMU serial, container) when there is one, else the guest system log through the spacesd.
`cua sandbox port-forward`	Forward a guest port: `port-forward NAME PORT[:LOCAL]` (a local sandbox's port not published at create tunnels through cua-spacesd when the image has it).
`cua sandbox url`	Print a URL for a named service: usable from this machine (default), or `--public` for a shareable URL that expires (`--ttl`, default 1h; a token URL served by the cua daemon).
`cua sandbox screenshot`	Save a screenshot (PNG).
`cua sandbox mcp`	Talk to an MCP server a sandbox serves: `mcp NAME SERVICE tools`, `mcp NAME SERVICE call TOOL '{"a":1}'`.
`cua sandbox mcp config`	The endpoint URL and headers, for any MCP client.
`cua sandbox mcp info`	Server name, version and negotiated protocol revision.
`cua sandbox mcp tools`	List tools.
`cua sandbox mcp call`	Call a tool with a JSON object of arguments.
`cua sandbox mcp resources`	List resources.
`cua sandbox mcp templates`	List resource templates.
`cua sandbox mcp read`	Read a resource.
`cua sandbox mcp prompts`	List prompts.
`cua sandbox mcp prompt`	Render a prompt with a JSON object of string arguments.
`cua sandbox mcp request`	Any other method (for example `skills/list`), printing the result.
`cua sandbox view`	Open the sandbox desktop in the browser (the cua-spacesd HTML5 viewer).
`cua image`	Images: local OCI pull/build/push.
`cua image pull`	Pull an image into the local cache.
`cua image build`	Build an image from an images.cua.ai/v1alpha1 Image resource (JSON).
`cua image push`	Copy an image (host architecture) to another registry reference.
`cua images`	The sandbox image catalog (the images the docs list): which exist, their variants, and which ship cua-spacesd and a browser.
`cua images ls`	List the catalog: ref, OS, container or VM, local runtime, cua-spacesd, browsers, summary.
`cua images info`	Show one catalog entry (a ref or an alias such as `linux`).
`cua images build`	Build a sandbox image definition (a libs/images directory): the rootfs, the bootable VM disk and the KubeVirt containerDisk.
`cua images pack`	Pack the disks `cua images build --outputs disk` wrote as KubeVirt containerDisks `<repo>:<tag>-<arch>` (push, or load into docker).
`cua images publish`	Publish a built image as immutable pins `<series>-<stamp>` and `<series>-disk-<stamp>`, refusing any that exist.
`cua images release`	Run an image's release pipeline (its release.json): build, doctor lanes, content digest, save; with --publish push, publish pins and verify; with --promote move the floating tags.
`cua images promote`	Move a series' moving tags (`edge`, `edge-disk`) to the pins a `cua images publish` record names, after the gates passed.
`cua runtime`	Local runtimes (cua-vmm).
`cua runtime doctor`	Inspect local runtimes (read-only).
`cua runtime setup`	Provision local runtimes.
`cua cache`	Disk used by images, sandboxes, builds and logs, and its cleanup.
`cua cache ls`	List what the SDK keeps on disk, one row per image, sandbox, build output, install archive or log.
`cua cache du`	Disk usage per category, the cache budget and free space.
`cua cache prune`	Reap orphaned ephemeral sandboxes, remove orphans (abandoned downloads, unused layers) and evict least-recently-used cache down to the budget.
`cua cache config`	Show or set the cache settings (`$CUA_HOME/cache.json`; the CUA_CACHE_BUDGET, CUA_DISK_MIN_FREE, CUA_DISK_WARN_FREE and CUA_ORPHAN_REAP_MINUTES environment variables win).
`cua cloud`	Spaces in your own cloud account (AWS, Google Cloud, Modal): connect, status, test, disconnect, sweep.
`cua cloud status`	Your clouds: found credentials, the connected account and region, what each runs at what hourly cost, and what Cua created there.
`cua cloud connect`	Connect a cloud account Spaces can be created in (after the checks `cua cloud test` runs).
`cua cloud test`	Check a cloud account without creating anything: credentials, permissions (by dry run), quota, the region and machine types.
`cua cloud disconnect`	Forget a connected cloud (nothing in it is deleted).
`cua cloud sweep`	Find what Cua left in your clouds: expired Spaces and resources whose Space is gone (with --all, every Cua resource).
`cua viewer`	Serve the HTML5 viewer for every sandbox on one loopback port.

Every command also accepts the global options.

`cua sandbox`#

Sandboxes: local or an existing machine (direct).

cua sandbox [OPTIONS] <COMMAND>

Alias: cua sb.

`cua sandbox create`#

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`).
`<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, 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). 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 and Lume 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, counted once the image is downloaded, the wait for the image's cua-spacesd included (default 600, plus up to 120 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; 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).
`--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`).
`--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 (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.

Examples

# A Linux desktop on this machine (a gVisor container)
cua sb create linux --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 8000
 
# The same Linux image as a VM
cua sb create linux --kind vm --name dev

`cua sandbox launch`#

Deprecated alias of create.

cua sandbox launch [OPTIONS] [IMAGE]

Examples

cua sb launch linux --name dev

`cua sandbox connect`#

Reattach to a sandbox (NAME or a ref such as local:NAME) and print it.

cua sandbox connect [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).

Flag	Type	Default	Description
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

cua sb connect dev
cua sb connect local:dev

`cua sandbox ls`#

List sandboxes: local and direct, each with its location; --local filters.

cua sandbox ls [OPTIONS]

Alias: cua sandbox list.

Flag	Type	Default	Description
`--local`	boolean	`false`	Only local sandboxes.
`--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 --local --json

`cua sandbox info`#

Show one sandbox.

cua sandbox info [OPTIONS] <NAME>

Alias: cua sandbox get.

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).

Flag	Type	Default	Description
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

cua sb info dev
cua sb info local:dev --json

`cua sandbox suspend`#

Suspend (pause/snapshot).

cua sandbox suspend [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).

Flag	Type	Default	Description
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

cua sb suspend dev

`cua sandbox resume`#

Resume.

cua sandbox resume [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).

Flag	Type	Default	Description
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

cua sb resume dev

`cua sandbox restart`#

Restart.

cua sandbox restart [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).

Flag	Type	Default	Description
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

cua sb restart dev

`cua sandbox rm`#

Delete a sandbox.

cua sandbox rm [OPTIONS] <NAME>

Alias: cua sandbox delete.

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local: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`).

Examples

cua sb rm dev
 
# Without the prompt (required in scripts and agents)
cua sb rm local:dev --force

`cua sandbox exec`#

Run a command (joined into one shell line, as sh -c). Exits with the command's own status. A local Lume sandbox without cua-spacesd runs it via SSH (lume ssh).

cua sandbox exec [OPTIONS] <NAME> <COMMAND>...

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).
`<COMMAND>...`	string	required	Command and arguments. Repeatable.

Flag	Type	Default	Description
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

cua sb exec dev uname -a
cua sb exec dev 'ls /tmp | wc -l'

`cua sandbox shell`#

Interactive shell (PTY), or run a command in a PTY.

cua sandbox shell [OPTIONS] <NAME> [COMMAND]...

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).
`<COMMAND>...`	string	optional	Command to run instead of the login shell. Repeatable.

Flag	Type	Default	Description
`--cols`	integer		Terminal width (default: this terminal's).
`--rows`	integer		Terminal height (default: this terminal's).
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

cua sb shell dev
cua sb shell dev top

`cua sandbox cp`#

Copy files: cp NAME:/guest/path LOCAL or cp LOCAL NAME:/guest/path (NAME may be a ref: cp local:box:/tmp/x .).

cua sandbox cp [OPTIONS] <SRC> <DST>

Argument	Type	Default	Description
`<SRC>`	string	required	Source: a local path or `NAME:/guest/path`.
`<DST>`	string	required	Destination: a local path or `NAME:/guest/path`.

Flag	Type	Default	Description
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

# Upload
cua sb cp ./notes.txt dev:/tmp/notes.txt
 
# Download
cua sb cp dev:/tmp/notes.txt .

`cua sandbox overlay`#

Inject freshly built binaries into a running sandbox (see create --overlay): NAME=PATH or NAME=PATH:GUEST_PATH.

cua sandbox overlay [OPTIONS] <NAME> <OVERLAYS>...

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).
`<OVERLAYS>...`	string	required	NAME=PATH[:GUEST_PATH] (repeatable). Repeatable.

Flag	Type	Default	Description
`--timeout`	integer	`180`	Budget for a cua-spacesd restart, in seconds.
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

# The cua-driver under test, then check that it is what runs
cua sb overlay dev cua-driver=./target/release/cua-driver
cua doctor dev --expect cua-driver=sha256:<sha256>
 
# The daemon too (restarts it and waits for the new build)
cua sb overlay dev cua-spacesd=./target/release/cua-spacesd

`cua sandbox logs`#

Show logs: the backend console (QEMU serial, container) when there is one, else the guest system log through the spacesd.

cua sandbox logs [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).

Flag	Short	Type	Default	Description
`--tail`	`-n`	integer	`200`	Lines from the end.
`--source`		string	`auto`	auto, console or guest.
`--local`		boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

cua sb logs dev
cua sb logs dev -n 50 --source guest

`cua sandbox port-forward`#

Forward a guest port: port-forward NAME PORT[:LOCAL] (a local sandbox's port not published at create tunnels through cua-spacesd when the image has it).

cua sandbox port-forward [OPTIONS] <NAME> <SPEC>

Alias: cua sandbox forward.

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).
`<SPEC>`	string	required	PORT or PORT:LOCAL_PORT.

Flag	Type	Default	Description
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).
`--no-wait`	boolean	`false`	Print the target and exit instead of forwarding until Ctrl-C.

Examples

# Guest port 8080 on localhost:8080 until Ctrl-C
cua sb port-forward dev 8080
 
# Guest port 5432 on localhost:15432
cua sb port-forward local:dev 5432:15432

`cua sandbox url`#

Print a URL for a named service: usable from this machine (default), or --public for a shareable URL that expires (--ttl, default 1h; a token URL served by the cua daemon).

cua sandbox url [OPTIONS] <NAME> <SERVICE>

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).
`<SERVICE>`	string	required	Service name (from `--service` at create time).

Flag	Type	Default	Description
`--ttl`	integer		Lifetime of a --public URL (`10m`, `1h`, `3600`; 60 s to 24 h).
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).
`--public`	boolean	`false`	A shareable URL that expires.

Examples

cua sb url dev web
 
# A shareable URL for 10 minutes
cua sb url local:dev web --public --ttl 10m

`cua sandbox screenshot`#

Save a screenshot (PNG). A local Lume sandbox without cua-spacesd is captured via VNC.

cua sandbox screenshot [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).

Flag	Short	Type	Default	Description
`--output`	`-o`	path	`screenshot.png`	Output file (PNG).
`--local`		boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

cua sb screenshot dev -o desktop.png

`cua sandbox mcp`#

Talk to an MCP server a sandbox serves: mcp NAME SERVICE tools, mcp NAME SERVICE call TOOL '{"a":1}'. Generic streamable HTTP over the service; no cua-spacesd needed.

cua sandbox mcp [OPTIONS] <NAME> <SERVICE> <COMMAND>

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).
`<SERVICE>`	string	required	Service name (for example `mcp`, or `port-8765`).

Flag	Type	Default	Description
`--path`	string	`/mcp`	Endpoint path on the service.
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

cua sb mcp dev mcp tools
cua sb mcp dev mcp call echo '{"text":"hi"}'

`cua sandbox mcp config`#

The endpoint URL and headers, for any MCP client. Credential headers print masked (Bearer ****) unless --show-secrets.

cua sandbox mcp <NAME> <SERVICE> config [OPTIONS]

Flag	Type	Default	Description
`--show-secrets`	boolean	`false`	Print credential header values in full.

Examples

cua sb mcp dev mcp config

`cua sandbox mcp info`#

Server name, version and negotiated protocol revision.

cua sandbox mcp <NAME> <SERVICE> info [OPTIONS]

Examples

cua sb mcp dev mcp info

`cua sandbox mcp tools`#

List tools.

cua sandbox mcp <NAME> <SERVICE> tools [OPTIONS]

Examples

cua sb mcp dev mcp tools

`cua sandbox mcp call`#

Call a tool with a JSON object of arguments.

cua sandbox mcp <NAME> <SERVICE> call [OPTIONS] <TOOL> [ARGUMENTS]

Argument	Type	Default	Description
`<TOOL>`	string	required	Tool name.
`<ARGUMENTS>`	string	optional	Arguments (JSON object). Default `{}`.

Flag	Type	Default	Description
`--out`	path		Save image, audio and blob content here instead of summarizing.

Examples

cua sb mcp dev mcp call echo '{"text":"hi"}'
cua sb mcp dev mcp call screenshot --out ./shots

`cua sandbox mcp resources`#

List resources.

cua sandbox mcp <NAME> <SERVICE> resources [OPTIONS]

Examples

cua sb mcp dev mcp resources

`cua sandbox mcp templates`#

List resource templates.

cua sandbox mcp <NAME> <SERVICE> templates [OPTIONS]

Examples

cua sb mcp dev mcp templates

`cua sandbox mcp read`#

Read a resource.

cua sandbox mcp <NAME> <SERVICE> read [OPTIONS] <URI>

Argument	Type	Default	Description
`<URI>`	string	required	Resource URI.

Flag	Type	Default	Description
`--out`	path		Save blob contents here instead of summarizing.

Examples

cua sb mcp dev mcp read file:///tmp/report.txt

`cua sandbox mcp prompts`#

List prompts.

cua sandbox mcp <NAME> <SERVICE> prompts [OPTIONS]

Examples

cua sb mcp dev mcp prompts

`cua sandbox mcp prompt`#

Render a prompt with a JSON object of string arguments.

cua sandbox mcp <NAME> <SERVICE> prompt [OPTIONS] <NAME> [ARGUMENTS]

Argument	Type	Default	Description
`<NAME>`	string	required	Prompt name.
`<ARGUMENTS>`	string	optional	Arguments (JSON object of strings). Default `{}`.

Examples

cua sb mcp dev mcp prompt summarize '{"topic":"logs"}'

`cua sandbox mcp request`#

Any other method (for example skills/list), printing the result.

cua sandbox mcp <NAME> <SERVICE> request [OPTIONS] <METHOD> [PARAMS]

Argument	Type	Default	Description
`<METHOD>`	string	required	JSON-RPC method.
`<PARAMS>`	string	optional	Params (JSON object).

Examples

cua sb mcp dev mcp request skills/list

`cua sandbox view`#

Open the sandbox desktop in the browser (the cua-spacesd HTML5 viewer). A local Lume sandbox without cua-spacesd opens its VNC display with lume attach.

cua sandbox view [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`).

Flag	Type	Default	Description
`--service`	string		Open this web service of the sandbox instead of the viewer (for images without cua-spacesd that serve their own display page).
`--files`	string		Guest folder for uploads and folder sharing (default `~`; `none` turns files off).
`--ttl`	string		Link lifetime (for example `1h`, `30m`). Default 1h.
`--view-only`	boolean	`false`	Watch only: no input, clipboard, files or microphone.
`--no-open`	boolean	`false`	Print the link without opening a browser.
`--local`	boolean	`false`	Look NAME up among local sandboxes only (same as `local:NAME`).

Examples

cua sb view dev
 
# Watch only, print the link instead of opening it
cua sb view dev --view-only --no-open
 
# An image that ships its own web display instead of cua-spacesd
cua sb view old-box --service web

`cua image`#

Images: local OCI pull/build/push.

cua image [OPTIONS] <COMMAND>

Alias: cua img.

`cua image pull`#

Pull an image into the local cache.

cua image pull [OPTIONS] <REFERENCE>

Argument	Type	Default	Description
`<REFERENCE>`	string	required	Image reference or alias.

Examples

cua image pull linux
cua image pull ghcr.io/trycua/linux:24.04

`cua image build`#

Build an image from an images.cua.ai/v1alpha1 Image resource (JSON).

cua image build [OPTIONS] --base <BASE> <SPEC>

Argument	Type	Default	Description
`<SPEC>`	path	required	Image resource file (JSON).

Flag	Type	Default	Description
`--base`	string	required	Base image (`container:<ref>`, `vm:<ref>`, `disk:<path>`).
`--push`	string		Push the result to this reference.

Examples

cua image build image.json --base container:ubuntu:24.04
cua image build image.json --base container:ubuntu:24.04 --push ghcr.io/acme/desktop:1

`cua image push`#

Copy an image (host architecture) to another registry reference.

cua image push [OPTIONS] <REFERENCE> <DESTINATION>

Argument	Type	Default	Description
`<REFERENCE>`	string	required	Source image reference or alias.
`<DESTINATION>`	string	required	Destination registry reference.

Examples

cua image push linux ghcr.io/acme/desktop:1

`cua images`#

The sandbox image catalog (the images the docs list): which exist, their variants, and which ship cua-spacesd and a browser.

cua images [OPTIONS] <COMMAND>

`cua images ls`#

List the catalog: ref, OS, container or VM, local runtime, cua-spacesd, browsers, summary.

cua images ls [OPTIONS]

Alias: cua images list.

Flag	Type	Default	Description
`--os`	string		Only this OS: linux, windows or macos.
`--all`	boolean	`false`	Include unpublished entries (benchmark images).
`--browser`	boolean	`false`	Only images with a browser the cua-driver browser tools drive.

Examples

cua images ls
 
# Images whose browser the cua-driver browser tools drive
cua images ls --browser
cua images ls --all --json

`cua images info`#

Show one catalog entry (a ref or an alias such as linux).

cua images info [OPTIONS] <REFERENCE>

Argument	Type	Default	Description
`<REFERENCE>`	string	required	Image ref or alias.

Examples

cua images info linux

`cua images build`#

Build a sandbox image definition (a libs/images directory): the rootfs, the bootable VM disk and the KubeVirt containerDisk.

Outputs: rootfs <repo>:docker-<tag>-<arch>; disk <out>/<name>/<arch>/disk.img; containerdisk <repo>:<tag>-<arch>. --push pushes the outputs the image.json lists (a VM-only image never pushes its rootfs).

cua images build [OPTIONS] <DIR>

Argument	Type	Default	Description
`<DIR>`	path	required	Image definition directory (Dockerfile, image.json).

Flag	Type	Default	Description
`--platform`	string		Platforms, comma separated (default: the host's, or the image's only one).
`--tag`	string	`local`	Tag for the per-arch outputs.
`--repo`	string		Repository (default: image.json `repository`, else cua-e2e-local/<name>).
`--outputs`	string	`rootfs`	Outputs: rootfs, disk, containerdisk (comma separated).
`--build-arg`	string		Docker build argument KEY=VALUE (repeatable).
`--build-context`	string		Named build context NAME=PATH (repeatable).
`--label`	string		Extra rootfs label KEY=VALUE (repeatable).
`--out`	path		Where disks go (default: $CUA_IMAGES_OUT or ~/.cache/cua-images).
`--disk-size`	string	`20G`	Virtual size of the disk.
`--target`	string		Dockerfile stage to build (a tier: `slim`, `full`); disks go to <out>/<name>-<target>/<arch>. Default: the Dockerfile's last stage.
`--push`	boolean	`false`	Push the published outputs.
`--dry-run`	boolean	`false`	Print the steps without running them.

Examples

cua images build libs/images/omarchy --outputs rootfs,disk
cua images build libs/images/omarchy --tag build-1a2b3c4d --outputs containerdisk --push
cua images build libs/images/linux --target slim --tag 24.04-slim-local --outputs rootfs,disk
cua images build libs/images/linux --platform linux/amd64,linux/arm64 --dry-run

`cua images pack`#

Pack the disks cua images build --outputs disk wrote as KubeVirt containerDisks <repo>:<tag>-<arch> (push, or load into docker).

Packs exactly the disk the doctor checked, so the pushed bytes are the tested ones.

cua images pack [OPTIONS] <DIR>

Argument	Type	Default	Description
`<DIR>`	path	required	Image definition directory.

Flag	Type	Default	Description
`--platform`	string		Platforms, comma separated (default: the host's, or the image's only one).
`--tag`	string	`local`	Tag for the per-arch containerDisks.
`--repo`	string		Repository (default: image.json `repository`, else cua-e2e-local/<name>).
`--out`	path		Where the disks are (default: $CUA_IMAGES_OUT or ~/.cache/cua-images).
`--target`	string		The `--target` the disks were built with (their <name>-<target> dir).
`--push`	boolean	`false`	Push instead of loading into docker.
`--dry-run`	boolean	`false`	Print what would be packed.

Examples

cua images pack libs/images/omarchy --tag ci-1a2b3c4d --push --json

`cua images publish`#

Publish a built image as immutable pins <series>-<stamp> and <series>-disk-<stamp>, refusing any that exist. Moves nothing.

Reads the per-arch images cua images build --tag TAG --push wrote (<repo>:<tag>-<arch>, and <repo>:docker-<tag>-<arch> when the image has a rootfs output). Writes the record cua images promote takes.

cua images publish [OPTIONS] --tag <TAG> --series <SERIES> <DIR>

Argument	Type	Default	Description
`<DIR>`	path	required	Image definition directory.

Flag	Type	Default	Description
`--tag`	string	required	The build tag the per-arch images were pushed under.
`--series`	string	required	Series / channel (`edge`, `24.04`).
`--stamp`	string		Pin stamp `<yyyymmdd>-<sha7>` (default: today and git HEAD).
`--repo`	string		Repository (default: image.json `repository`).
`--platform`	string		Platforms (default: image.json `platforms`).
`--annotation`	string		Extra index annotation KEY=VALUE (repeatable).
`--descriptor-annotation`	string		Annotation on one child's descriptor, VARIANT/ARCH:KEY=VALUE (`rootfs/amd64:ai.cua.doctor.status=pass`; repeatable).
`--record`	path		Write the publish record (JSON) here.
`--dry-run`	boolean	`false`	Resolve and print, push nothing.

Examples

cua images publish libs/images/omarchy --tag build-1a2b3c4d --series edge --record pins.json
cua images publish libs/images/linux --tag build-20260925-1a2b3c4 --series 24.04 --descriptor-annotation rootfs/amd64:ai.cua.doctor.status=pass
cua images publish libs/images/omarchy --tag build-1a2b3c4d --series edge --dry-run

`cua images release`#

Run an image's release pipeline (its release.json): build, doctor lanes, content digest, save; with --publish push, publish pins and verify; with --promote move the floating tags. The same command runs locally and in CI.

Phases: prepare, build, gate (doctor lanes), stage, push, publish, verify, promote. Push refuses unless every required gate passed (this run, or a state-*.json merged from other jobs in <work>/evidence). Evidence, logs and the summary go to <work>/evidence (a plain directory CI uploads as-is).

cua images release [OPTIONS] <DIR>

Argument	Type	Default	Description
`<DIR>`	path	required	Image directory with a release.json.

Flag	Type	Default	Description
`--tier`	string		Tier (`slim`, `full`) for images that have tiers.
`--arch`	string		Arches, comma separated (default: release.json `arches`). Repeatable.
`--stamp`	string		Pin stamp `<yyyymmdd>-<sha7>` (default: today and git HEAD).
`--work`	path		Work directory (default: $CUA_RELEASE_WORK, else under the cua build cache, which `cua cache prune` manages).
`--steps`	string		Only these steps: phase names or step-id prefixes (comma separated). Repeatable.
`--from`	string		Rerun from this phase or step; the steps before it must have passed.
`--var`	string		Variable KEY=VALUE for release.json templates (repeatable).
`--assume`	string		Treat a host capability as present (`kvm`) or absent (`!runsc`). Repeatable.
`--scope`	string		This run's state file name, state-<scope>.json (default: the arches); CI jobs sharing an evidence directory use distinct scopes.
`--resume`	boolean	`false`	Skip steps that passed with the same inputs and whose outputs exist.
`--dry-run`	boolean	`false`	Print the plan; run nothing.
`--publish`	boolean	`false`	Also push, publish immutable pins and verify them.
`--promote`	boolean	`false`	Also move the floating tags to the pins.

Examples

# Plan only
cua images release libs/images/linux --tier slim --dry-run
 
# Build and doctor amd64 locally; resume after a failure
cua images release libs/images/linux --tier slim --arch amd64 --resume
 
# Rerun from the doctor lanes (the build must have passed)
cua images release libs/images/linux --tier slim --from gate
 
# One CI job's slice
cua images release libs/images/linux --tier full --arch arm64 --steps build,gate,stage --work release
 
# Publish and promote (the gates must have passed)
cua images release libs/images/omarchy --publish --promote --resume

`cua images promote`#

Move a series' moving tags (edge, edge-disk) to the pins a cua images publish record names, after the gates passed.

cua images promote [OPTIONS] <RECORD>

Argument	Type	Default	Description
`<RECORD>`	path	required	Record written by `cua images publish --record`.

Flag	Type	Default	Description
`--dry-run`	boolean	`false`	Check and print, move nothing.

Examples

cua images promote pins.json
cua images promote pins.json --dry-run

`cua runtime`#

Local runtimes (cua-vmm).

cua runtime [OPTIONS] <COMMAND>

`cua runtime doctor`#

Inspect local runtimes (read-only).

cua runtime doctor [OPTIONS]

Examples

cua runtime doctor

`cua runtime setup`#

Provision local runtimes.

cua runtime setup [OPTIONS] [COMPONENTS]...

Argument	Type	Default	Description
`<COMPONENTS>...`	string	optional	Components: `qemu`, `lume`, `runsc` (default: everything provisionable). Repeatable.

Flag	Type	Default	Description
`--dry-run`	boolean	`false`	Only report what would be done.

Examples

# See what would be installed
cua runtime setup --dry-run
cua runtime setup qemu

`cua cache`#

Disk used by images, sandboxes, builds and logs, and its cleanup.

cua cache [OPTIONS] <COMMAND>

`cua cache ls`#

List what the SDK keeps on disk, one row per image, sandbox, build output, install archive or log.

cua cache ls [OPTIONS]

Alias: cua cache list.

Flag	Type	Default	Description
`--category`	string		Only this category (images, docker-images, lume-bases, builds, installables, icons, sandboxes, checkpoints, logs, data, legacy).

Examples

cua cache ls
 
# Only cached images
cua cache ls --category images

`cua cache du`#

Disk usage per category, the cache budget and free space.

cua cache du [OPTIONS]

Examples

cua cache du
cua cache du --json

`cua cache prune`#

Reap orphaned ephemeral sandboxes, remove orphans (abandoned downloads, unused layers) and evict least-recently-used cache down to the budget. Never removes a sandbox or anything one uses.

cua cache prune [OPTIONS]

Flag	Type	Default	Description
`--budget`	string		Budget for this run (`auto`, `off` or a size such as `20G`).
`--all`	boolean	`false`	Evict every unused cache entry, not only down to the budget.
`--dry-run`	boolean	`false`	Show what would be removed; remove nothing.

Examples

# See what a cleanup would remove
cua cache prune --dry-run
 
# Evict every unused cache entry
cua cache prune --all

`cua cache config`#

Show or set the cache settings ($CUA_HOME/cache.json; the CUA_CACHE_BUDGET, CUA_DISK_MIN_FREE, CUA_DISK_WARN_FREE and CUA_ORPHAN_REAP_MINUTES environment variables win).

cua cache config [OPTIONS]

Flag	Type	Description
`--budget`	string	Cache budget: `auto` (min of 30 GiB and 10% of free space plus cache), `off`, or a size.
`--min-free`	string	Free space pulls, builds and VM creates always leave (size).
`--warn-free`	string	Warn when free space drops under this (size).
`--orphan-reap-minutes`	integer	Minutes before an ephemeral sandbox whose process died is reaped.
`--auto-gc`	`true` \| `false`	Clean up automatically after pulls and builds and on daemon idle.

Examples

# Show the settings
cua cache config
 
# Cap the cache at 20 GB and keep 10 GB free
cua cache config --budget 20G --min-free 10G

`cua cloud`#

Spaces in your own cloud account (AWS, Google Cloud, Modal): connect, status, test, disconnect, sweep.

cua cloud [OPTIONS] <COMMAND>

Examples

cua cloud status
cua cloud connect aws --region us-west-2 --default
cua spaces create --on aws
cua cloud sweep

`cua cloud status`#

Your clouds: found credentials, the connected account and region, what each runs at what hourly cost, and what Cua created there.

cua cloud status [OPTIONS] [PROVIDER]

Alias: cua cloud ls.

Argument	Type	Default	Description
`<PROVIDER>`	string	optional	Only this cloud (`aws`, `gcp`, `modal`).

Examples

cua cloud status
cua cloud status aws --json

`cua cloud connect`#

Connect a cloud account Spaces can be created in (after the checks cua cloud test runs). Credentials stay in the cloud's own CLI; Cua stores only the profile, region, project or environment names.

cua cloud connect [OPTIONS] <PROVIDER>

Argument	Type	Default	Description
`<PROVIDER>`	string	required	`aws`, `gcp` or `modal`.

Flag	Type	Default	Description
`--profile`	string		AWS profile (`~/.aws/config`) or Modal profile (`~/.modal.toml`).
`--region`	string		AWS or Google Cloud region.
`--zone`	string		Google Cloud zone (default: the region's `-a` zone).
`--project`	string		Google Cloud project (default: `gcloud config get project`).
`--environment`	string		Modal environment (default: the profile's).
`--ttl-hours`	integer		Delete each Space there after this many hours (default 8; 0: never; Modal caps a sandbox at 24).
`--default`	boolean	`false`	Also make it the default location (`default.on`).

Examples

cua cloud connect aws --region us-west-2 --default
cua cloud connect aws --profile sandbox
cua cloud connect gcp --project my-project --region us-central1
cua cloud connect modal --environment spaces
 
# Spaces there delete themselves after 4 hours (default 8; 0: never)
cua cloud connect aws --ttl-hours 4

`cua cloud test`#

Check a cloud account without creating anything: credentials, permissions (by dry run), quota, the region and machine types.

cua cloud test [OPTIONS] <PROVIDER>

Argument	Type	Default	Description
`<PROVIDER>`	string	required	`aws`, `gcp` or `modal`.

Flag	Type	Description
`--profile`	string	AWS profile (`~/.aws/config`) or Modal profile (`~/.modal.toml`).
`--region`	string	AWS or Google Cloud region.
`--zone`	string	Google Cloud zone (default: the region's `-a` zone).
`--project`	string	Google Cloud project (default: `gcloud config get project`).
`--environment`	string	Modal environment (default: the profile's).

Examples

cua cloud test aws
cua cloud test gcp --project my-project

`cua cloud disconnect`#

Forget a connected cloud (nothing in it is deleted).

cua cloud disconnect [OPTIONS] <PROVIDER>

Argument	Type	Default	Description
`<PROVIDER>`	string	required	`aws`, `gcp` or `modal`.

Examples

cua cloud disconnect aws

`cua cloud sweep`#

Find what Cua left in your clouds: expired Spaces and resources whose Space is gone (with --all, every Cua resource). Lists them unless --delete. Only resources Cua tagged and recorded are ever touched.

cua cloud sweep [OPTIONS] [PROVIDER]

Argument	Type	Default	Description
`<PROVIDER>`	string	optional	Only this cloud.

Flag	Type	Default	Description
`--delete`	boolean	`false`	Delete what it finds (default: list only).
`--all`	boolean	`false`	Include Cua resources that have not expired (every Space there).

Examples

cua cloud sweep
cua cloud sweep aws --delete
cua cloud sweep --all --delete

`cua viewer`#

Serve the HTML5 viewer for every sandbox on one loopback port.

cua viewer [OPTIONS]

Flag	Type	Default	Description
`--listen`	string	`127.0.0.1:0`	Address to listen on (loopback only).
`--no-open`	boolean	`false`	Print the URL without opening a browser.

Examples

# List your sandboxes in the browser and open any of them
cua viewer
 
# Fixed port, print the URL only
cua viewer --listen 127.0.0.1:8211 --no-open

Exit codes#

Code	Meaning
`0`	Success.
`1`	Failure, or `cua do` reported an error.
`2`	Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`).
`3`	Not found: sandbox, window, skill or image (or an image not published yet).
`4`	Not supported, or not configured (for example no provider credentials).
`5`	No cua-spacesd answered, or a transport failure.
`6`	Unauthenticated or permission denied (by Cua 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.

Sandboxes and images

cua sandbox#

cua sandbox create#

cua sandbox launch#

cua sandbox connect#

cua sandbox ls#

cua sandbox info#

cua sandbox suspend#

cua sandbox resume#

cua sandbox restart#

cua sandbox rm#

cua sandbox exec#

cua sandbox shell#

cua sandbox cp#

cua sandbox overlay#

cua sandbox logs#

cua sandbox port-forward#

cua sandbox url#

cua sandbox screenshot#

cua sandbox mcp#

cua sandbox mcp config#

cua sandbox mcp info#

cua sandbox mcp tools#

cua sandbox mcp call#

cua sandbox mcp resources#

cua sandbox mcp templates#

cua sandbox mcp read#

cua sandbox mcp prompts#

cua sandbox mcp prompt#

cua sandbox mcp request#

cua sandbox view#

cua image#

cua image pull#

cua image build#

cua image push#

cua images#

cua images ls#

cua images info#

cua images build#

cua images pack#

cua images publish#

cua images release#

cua images promote#

cua runtime#

cua runtime doctor#

cua runtime setup#

cua cache#

cua cache ls#

cua cache du#

cua cache prune#

cua cache config#

cua cloud#

cua cloud status#

cua cloud connect#

cua cloud test#

cua cloud disconnect#

cua cloud sweep#

cua viewer#

Exit codes#

`cua sandbox`#

`cua sandbox create`#

`cua sandbox launch`#

`cua sandbox connect`#

`cua sandbox ls`#

`cua sandbox info`#

`cua sandbox suspend`#

`cua sandbox resume`#

`cua sandbox restart`#

`cua sandbox rm`#

`cua sandbox exec`#

`cua sandbox shell`#

`cua sandbox cp`#

`cua sandbox overlay`#

`cua sandbox logs`#

`cua sandbox port-forward`#

`cua sandbox url`#

`cua sandbox screenshot`#

`cua sandbox mcp`#

`cua sandbox mcp config`#

`cua sandbox mcp info`#

`cua sandbox mcp tools`#

`cua sandbox mcp call`#

`cua sandbox mcp resources`#

`cua sandbox mcp templates`#

`cua sandbox mcp read`#

`cua sandbox mcp prompts`#

`cua sandbox mcp prompt`#

`cua sandbox mcp request`#

`cua sandbox view`#

`cua image`#

`cua image pull`#

`cua image build`#

`cua image push`#

`cua images`#

`cua images ls`#

`cua images info`#

`cua images build`#

`cua images pack`#

`cua images publish`#

`cua images release`#

`cua images promote`#

`cua runtime`#

`cua runtime doctor`#

`cua runtime setup`#

`cua cache`#

`cua cache ls`#

`cua cache du`#

`cua cache prune`#

`cua cache config`#

`cua cloud`#

`cua cloud status`#

`cua cloud connect`#

`cua cloud test`#

`cua cloud disconnect`#

`cua cloud sweep`#

`cua viewer`#