cua spaces
Registered Spaces and your machines on the relay.
Registered Spaces and your machines on the relay.
| Command | Description |
|---|---|
cua spaces ls | Registered Spaces and your machines on the relay. |
cua spaces add | Register a Space after a capabilities handshake with its cua-spacesd (or, for another URL, an MCP initialize). |
cua spaces create | Create Spaces: on this machine, on one of your machines that provides Spaces (cua host setup --provide-spaces there), or in the cloud. |
cua spaces cancel | Cancel a create that is still running (here, in the daemon, or in another terminal): it stops and what it made is removed. |
cua spaces gpus | The GPU options each runtime offers on this machine (or in the cloud). |
cua spaces delete | Delete a Space's sandbox (on this machine, on the machine that provides it, or in the cloud) and forget it (asks first). |
cua spaces stop | Turn a Space off: a local container or QEMU VM is suspended (its memory is kept), a Lume VM or a Space one of your machines provides is stopped (its disk is kept), and so is a Space in your own cloud (--on aws, gcp; compute billing stops). |
cua spaces start | Turn a Space back on: resume a suspended one or boot a stopped one. |
cua spaces rm | Forget a registered Space and its stored token. |
cua spaces share | Let another cua.ai account watch (viewer) or use (editor) a Space, through the relay. |
cua spaces unshare | Stop sharing a Space with one account at once, or with everyone. |
cua spaces shares | Who a Space is shared with, and who of them is connected now. |
cua spaces relay-register | Publish a Space on the relay for your other devices (a phone off this network): its own driver dials out, as cua host setup does for this computer. |
cua spaces relay-unregister | Take a Space off the relay (every share with it ends). |
Every command also accepts the global options.
Spaces: registered ones and your machines on the relay.
cua spaces [OPTIONS] <COMMAND>cua spaces ls#Registered Spaces and your machines on the relay.
cua spaces ls [OPTIONS]Alias: cua spaces list.
| Flag | Type | Default | Description |
|---|---|---|---|
--relay | string | Relay URL (default $CUA_RELAY_URL, else https://relay.cua.ai). |
Examples
cua spaces ls
cua spaces ls --jsoncua spaces add#Register a Space after a capabilities handshake with its cua-spacesd (or, for another URL, an MCP initialize). Re-adding an address updates it. The token is stored apart from the registry, 0600.
cua spaces add [OPTIONS] <URL>| Argument | Type | Default | Description |
|---|---|---|---|
<URL> | string | required | The Space's cua-spacesd (http(s)://host:port, host:port, default port 3211), a Space id (local:<name>, cloud:<name>), or any MCP endpoint URL. |
| Flag | Type | Default | Env var | Description |
|---|---|---|---|---|
--token | string | CUA_ENV_TOKEN | spacesd token (or the bearer an MCP endpoint needs). | |
--name | string | Display name (default: the guest's hostname). | ||
--service | string | For an MCP endpoint URL: the service name to register it under (default mcp). | ||
--host | boolean | false | It is a machine that provides Spaces over its direct address (Tailscale or LAN): --on host:<name> finds it without the relay. Its token is stored like any direct Space's. |
Examples
cua spaces add 10.0.0.5:3211 --token "$TOKEN" --name studio
cua spaces add local:my-sandbox
cua spaces add http://127.0.0.1:8765/mcp --service tools
# A machine that provides Spaces over Tailscale, without the relay (`cua host setup --direct ... --provide-spaces` on it prints this)
cua spaces add 100.101.102.103:3211 --host --name "Mac mini (spare)" --token "$TOKEN"cua spaces create#Create Spaces: on this machine, on one of your machines that provides Spaces (cua host setup --provide-spaces there), or in the cloud.
cua spaces create [OPTIONS] [IMAGE]| Argument | Type | Default | Description |
|---|---|---|---|
<IMAGE> | string | optional | Image: an alias (linux, macos, macos:26) or a registry reference. Default: the canonical Linux image. |
| Flag | Type | Default | Description |
|---|---|---|---|
--on | string | Where: local, cloud, host:<machine>, or a machine name (mac-mini, "spare mac mini"). Default: your default location. | |
--count | integer | 1 | How many (1 to 8). |
--name | string | Name (with --count, -2, -3, ... are appended). | |
--kind | string | auto | container | vm. | |
--runtime | string | auto, or an engine the location offers (lume, runc, gvisor, qemu). | |
--cpus | integer | vCPUs. | |
--memory-mb | integer | Memory in MiB. | |
--disk-gb | integer | Grow a VM's disk to this many GiB. | |
--gpu | string | A GPU: the runtime's own (--gpu), or an option cua spaces gpus lists. macOS VMs: GPU acceleration (experimental, Apple silicon; https://cua.ai/docs/lume/guides/gpu-passthrough). |
Examples
cua spaces create linux
# Two macOS VMs on your spare Mac mini (matched by name)
cua spaces create macos:26 --on "spare mac mini" --count 2
cua spaces create --on host:0123abcd4567ef89 linux --jsoncua spaces cancel#Cancel a create that is still running (here, in the daemon, or in another terminal): it stops and what it made is removed. Finished image downloads stay cached. Ctrl-C during cua spaces create does the same.
cua spaces cancel [OPTIONS] <SPACE>| Argument | Type | Default | Description |
|---|---|---|---|
<SPACE> | string | required | The id the Space will have (local:<name>, printed when the create starts) or its name. |
Examples
cua spaces cancel local:space-1a2b3c
cua spaces cancel studiocua spaces gpus#The GPU options each runtime offers on this machine (or in the cloud).
cua spaces gpus [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--on | string | local (default) or cloud. |
Examples
cua spaces gpus
cua spaces gpus --jsoncua spaces delete#Delete a Space's sandbox (on this machine, on the machine that provides it, or in the cloud) and forget it (asks first).
cua spaces delete [OPTIONS] <SPACE>| Argument | Type | Default | Description |
|---|---|---|---|
<SPACE> | string | required | Space id or name. |
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--force | -f | boolean | false | Skip the confirmation (required without a terminal). |
Examples
cua spaces delete relay:space-0123456789abcdef
cua spaces delete local:studio --forcecua spaces stop#Turn a Space off: a local container or QEMU VM is suspended (its memory is kept), a Lume VM or a Space one of your machines provides is stopped (its disk is kept), and so is a Space in your own cloud (--on aws, gcp; compute billing stops). Fleet cloud Spaces, Modal sandboxes and Spaces added by address cannot be turned off.
cua spaces stop [OPTIONS] <SPACE>| Argument | Type | Default | Description |
|---|---|---|---|
<SPACE> | string | required | Space id or name. |
Examples
cua spaces stop local:studio
cua spaces stop relay:space-0123456789abcdef --jsoncua spaces start#Turn a Space back on: resume a suspended one or boot a stopped one.
cua spaces start [OPTIONS] <SPACE>| Argument | Type | Default | Description |
|---|---|---|---|
<SPACE> | string | required | Space id or name. |
Examples
cua spaces start local:studio
cua spaces start studio --jsoncua spaces rm#Forget a registered Space and its stored token. The sandbox keeps running.
cua spaces rm [OPTIONS] <SPACE>Alias: cua spaces remove.
| Argument | Type | Default | Description |
|---|---|---|---|
<SPACE> | string | required | Space id, address or display name (as cua spaces ls shows). |
Examples
cua spaces rm direct:10.0.0.5:3211
cua spaces rm studiocua spaces share#Let another cua.ai account watch (viewer) or use (editor) a Space, through the relay. They open it as relay:<machine>.
cua spaces share [OPTIONS] <SPACE> <WHO>| Argument | Type | Default | Description |
|---|---|---|---|
<SPACE> | string | required | Space id, address or display name. |
<WHO> | string | required | Their email (verified by cua.ai) or account id. |
| Flag | Type | Default | Description |
|---|---|---|---|
--role | viewer | editor | viewer | viewer: presence and a view-only stream. editor: full use. |
--yes | boolean | false | Confirm without a prompt (needed without a terminal when no daemon runs; a running daemon asks with Touch ID or your password instead). |
Examples
cua spaces share local:studio bob@example.com
cua spaces share local:studio bob@example.com --role editor
cua spaces share relay:0123abcd4567ef89 acct-42 --role viewercua spaces unshare#Stop sharing a Space with one account at once, or with everyone.
cua spaces unshare [OPTIONS] <SPACE> [WHO]| Argument | Type | Default | Description |
|---|---|---|---|
<SPACE> | string | required | Space id, address or display name. |
<WHO> | string | optional | Their email or account id. |
| Flag | Type | Default | Description |
|---|---|---|---|
--all | boolean | false | Stop sharing with everyone (the Space leaves the relay). |
Examples
cua spaces unshare local:studio bob@example.com
cua spaces unshare local:studio --allcua spaces shares#Who a Space is shared with, and who of them is connected now.
cua spaces shares [OPTIONS] <SPACE>| Argument | Type | Default | Description |
|---|---|---|---|
<SPACE> | string | required | Space id, address or display name. |
Examples
cua spaces shares local:studio
cua spaces shares local:studio --jsoncua spaces relay-register#Publish a Space on the relay for your other devices (a phone off this network): its own driver dials out, as cua host setup does for this computer. Nobody else gets in until you share it.
cua spaces relay-register [OPTIONS] <SPACE>| Argument | Type | Default | Description |
|---|---|---|---|
<SPACE> | string | required | Space id, address or display name. |
Examples
cua spaces relay-register local:studiocua spaces relay-unregister#Take a Space off the relay (every share with it ends).
cua spaces relay-unregister [OPTIONS] <SPACE>| Argument | Type | Default | Description |
|---|---|---|---|
<SPACE> | string | required | Space id, address or display name. |
Examples
cua spaces relay-unregister local:studio| 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. |