cua host

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 pair`	Make a one-time code (with a link and the install command) that adds another computer to your account: run the command it prints on that computer.
`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 the CUA_ENV relay, https://relay.cua.ai in production).
`--pair`	string		Join with a one-time pairing code (or add-machine link) made in the Cua Spaces app or with `cua host pair`, instead of signing in here. The machine joins the account (or team) that made it.
`--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).
`--remote`	boolean	`false`	When sign-in is needed, use a device code to approve it in a browser on another machine. The account session is not saved.
`--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 spare
 
# Add this machine with a one-time code from the Cua Spaces app (Add a machine) or `cua host pair`: no sign-in needed here
cua host setup --pair K7QM-4XPB-2RHD

`cua host pair`#

Make a one-time code (with a link and the install command) that adds another computer to your account: run the command it prints on that computer. Codes work once and expire (30 minutes by default). Run from an enrolled device.

cua host pair [OPTIONS]

Flag	Type	Default	Description
`--team`	string		Add the machine to this team (id, alias or name; owner or admin): waits until the machine joins, then makes it a team machine.
`--name`	string		Name the machine gets (default: its own host name).
`--expires`	integer	`30`	Minutes until the code expires (1 to 1440).
`--revoke`	string		Revoke an unused code by id (`pc_…`).
`--relay`	string		Relay URL (default $CUA_RELAY_URL, else the CUA_ENV relay, https://relay.cua.ai in production).
`--no-wait`	boolean	`false`	With --team: print the code and exit instead of waiting; add the machine later with `cua team add-machine <team> relay:<id>`.
`--list`	boolean	`false`	List your codes (used, unused, revoked, expired) instead.

Examples

cua host pair
cua host pair --name build-box --expires 60
cua host pair --list
cua host pair --revoke pc_0123456789abcdef
 
# Add the machine to a team: waits for it to join, then adds it
cua host pair --team AIGIS

`cua 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	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 6

`cua host status`#

Show whether this machine is set up, the service, and who is connected.

cua host status [OPTIONS]

Examples

cua host status

`cua host stop`#

Stop sharing: disconnect everyone and refuse new connections.

cua host stop [OPTIONS]

Examples

cua host stop

`cua host start`#

Start sharing again after stop.

cua host start [OPTIONS]

Examples

cua host start

`cua 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 --yes

`cua 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.com

`cua 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.
`--uninstalling`		boolean	`false`	For an uninstall of Cua Spaces: turns off the Spaces this machine provides and takes them off the relay too, instead of refusing while it provides any. The Spaces and their data stay on this machine.

Examples

cua host remove
 
# Without the prompt (required in scripts and agents)
cua host remove --force

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 host

cua host setup#

cua host pair#

cua host config#

cua host status#

cua host stop#

cua host start#

cua host share#

cua host unshare#

cua host remove#

Exit codes#

cua host setup#

cua host pair#

cua host config#

cua host status#

cua host stop#

cua host start#

cua host share#

cua host unshare#

cua host remove#

Exit codes#

`cua host setup`#

`cua host pair`#

`cua host config`#

`cua host status`#

`cua host stop`#

`cua host start`#

`cua host share`#

`cua host unshare`#

`cua host remove`#

`cua host setup`#

`cua host pair`#

`cua host config`#

`cua host status`#

`cua host stop`#

`cua host start`#

`cua host share`#

`cua host unshare`#

`cua host remove`#