Sandbox access

Run commands, copy files, forward ports, take screenshots, reach the MCP and view a sandbox (`cua sandbox exec`, `cp`, `view`, ...).

Command	Description
`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, and cloud sandboxes, tunnel through cua-spacesd when the image has it; cloud images without it get HTTP and WebSocket through a loopback proxy to the cloud gateway).
`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; cloud: a signed URL; local: 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).

Every command also accepts the global options.

`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`, `cloud: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`).
`--cloud`	boolean	`false`	Look NAME up among cloud sandboxes only (same as `cloud: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`, `cloud: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`).
`--cloud`	boolean	`false`	Look NAME up among cloud sandboxes only (same as `cloud: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`).
`--cloud`	boolean	`false`	Look NAME up among cloud sandboxes only (same as `cloud: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`, `cloud: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`).
`--cloud`	boolean	`false`	Look NAME up among cloud sandboxes only (same as `cloud: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`, `cloud: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`).
`--cloud`		boolean	`false`	Look NAME up among cloud sandboxes only (same as `cloud: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, and cloud sandboxes, tunnel through cua-spacesd when the image has it; cloud images without it get HTTP and WebSocket through a loopback proxy to the cloud gateway).

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

Alias: cua sandbox forward.

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`, `cloud: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`).
`--cloud`	boolean	`false`	Look NAME up among cloud sandboxes only (same as `cloud: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 cloud: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; cloud: a signed URL; local: 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`, `cloud: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`).
`--cloud`	boolean	`false`	Look NAME up among cloud sandboxes only (same as `cloud:NAME`).
`--public`	boolean	`false`	A shareable URL that expires.

Examples

cua sb url dev web
 
# A shareable URL for 10 minutes
cua sb url cloud: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`, `cloud: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`).
`--cloud`		boolean	`false`	Look NAME up among cloud sandboxes only (same as `cloud: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 (local or cloud); no cua-spacesd needed.

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

Argument	Type	Default	Description
`<NAME>`	string	required	Sandbox name or ref (`local:NAME`, `cloud: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`).
`--cloud`	boolean	`false`	Look NAME up among cloud sandboxes only (same as `cloud: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; Fleet bearers are short-lived.

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`, `cloud: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`).
`--cloud`	boolean	`false`	Look NAME up among cloud sandboxes only (same as `cloud: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

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`, `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.

Sandbox access

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#

Exit codes#

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#

Exit codes#

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