Your pool

Run Python functions on your pool, each member in a Space (`cua run`, `cua jobs`). Computers join with `cua host setup --no-desktop --provide-spaces` (or `--pair CODE` from `cua host pair`) and `cua cloud add aws`; `cua computers` lists them.

Command	Description
`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.
`cua jobs logs`	A run's output, every rank (`[rank R host]`) or one.
`cua jobs cancel`	Cancel a run (every member stops).
`cua jobs result`	Save rank 0's 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`).
`cua compat serve`	Serve a provider's wire protocol from Cua Spaces until stopped.
`cua compat env`	Print the shell exports for a client of the gateway (`eval` them).

Every command also accepts the global options.

`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 computers [OPTIONS]

Examples

cua computers
cua computers --json

`cua run`#

Run a Python function on your pool: FILE::FN, decorated with @app.function(...) (the cua jobs shim). Each member runs in a Space (a macOS VM with GPU on a Mac, the computer's own Space on a dedicated host, a container elsewhere); a lost computer re-places the gang and the job resumes from its checkpoints. Rank 0's result is saved in ./cua-runs/<run>/.

cua run [OPTIONS] [TARGET] [-- <COMMAND>...]

Argument	Type	Default	Description
`<TARGET>`	string	optional	`FILE::FN`: a function decorated with `@app.function(...)` in FILE. Or leave it out and give a command after `--`.
`<COMMAND>...`	string	optional	A command to run in a Space instead of `FILE::FN` (`cua run -- CMD ARGS...`); the current directory goes with it like FILE's does. Repeatable.

Flag	Short	Type	Default	Description
`--compat`		string		Give the command another provider's sandbox API on Cua Spaces: `e2b`, `daytona` or `modal`. Its SDK finds the gateway in the environment (E2B_API_URL, E2B_API_KEY, ...; DAYTONA_API_URL, DAYTONA_API_KEY; MODAL_SERVER_URL, MODAL_TOKEN_ID, MODAL_TOKEN_SECRET) and needs no code change; the sandboxes it makes are Cua Spaces on your pool.
`--kind`		string		The command's Space kind (`container`, `vm`, `microvm`; default: the host's pick). Command form only.
`--image`		string		The command's Space image (default: the host's). Command form only.
`--nodes`		string		Members of the gang, `N` or `MIN:MAX` (default: the decorator's).
`--on`		string		Where: `local` (this machine; the default for a command), `auto` (any of your hosts) or `host:NAME` (default for a function: the decorator's).
`--accelerator`		string		`gpu` (any), `apple`, `nvidia`, or `none` (default: the decorator's).
`--retries`		integer		Times the gang is placed again after a failure or a lost computer (default: the decorator's).
`--cpus`		number	`2`	CPUs reserved for each member.
`--memory`		integer	`4096`	Memory reserved for each member, in MiB.
`--env`	`-e`	string		`KEY=VALUE` for every member's environment (over the decorator's `env=`), or `KEY` alone for this shell's value (secrets: never printed). Repeatable.
`--id`		string		The run's id (default: a new one).
`--detach`		boolean	`false`	Submit, print the run's id and return.

Examples

cua run train.py::finetune
cua run train.py::finetune --nodes 1:2 --accelerator gpu
cua run train.py::finetune --on host:aws-1 --detach

`cua jobs`#

Runs on your pool: the list, one run's members and cost, its logs, cancel, and its result.

cua jobs [OPTIONS] [RUN]
       cua jobs <COMMAND>

Argument	Type	Default	Description
`<RUN>`	string	optional	A run: its members, attempts, hosts, state and cost.

Examples

cua jobs
cua jobs p-finetune-1a2b3c4d
cua jobs logs -f p-finetune-1a2b3c4d --rank 0
cua jobs cancel p-finetune-1a2b3c4d
cua jobs result p-finetune-1a2b3c4d -o ./adapter

`cua jobs logs`#

A run's output, every rank ([rank R host]) or one.

cua jobs logs [OPTIONS] <RUN>

Argument	Type	Default	Description
`<RUN>`	string	required	The run.

Flag	Short	Type	Default	Description
`--rank`		integer		Only this rank.
`--follow`	`-f`	boolean	`false`	Keep following until the run ends.

Examples

cua jobs logs -f p-finetune-1a2b3c4d
cua jobs logs p-finetune-1a2b3c4d --rank 1

`cua jobs cancel`#

Cancel a run (every member stops).

cua jobs cancel [OPTIONS] <RUN>

Argument	Type	Default	Description
`<RUN>`	string	required	The run.

Examples

cua jobs cancel p-finetune-1a2b3c4d

`cua jobs result`#

Save rank 0's result.

cua jobs result [OPTIONS] <RUN>

Argument	Type	Default	Description
`<RUN>`	string	required	The run.

Flag	Short	Type	Default	Description
`--output`	`-o`	path		Directory (default ./cua-runs/<run>).

Examples

cua jobs result p-finetune-1a2b3c4d
cua jobs result p-finetune-1a2b3c4d -o ./adapter

`cua compat`#

Run another provider's SDK unchanged on Cua Spaces: a local gateway that speaks its wire protocol (cua compat serve --provider e2b).

cua compat [OPTIONS] <COMMAND>

`cua compat serve`#

Serve a provider's wire protocol from Cua Spaces until stopped.

cua compat serve [OPTIONS]

Flag	Type	Default	Description
`--provider`	string	`e2b`	Provider whose SDK clients use (`e2b`, `daytona`, `modal`).
`--listen`	string		API (and envd) listen address. Loopback by default.
`--host-port`	integer		Port of the `<port>-<id>.<domain>` host router (TLS and plain HTTP).
`--on`	string		Where new Spaces run (default: the core default, this machine; `auto`: least-loaded machine of your pool; `host:<machine>`).
`--kind`	string		Space kind (`vm`: Linux on QEMU/HVF or KVM; `container`; `microvm`). Default: `vm` where this machine can run one, else `container`.
`--image`	string		Image for the provider's base template (default: the canonical Linux image).
`--cpus`	integer		vCPUs per Space.
`--memory-mb`	integer		Memory per Space (MiB).
`--overlay`	string		Inject a freshly built binary into every new sandbox, `NAME=PATH[:GUEST_PATH]` (as `cua sandbox create --overlay`), for trying a guest agent that no image carries yet. Repeatable.
`--default-user`	string		The guest user for the provider's default user (default: the provider's own: `user` for E2B, `daytona` for Daytona, `root` for Modal).
`--no-warm`	boolean	`false`	Do not make a first sandbox before serving. By default `serve` pulls the image and boots one default sandbox (then deletes it) and only then prints the `Clients export` line, so the first create of a separate client program cannot outlast the SDK's request timeout.
`--no-create-user`	boolean	`false`	Do not create the default user in images that lack it.

Examples

cua compat serve --provider e2b
cua compat serve --provider daytona --on host:mac-studio --kind vm
cua compat serve --provider modal
cua compat serve --provider e2b --overlay cua-spacesd=./target/debug/cua-spacesd

`cua compat env`#

Print the shell exports for a client of the gateway (eval them).

cua compat env [OPTIONS]

Flag	Type	Default	Description
`--provider`	string	`e2b`	Provider whose SDK the client uses (`e2b`, `daytona`, `modal`).
`--listen`	string		API listen address of the running gateway.
`--host-port`	integer		Host-router port of the running gateway.

Examples

cua compat env --provider e2b
cua compat env --provider daytona

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.

Your pool

cua computers#

cua run#

cua jobs#

cua jobs logs#

cua jobs cancel#

cua jobs result#

cua compat#

cua compat serve#

cua compat env#

Exit codes#

`cua computers`#

`cua run`#

`cua jobs`#

`cua jobs logs`#

`cua jobs cancel`#

`cua jobs result`#

`cua compat`#

`cua compat serve`#

`cua compat env`#