cua host
Set this machine up for unattended access.
Set this machine up for unattended access.
| Command | Description |
|---|---|
cua host setup | Set this machine up for unattended access: install cua-spacesd as a service that joins the cua.ai relay as your account (default) or serves on a direct ip:port. |
cua host config | Show or change what this machine shares: its own desktop, and whether it creates Spaces for your other devices. |
cua host status | Show whether this machine is set up, the service, and who is connected. |
cua host stop | Stop sharing: disconnect everyone and refuse new connections. |
cua host start | Start sharing again after stop. |
cua host share | Share a relay machine (this one, or --machine) with other cua.ai accounts (id or verified email). |
cua host unshare | Stop sharing a relay machine with accounts; their open connections are cut. |
cua host remove | Unregister from the relay, uninstall the service and delete the host configuration (asks first). |
Every command also accepts the global options.
Unattended access to this machine (setup, status, stop, start, remove).
cua host [OPTIONS] <COMMAND>cua host setup#Set this machine up for unattended access: install cua-spacesd as a service that joins the cua.ai relay as your account (default) or serves on a direct ip:port.
cua host setup [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--relay | string | Relay URL (default $CUA_RELAY_URL, else https://relay.cua.ai). | |
--direct | string | Serve directly on ip:port with a local env token (LAN / port-forwarded) instead of joining a relay. | |
--name | string | Display name (default: the host name). | |
--allow | string | Also allow this account (id or email). Repeatable. | |
--driver-bin | path | cua-spacesd binary (default $CUA_SPACESD_BIN, a bundled one, or the release download). | |
--runner | string | auto | auto | systemd | launchd | windows-task | process. |
--profile | desktop | spare | desktop | What this machine is for: desktop (share this desktop; the default) or spare (do not share the desktop; provide Spaces). |
--max-spaces | integer | Provided Spaces at once (default 4; 0: no limit). | |
--desktop | boolean | false | Share this machine's own desktop as a Space. |
--no-desktop | boolean | false | Do not share this machine's own desktop (screen, input, shell, files): relayed callers reach only the Spaces it provides. |
--provide-spaces | boolean | false | Create Spaces for your enrolled devices on this machine's runtimes (Lume macOS VMs, Docker Linux containers). |
--no-provide-spaces | boolean | false | Do not create Spaces for other devices. |
--allow-any-address | boolean | false | With --direct and Spaces: take host calls, and connections to the Spaces this machine forwards, from any address (and allow a public --direct address). By default only loopback, Tailscale and private LAN addresses may. The direct listener is plaintext and its token is a shell on this machine: prefer Tailscale. |
Examples
# Join the cua.ai relay as your account (shares this desktop)
cua host setup
# A spare machine: do not share its desktop, run Spaces for your devices
cua host setup --profile spare --name "Mac mini (spare)"
cua host setup --no-desktop --provide-spaces
# Serve on the LAN instead of the relay
cua host setup --direct 0.0.0.0:3211 --name studio-mac
# A spare Mac on your tailnet that runs Spaces, without the relay (prints the command that adds it on your laptop)
cua host setup --direct 100.101.102.103:3211 --profile sparecua host config#Show or change what this machine shares: its own desktop, and whether it creates Spaces for your other devices.
cua host config [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--desktop | on | off | Share this machine's own desktop: on | off. | |
--provide-spaces | on | off | Create Spaces for your enrolled devices: on | off. | |
--max-spaces | integer | Provided Spaces at once (0: no limit). | |
--max-macos-vms | integer | macOS VMs at once, 0 to 2 (Apple's license allows two per Mac). |
Examples
cua host config
# Stop sharing this desktop; keep providing Spaces
cua host config --desktop off --provide-spaces on
cua host config --max-spaces 6cua host status#Show whether this machine is set up, the service, and who is connected.
cua host status [OPTIONS]Examples
cua host statuscua host stop#Stop sharing: disconnect everyone and refuse new connections.
cua host stop [OPTIONS]Examples
cua host stopcua host start#Start sharing again after stop.
cua host start [OPTIONS]Examples
cua host startcua host share#Share a relay machine (this one, or --machine) with other cua.ai accounts (id or verified email). Run from an enrolled device; every change is in the owner's audit log (cua devices audit).
cua host share [OPTIONS] <WHO>...| Argument | Type | Default | Description |
|---|---|---|---|
<WHO>... | string | required | Accounts to add. Repeatable. Repeatable. |
| Flag | Type | Default | Description |
|---|---|---|---|
--machine | string | Machine id (default: this machine). | |
--relay | string | Relay URL (default: the one this machine joined, else $CUA_RELAY_URL / https://relay.cua.ai). | |
--yes | boolean | false | Do not ask for confirmation. |
Examples
cua host share friend@example.com
cua host share friend@example.com --machine 0123abcd4567ef89 --yescua host unshare#Stop sharing a relay machine with accounts; their open connections are cut.
cua host unshare [OPTIONS] <WHO>...| Argument | Type | Default | Description |
|---|---|---|---|
<WHO>... | string | required | Accounts to remove. Repeatable. Repeatable. |
| Flag | Type | Default | Description |
|---|---|---|---|
--machine | string | Machine id (default: this machine). | |
--relay | string | Relay URL. |
Examples
cua host unshare friend@example.comcua host remove#Unregister from the relay, uninstall the service and delete the host configuration (asks first).
cua host remove [OPTIONS]| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--force | -f | boolean | false | Skip the confirmation prompt. Required when there is no terminal to ask on (scripts, agents): without it nothing is removed. |
Examples
cua host remove
# Without the prompt (required in scripts and agents)
cua host remove --force| 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. |