cua agent

Run coding agents (Claude Code, Codex, Gemini CLI, ...) inside a sandbox and follow, continue or stop them.

Command	Description
`cua agent run`	Start a coding agent in a sandbox (returns at once unless --follow).
`cua agent ls`	List runs in a sandbox.
`cua agent logs`	Print a run's normalized events (--follow to stream).
`cua agent send`	Send a follow-up (queued while a turn runs).
`cua agent interrupt`	Cancel the turn in flight (the session stays open).
`cua agent stop`	Stop a run and verify it is gone.
`cua agent status`	A run's status and last result.
`cua agent rm`	Stop a run and delete its record (secrets included).
`cua agent ensure`	Install harnesses or apps now (`claude-code`, `blender`, ...).
`cua agent harnesses`	The harnesses: readiness, installs, key variables, limits.
`cua agent create`	Create a persistent agent: a named harness whose memory lives in the Cua Volume (agents/NAME/) and outlives its Space.
`cua agent persistent`	List persistent agents.
`cua agent tell`	Give a persistent agent a turn (starts a run with its home restored, or follows up on its idle run).
`cua agent save`	Save a persistent agent's home into the drive now.
`cua agent pause`	Pause a persistent agent: its run, its routines, and its Space (suspended when local; a cloud Space is released after the home is saved).
`cua agent resume`	Resume a paused persistent agent.
`cua agent forget`	Forget a persistent agent (its home stays in the drive).
`cua agent routine`	A persistent agent's routines, fired by the daemon with or without the app open.
`cua agent routine add`	Add a routine (give one of --every, --daily, --weekly).
`cua agent routine ls`	List routines.
`cua agent routine rm`	Delete a routine.
`cua agent routine enable`	Turn a routine on.
`cua agent routine disable`	Turn a routine off.
`cua agent allow-computer`	Let a persistent agent use one of your computers (asks for presence).
`cua agent revoke-computer`	Take a persistent agent's computer access back.
`cua agent computer-access`	Which agents may use which computers, and the audit log.
`cua agent notifications`	The notifications the Cua app shows (turn ends, notify_user, requests).

Every command also accepts the global options.

Run coding agents inside a sandbox: run, ls, logs, send, interrupt, stop.

cua agent [OPTIONS] <COMMAND>

`cua agent run`#

Start a coding agent in a sandbox (returns at once unless --follow).

cua agent run [OPTIONS] <SANDBOX> <HARNESS> <PROMPT>

Argument	Type	Default	Description
`<SANDBOX>`	string	required	Sandbox (`local:NAME`, `cloud:NAME`, `direct:HOST:PORT`, or NAME).
`<HARNESS>`	string	required	Harness (`cua agent harnesses`).
`<PROMPT>`	string	required	The task.

Flag	Short	Type	Default	Description
`--env-from-host`		string		Forward a provider key from this shell's environment (repeatable), for example ANTHROPIC_API_KEY. The value never appears in argv.
`--repo`		string		Git repository cloned into the working directory first.
`--branch`		string
`--cwd`		string		Working directory in the sandbox.
`--model`		string
`--base-url`		string		A custom model endpoint (proxy or compatible server).
`--wire`		string		Its wire format: anthropic, openai-responses, openai-chat, gemini.
`--mcp`		string		An MCP server for the agent: NAME=URL (HTTP, as reachable inside the sandbox) or NAME=cmd:COMMAND ARGS... (stdio, run in the sandbox). Repeatable.
`--file`		path		Attach a local file to the prompt (repeatable).
`--label`		string
`--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-sandbox-mcp`		boolean	`false`	Do not give the agent the sandbox's own MCP tools.
`--no-skills`		boolean	`false`	Do not copy the cua skills into the harness.
`--exit-when-idle`		boolean	`false`	Stop (resumably) once the prompt is answered.
`--follow`	`-f`	boolean	`false`	Stream events until the turn ends.

Examples

cua agent run local:dev claude-code "fix the failing test" --env-from-host ANTHROPIC_API_KEY -f
cua agent run cloud:ci openai-codex "add tests" --repo https://github.com/org/repo --exit-when-idle

`cua agent ls`#

List runs in a sandbox.

cua agent ls [OPTIONS] <SANDBOX>

Alias: cua agent list.

Argument	Type	Default	Description
`<SANDBOX>`	string	required	Sandbox (`local:NAME`, `cloud:NAME`, `direct:HOST:PORT`, or 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 agent ls local:dev

`cua agent logs`#

Print a run's normalized events (--follow to stream).

cua agent logs [OPTIONS] <SANDBOX> <RUN_ID>

Argument	Type	Default	Description
`<SANDBOX>`	string	required
`<RUN_ID>`	string	required

Flag	Short	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`).
`--follow`	`-f`	boolean	`false`	Keep streaming until the turn ends.
`--raw`		boolean	`false`	Print each event's JSON (raw ACP payload included).

Examples

cua agent logs local:dev run-1a2b3c4d -f

`cua agent send`#

Send a follow-up (queued while a turn runs).

cua agent send [OPTIONS] <SANDBOX> <RUN_ID> <TEXT>

Argument	Type	Default
`<SANDBOX>`	string	required
`<RUN_ID>`	string	required
`<TEXT>`	string	required

Flag	Short	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`).
`--follow`	`-f`	boolean	`false`

