cua
Cua: sandboxes, computer actions, MCP, skills and the cua daemon.
Cua: sandboxes, computer actions, MCP, skills and the cua daemon.
cua [OPTIONS] <COMMAND>Run cua <command> --help for the build you have.
cua auth#Sign in, inspect your Fleet identity, manage API keys and CI tokens. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua auth | Log in to Cua and inspect Fleet identity. | login, logout, status, whoami, keys, keys ls, keys create, keys rm, provider, provider ls, provider set, provider rm |
cua wif-token | Workload identity federation tokens. | github |
cua sandbox#Create, list, connect to, suspend and delete sandboxes, local or in the cloud. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua sandbox | Sandboxes: local, cloud or an existing machine (direct). | create, launch, connect, ls, info, suspend, resume, restart, keep-alive, rm |
Run commands, copy files, forward ports, take screenshots, reach the MCP and view a sandbox (cua sandbox exec, cp, view, ...). Reference.
| Command | Description | Subcommands |
|---|---|---|
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}'. | config, info, tools, call, resources, templates, read, prompts, prompt, request |
cua sandbox view | Open the sandbox desktop in the browser (the cua-spacesd HTML5 viewer). |
cua config#User defaults: where sandboxes run (default.on), the default kind and runtime, cloud defaults. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua config | User defaults (~/.cua/config.toml): where sandboxes run when --on is not given (default.on), the default kind and runtime, cloud defaults. | list, get, set, unset, path |
cua viewer#One local browser page that lists every sandbox and opens its viewer. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua viewer | Serve the HTML5 viewer for every sandbox on one loopback port. |
cua do#One-shot computer actions (screenshot, click, type, windows) against a selected target. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua do | One-shot computer actions against the selected target. | switch, status, ls, zoom, unzoom, screenshot, snapshot, click, dclick, move, type, key, hotkey, scroll, drag, shell, open, launch, window, window ls, window unfocus, window focus, window minimize, window maximize, window restore, window close, window resize, window move, window info, a11y, a11y tree, a11y find, a11y act, cursor, clipboard, clipboard get, clipboard set |
cua do-host-consent | Grant consent for cua do switch host. |
cua image#Pull, build and push OCI images, and manage Fleet image resources; list the image catalog. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua image | Images: local OCI pull/build/push and Fleet image resources. | pull, build, push, ls, info, rm, create |
cua images | The sandbox image catalog (the images the docs list): which exist, their variants, and which ship cua-spacesd and a browser. | ls, info, build, pack, publish, release, promote |
cua fleet#Managed Fleet pools behind cua sandbox create. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua fleet | Fleet: managed pools behind cua sandbox create without --pool. | pools, pools ls, pools gc, pool, pool export |
cua mcp#The stdio MCP server for AI assistants. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua mcp | Stdio MCP server exposing sandboxes, computer control and skills. |
cua agent#Run coding agents (Claude Code, Codex, Gemini CLI, ...) inside a sandbox and follow, continue or stop them. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua agent | Run coding agents inside a sandbox: run, ls, logs, send, interrupt, stop. | run, ls, logs, send, interrupt, stop, status, rm, ensure, harnesses, create, persistent, tell, save, pause, resume, forget, routine, routine add, routine ls, routine rm, routine enable, routine disable, allow-computer, revoke-computer, computer-access, notifications |
cua agents#Install cua skills and the cua MCP server into AI coding agents. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua agents | AI coding agents on this machine: install cua skills and configure the cua MCP server. | detect, setup, status, remove, update |
cua skills#Record, list and replay demonstrations (skills). Reference.
| Command | Description | Subcommands |
|---|---|---|
cua skills | Recorded demonstrations (skills) for agents. | list, read, replay, delete, clean, record |
cua trajectory#Recorded cua do trajectories. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua trajectory | Recorded cua do trajectories. | ls, view, stop, clean |
cua spaces#Registered Spaces and your machines on the relay. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua spaces | Spaces: registered ones and your machines on the relay. | ls, add, create, cancel, gpus, delete, stop, start, rm, share, unshare, shares, relay-register, relay-unregister |
cua cloud#Your own AWS, Google Cloud or Modal account as a place for sandboxes and Spaces: connect, test, status, sweep. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua cloud | Spaces in your own cloud account (AWS, Google Cloud, Modal): connect, status, test, disconnect, sweep. | status, connect, test, disconnect, sweep |
cua host#Set this machine up for unattended access. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua host | Unattended access to this machine (setup, status, stop, start, remove). | setup, config, status, stop, start, share, unshare, remove |
cua devices#Enroll this device on the relay, approve, rename and revoke devices, and read the access log. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua devices | This device as a client of your cua.ai account on the relay: enroll (second factor), approve other devices, list, rename, revoke, and the audit log of who accessed what. | status, enroll, approve, ls, rename, revoke, audit |
cua teleport#Move a desktop app session into a sandbox. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua teleport | Move a desktop app session (tabs, profile, sign-in) into a sandbox. | providers, manifest, push |
cua volume#Cua Volume: files, versions, grants, access requests and audit of the volume every Space and agent shares. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua volume | Cua Volume: the versioned volume every Space and agent shares (public/, agents/<agent>/, spaces/<space>/), its grants and audit. | ls, cat, put, rm, history, restore, grant, revoke, grants, requests, approve, deny, audit, mount, unmount, status, config, config show, config set, config set-keys |
cua keyvault#Set up, unlock and lock the Cua Keyvault, with the OS key store or a passphrase. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua keyvault | The Cua Keyvault the daemon hosts: status, init, unlock, lock, saved passwords and approvals. | status, init, unlock, lock, import-passwords, import-session, requests, approve, deny |
cua spacesd#Talk to a cua-spacesd directly by URL. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua spacesd | Talk to a cua-spacesd directly by URL. | caps, exec, cp, shell, targets, call |
cua daemon#Start, stop and inspect the cua daemon. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua daemon | The cua daemon. | start, stop, status, mcp |
cua cache#See and reclaim the disk used by images, sandboxes, builds and logs. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua cache | Disk used by images, sandboxes, builds and logs, and its cleanup. | ls, du, prune, config |
cua runtime#Inspect and provision local runtimes. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua runtime | Local runtimes (cua-vmm). | doctor, setup |
cua doctor#Check the host, an image and a sandbox guest, or eval parity between image variants. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua doctor | Check the host, an image and a sandbox's guest in one report (cua doctor [REF]), or eval parity between two variants (cua doctor parity A B). | parity |
cua telemetry#Anonymous usage telemetry (status, off, show-last). Reference.
| Command | Description | Subcommands |
|---|---|---|
cua telemetry | Anonymous usage telemetry (status, on, off, show-last, reset-id, schema). | status, on, off, show-last, reset-id, schema |
Accepted by every command, before or after the subcommand.
| Flag | Type | Default | Env var | Description |
|---|---|---|---|---|
--embedded | boolean | false | Use an embedded runtime even when a daemon runs. | |
--daemon | string | CUA_DAEMON | Daemon address (socket path or loopback URL). | |
--daemon-token | string | CUA_DAEMON_TOKEN | Daemon token (loopback URLs). | |
--state-dir | string | Sandbox state directory (embedded; default ~/.cua/sandboxes). | ||
--json | boolean | false | Print JSON. |
--help prints help for any command; --version prints the version.
| 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. |