cua
Cua: sandboxes, computer actions, MCP, skills and the cua daemon.
cua [OPTIONS] <COMMAND>Run cua <command> --help for the build you have.
Commands#
Spaces#
Your Spaces, and a cua-spacesd by URL. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua spaces | Spaces: registered ones and your computers on the relay. | ls, add, create, prewarm, egress, children, budget, orphans, service, service add, service ls, service logs, service start, service stop, service restart, service rm, cancel, gpus, delete, stop, suspend, resize, start, rm, default, rename, set, share, unshare, shares, relay-register, relay-unregister |
cua spacesd | Talk to a cua-spacesd directly by URL. | caps, exec, cp, shell, targets, call |
Computers and teams#
Your computers, unattended access on this computer, teams and your remote use this month. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua host | Unattended access to this computer (setup, status, stop, start, remove). | setup, pair, config, cache, cache status, cache fill, cache clear, status, stop, start, share, unshare, migrate, remove |
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 team | Teams (organizations of your cua.ai account) share computers with every member and their agents. | create, ls, show, invite, join, leave, remove-member, set-role, devices, approve, deny, request, add-machine, remove-machine, audit, delete |
cua usage | Your remote use this month: computers in use at once, remote hours, and your plan. |
Sharing and Space networks#
Share a port, file or folder as a link or a public TCP address, set what a Space can reach and where its traffic leaves, the exit through this computer, and the paths between your computers. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua share | Share a link to a port, a file or a folder that opens on your other signed-in devices (never localhost): cua share 3000, cua share ./report.html, cua share ls, cua share stop ID. | ls, stop, check, approve, deny, settings |
cua network | What a Space can reach on the network, and changing it: show, set, log. | show, set, log |
cua hotspot | Send a Space's internet traffic out through this computer for a while: start, stop, status. | start, stop, status |
cua mesh | How traffic reaches your other computers: status (and --prefer). | status |
Files, teleport and keys#
Cua Volume files and sharing, moving an app session into a sandbox, and the Cua Keyvault. 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, named, named ls, named create, named rm |
cua teleport | Move a desktop app session (tabs, profile, sign-in) into a sandbox. | providers, manifest, push, doctor |
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 |
Sandboxes#
Create, reach and delete sandboxes; local runtimes, disk cleanup and the sandbox viewer. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua sandbox | Sandboxes: local or an existing computer (direct). | create, launch, connect, ls, info, suspend, resume, restart, checkpoint, fork, fork-many, publish, bake, pool, pool create, pool ls, pool rm, checkpoints, checkpoints rm, checkpoints pin, checkpoints unpin, checkpoints prune, rm, exec, run, runs, shell, cp, overlay, logs, port-forward, url, screenshot, mcp, mcp config, mcp info, mcp tools, mcp call, mcp resources, mcp templates, mcp read, mcp prompts, mcp prompt, mcp request, view |
cua runtime | Local runtimes (cua-vmm). | doctor, setup |
cua cache | Disk used by images, sandboxes, builds and logs, and its cleanup. | ls, du, prune, config |
cua viewer | Serve the HTML5 viewer for every sandbox on one loopback port. |
CI runners#
Run GitHub Actions jobs in a fresh Space each on your own computers (an experiment: cua experiments enable ci-runners). Reference.
| Command | Description | Subcommands |
|---|---|---|
cua ci | Cua CI, GitHub Actions jobs on Cua Spaces: each job runs in a fresh Space (a macOS VM or a Linux container or VM) registered with a just-in-time runner, then deleted. | connect, add, remove, status, overview, why, config, disconnect, serve, ls, logs, stop, start, cache, cache clear |
Images and your cloud#
Pull, build, push and publish images, and the cloud account you link for machines. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua image | Images: local OCI pull/build/push. | pull, build, push |
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 build | Build an image from a Dockerfile, in a Space, as pinned checkpoints that Spaces fork from in under a second. | |
cua cloud | Spaces in your own cloud account (AWS, Google Cloud, Hetzner, Modal): connect, status, test, disconnect, sweep; and pool hosts there (cua cloud add aws). | status, connect, approve, trust, test, disconnect, audit, cost, sweep, add, add aws, plan, hosts, hosts list, hosts add, hosts remove, budget, reconcile |
Computer actions#
One-shot computer actions (screenshot, click, type, windows) against a selected target, and their recorded trajectories. 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 trajectory | Recorded cua do trajectories. | ls, view, stop, clean |
Agents, MCP and skills#
Agents in a Space, connecting your AI agents and the AI providers they use, the stdio MCP server, and recorded skills. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua agent | Agents in a Space: add, send, ls, rm, schedule; run, logs, stop. | add, run, ls, logs, send, interrupt, stop, status, rm, ensure, schedule, schedule add, schedule ls, schedule rm, schedule enable, schedule disable, sessions, harnesses, keys, keys ls, keys set, keys check, keys rm, 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 thread | A Space's thread, as the agent this computer joined with cua join: say who you are, read your inbox, post. | join, inbox, post, read |
cua join | Join a Space as an agent on this computer, with the code from a "Join my Cua Space" link. | |
cua connect | Connect the AI agents on this computer to Cua: install the cua skills and configure the cua MCP server. | detect, setup, status, remove, update |
cua connections | The AI providers connected once for every app that can use them: list, add (a key from stdin), test, remove. | list, add, test, remove, github, github status, github rescan, github use, github on, github off |
cua agents | Deprecated alias of connect. | detect, setup, status, remove, update |
cua mcp | Stdio MCP server exposing sandboxes, computer control and skills. | |
cua skills | Recorded demonstrations (skills) for agents. | list, read, replay, delete, clean, record |
Account and setup#
Sign in and out, user defaults, the cua daemon, health checks and usage telemetry. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua auth | Log in to Cua and manage the signed-in session. | login, logout, status, whoami, provider, provider ls, provider set, provider rm |
cua config | User defaults (~/.cua/config.toml): where sandboxes run when --on is not given (default.on), the default kind and runtime. | list, get, set, unset, path |
cua daemon | The cua daemon. | start, stop, reap, status, mcp |
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, on, off, show-last, reset-id, schema). | status, on, off, show-last, reset-id, schema |
cua experiments | Features that are still being built, one switch each: list, enable, disable. | list, enable, disable |
Your pool#
Run Python functions on your pool, each member in a Space (cua run, cua jobs). Computers join with cua host setup --share spaces (or --pair CODE from cua host pair) and cua cloud add aws; cua computers lists them. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua computers | The computers in your pool, as its coordinator sees them now: state, OS/arch, load, jobs, accelerators and $/h, with the queue. | |
cua run | Run a Python function on your pool: FILE::FN, decorated with @app.function(...) (the cua jobs shim). | |
cua jobs | Runs on your pool: the list, one run's members and cost, its logs, cancel, and its result. | logs, cancel, result |
cua compat | Run another provider's SDK unchanged on Cua Spaces: a local gateway that speaks its wire protocol (cua compat serve --provider e2b). | serve, env |
Benchmarks#
Spaces performance benchmarks: list them, run one in Spaces of its own (result.json and samples.csv in the bench-result v1 format), and check a run against a committed baseline. Reference.
| Command | Description | Subcommands |
|---|---|---|
cua bench | Spaces performance benchmarks: list them, run one in Spaces of its own (writes result.json and samples.csv in the bench-result v1 format), and check a run against a committed baseline. | list, run, check |
Global options#
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.
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). |
8 | No room on the machine: its VMs are at their memory or CPU limit, or it is low on memory. |
130 | Cancelled (Ctrl-C during a create): what it made was removed. |