Examples

cua agent send local:dev run-1a2b3c4d "now add a regression test" -f

`cua agent interrupt`#

Cancel the turn in flight (the session stays open).

cua agent interrupt [OPTIONS] <SANDBOX> <RUN_ID>

Argument	Type	Default	Description
`<SANDBOX>`	string	required
`<RUN_ID>`	string	required

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 agent interrupt local:dev run-1a2b3c4d

`cua agent stop`#

Stop a run and verify it is gone.

cua agent stop [OPTIONS] <SANDBOX> <RUN_ID>

Argument	Type	Default	Description
`<SANDBOX>`	string	required
`<RUN_ID>`	string	required

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 agent stop local:dev run-1a2b3c4d

`cua agent status`#

A run's status and last result.

cua agent status [OPTIONS] <SANDBOX> <RUN_ID>

Argument	Type	Default	Description
`<SANDBOX>`	string	required
`<RUN_ID>`	string	required

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 agent status local:dev run-1a2b3c4d

`cua agent rm`#

Stop a run and delete its record (secrets included).

cua agent rm [OPTIONS] <SANDBOX> <RUN_ID>

Argument	Type	Default	Description
`<SANDBOX>`	string	required
`<RUN_ID>`	string	required

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 agent rm local:dev run-1a2b3c4d

`cua agent ensure`#

Install harnesses or apps now (claude-code, blender, ...).

cua agent ensure [OPTIONS] <SANDBOX> <IDS>...

Argument	Type	Default	Description
`<SANDBOX>`	string	required
`<IDS>...`	string	required	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 agent ensure local:dev claude-code vscode

`cua agent harnesses`#

The harnesses: readiness, installs, key variables, limits.

cua agent harnesses [OPTIONS]

Examples

cua agent harnesses
cua --json agent harnesses

`cua agent create`#

Create a persistent agent: a named harness whose memory lives in the Cua Volume (agents/NAME/) and outlives its Space.

cua agent create [OPTIONS] --harness <HARNESS> --in <SPACE> <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required

Flag	Type	Default	Description
`--harness`	string	required	Harness id (`cua agent harnesses`).
`--in`	string	required	The Space it works in.
`--model`	string
`--base-url`	string
`--env-from-host`	string		Provider key variable to forward at each start. Repeatable.

Examples

cua agent create ada --harness hermes --in local:dev --env-from-host OPENAI_API_KEY
cua agent create scout --harness claude-code --in cloud:scout --env-from-host ANTHROPIC_API_KEY

`cua agent persistent`#

List persistent agents.

cua agent persistent [OPTIONS]

Examples

cua agent persistent

`cua agent tell`#

Give a persistent agent a turn (starts a run with its home restored, or follows up on its idle run).

cua agent tell [OPTIONS] <NAME> <TEXT>

Argument	Type	Default	Description
`<NAME>`	string	required
`<TEXT>`	string	required

Examples

cua agent tell ada "what did you learn yesterday?"

`cua agent save`#

Save a persistent agent's home into the drive now.

cua agent save [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required

Examples

cua agent save ada

`cua agent pause`#

Pause a persistent agent: its run, its routines, and its Space (suspended when local; a cloud Space is released after the home is saved).

cua agent pause [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required

Examples

cua agent pause ada

`cua agent resume`#

Resume a paused persistent agent.

cua agent resume [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required

Flag	Type	Default	Description
`--prompt`	string

Examples

cua agent resume ada
cua agent resume ada --prompt "pick up where you left off"

`cua agent forget`#

Forget a persistent agent (its home stays in the drive).

cua agent forget [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required

Examples

cua agent forget ada

`cua agent routine`#

A persistent agent's routines, fired by the daemon with or without the app open.

cua agent routine [OPTIONS] <COMMAND>

`cua agent routine add`#

Add a routine (give one of --every, --daily, --weekly).

cua agent routine add [OPTIONS] --title <TITLE> --prompt <PROMPT> <AGENT>

Argument	Type	Default	Description
`<AGENT>`	string	required

Flag	Type	Default	Description
`--title`	string	required
`--prompt`	string	required
`--every`	integer		Every N minutes.
`--daily`	string		Every day at HH:MM.
`--weekly`	string		Every week, `mon 09:00`.

Examples

cua agent routine add ada --title "Inbox sweep" --prompt "Triage new issues" --every 60
cua agent routine add ada --title "Morning" --prompt "Plan the day" --daily 08:00

`cua agent routine ls`#

List routines.

cua agent routine ls [OPTIONS] [AGENT]

Alias: cua agent routine list.

Argument	Type	Default	Description
`<AGENT>`	string	optional

Examples

cua agent routine ls
cua agent routine ls ada

`cua agent routine rm`#

Delete a routine.

cua agent routine rm [OPTIONS] <ID>

Argument	Type	Default	Description
`<ID>`	string	required

Examples

cua agent routine rm 0F3A2C1E-8B7D-4E6F-9A1B-2C3D4E5F6A7B

`cua agent routine enable`#

Turn a routine on.

cua agent routine enable [OPTIONS] <ID>

Argument	Type	Default	Description
`<ID>`	string	required

Examples

cua agent routine enable 0F3A2C1E-8B7D-4E6F-9A1B-2C3D4E5F6A7B

`cua agent routine disable`#

Turn a routine off.

cua agent routine disable [OPTIONS] <ID>

Argument	Type	Default	Description
`<ID>`	string	required

Examples

cua agent routine disable 0F3A2C1E-8B7D-4E6F-9A1B-2C3D4E5F6A7B

`cua agent allow-computer`#

Let a persistent agent use one of your computers (asks for presence).

cua agent allow-computer [OPTIONS] <NAME> <MACHINE>

Argument	Type	Default	Description
`<NAME>`	string	required
`<MACHINE>`	string	required	The machine's Space id (`cua host status` shows this machine's).

Flag	Type	Default	Description
`--for`	integer		End the grant after this many seconds.

Examples

cua agent allow-computer ada relay:0123456789abcdef

`cua agent revoke-computer`#

Take a persistent agent's computer access back.

cua agent revoke-computer [OPTIONS] <NAME> [MACHINE]

Argument	Type	Default	Description
`<NAME>`	string	required
`<MACHINE>`	string	optional

Examples

cua agent revoke-computer ada
cua agent revoke-computer ada relay:0123456789abcdef

`cua agent computer-access`#

Which agents may use which computers, and the audit log.

cua agent computer-access [OPTIONS] [NAME]

Argument	Type	Default	Description
`<NAME>`	string	optional

Flag	Type	Default	Description
`--audit`	integer	`0`	Also print this many audit entries.

Examples

cua agent computer-access --audit 20

`cua agent notifications`#

The notifications the Cua app shows (turn ends, notify_user, requests).

cua agent notifications [OPTIONS]

Flag	Type	Default	Description
`--unread`	boolean	`false`
`--mark-read`	boolean	`false`	Mark every notification read.

Examples

cua agent notifications --unread
cua agent notifications --mark-read

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.

cua agent

cua agent run#

cua agent ls#

cua agent logs#

cua agent send#

cua agent interrupt#

cua agent stop#

cua agent status#

cua agent rm#

cua agent ensure#

cua agent harnesses#

cua agent create#

cua agent persistent#

cua agent tell#

cua agent save#

cua agent pause#

cua agent resume#

cua agent forget#

cua agent routine#

cua agent routine add#

cua agent routine ls#

cua agent routine rm#

cua agent routine enable#

cua agent routine disable#

cua agent allow-computer#

cua agent revoke-computer#

cua agent computer-access#

cua agent notifications#

Exit codes#

cua agent run#

cua agent ls#

cua agent logs#

cua agent send#

cua agent interrupt#

cua agent stop#

cua agent status#

cua agent rm#

cua agent ensure#

cua agent harnesses#

cua agent create#

cua agent persistent#

cua agent tell#

cua agent save#

cua agent pause#

cua agent resume#

cua agent forget#

cua agent routine#

cua agent routine add#

cua agent routine ls#

cua agent routine rm#

cua agent routine enable#

cua agent routine disable#

cua agent allow-computer#

cua agent revoke-computer#

cua agent computer-access#

cua agent notifications#

Exit codes#

`cua agent run`#

`cua agent ls`#

`cua agent logs`#

`cua agent send`#

`cua agent interrupt`#

`cua agent stop`#

`cua agent status`#

`cua agent rm`#

`cua agent ensure`#

`cua agent harnesses`#

`cua agent create`#

`cua agent persistent`#

`cua agent tell`#

`cua agent save`#

`cua agent pause`#

`cua agent resume`#

`cua agent forget`#

`cua agent routine`#

`cua agent routine add`#

`cua agent routine ls`#

`cua agent routine rm`#

`cua agent routine enable`#

`cua agent routine disable`#

`cua agent allow-computer`#

`cua agent revoke-computer`#

`cua agent computer-access`#

`cua agent notifications`#

`cua agent run`#

`cua agent ls`#

`cua agent logs`#

`cua agent send`#

`cua agent interrupt`#

`cua agent stop`#

`cua agent status`#

`cua agent rm`#

`cua agent ensure`#

`cua agent harnesses`#

`cua agent create`#

`cua agent persistent`#

`cua agent tell`#

`cua agent save`#

`cua agent pause`#

`cua agent resume`#

`cua agent forget`#

`cua agent routine`#

`cua agent routine add`#

`cua agent routine ls`#

`cua agent routine rm`#

`cua agent routine enable`#

`cua agent routine disable`#

`cua agent allow-computer`#

`cua agent revoke-computer`#

`cua agent computer-access`#

`cua agent notifications`#