Add a computer

Connect another Mac, Windows or Linux computer you own to Cua Spaces, so your agents and your other devices can use it. Also how to turn a spare Mac into a place that runs Spaces.

A computer you add runs Spaces for you. Once it is added, it shows up in Computers on all your devices, your agents can create Spaces on it, and you can open its desktop from anywhere, even when nobody is sitting at it. Cua doesn't rent computers: add a Mac on your desk, a spare box in the office, or a VM in your own cloud account.

Add a computer from the app#

You need Cua Spaces on the computer you are adding, or its install command.

1. In Cua Spaces, open Computers and press Add a computer. You can also find it in the Getting Started checklist and the command palette.
2. If you belong to a team, choose who the computer is for next to Add it for: Just me or the team. See Team computers.
3. On the other computer, do one of these:
   • Open the link.
   • Scan the QR code with its camera.
   • Run the install command in its terminal. Choose macOS / Linux or Windows (preview) in the dialog to get the right command.
4. If Cua Spaces is already on that computer, open Computers there, press Join with a code and paste the code. The app asks before it joins.
5. Watch the dialog. It says "Waiting for the computer..." and then "Added", and the computer appears in your list.

The link and code work once and expire after a short time. The dialog shows how long is left. Press Revoke link to cancel one you no longer need, or Make a new link if it expired.

Add a computer from a terminal#

If you can't use the link, set the computer up yourself:

1. Install Cua Spaces on it. See Install.
2. Sign in with the same account you use here. A computer joins the account it is set up with.
3. Open This computer, choose how to use it, and press Set up for access.

Or run this in a terminal on that computer:

cua host setup          # signs in to cua.ai for this command if needed

cua host setup installs cua-spacesd as a background service. By default it joins the cua.ai relay with an outbound connection, as your account: no port forwarding and no token to copy. Your other devices, once enrolled, then see the computer as relay:<machine-id> in cua spaces ls and in the app.

The computer keeps only its own token. If it is not signed in, setup signs you in for that one command and stores no session, so a dedicated host holds no account credentials. The token lets the computer serve itself and stop sharing. It can't list or reach your other computers, change who the computer is shared with, or enroll devices. Running setup again updates the configuration and rotates the token.

What each system needs#

On Windows the host runs in your signed-in session, so your devices reach the desktop only while it is signed in, unlocked and on screen:

• After a restart, sign in once (or turn on automatic sign-in). The host starts at sign-in.
• Locked: Windows doesn't let apps see or use its lock screen. For unattended access, turn off automatic locking in Settings > Accounts > Sign-in options and the screen saver's "On resume, display logon screen".
• Remote Desktop: closing a Remote Desktop window leaves the session disconnected, and Windows stops drawing it. To leave a remote PC (a cloud VM) reachable, end Remote Desktop from an administrator prompt with tscon %sessionname% /dest:console instead.

A viewer or agent that connects in one of these states sees which one it is.

Reach it from your other devices#

A device reaches your computers through the cua.ai relay only after it is enrolled once with a second factor, so a stolen account session alone is not enough. A computer that only hosts is never enrolled as a client.

• Sign in. Signing in on your own computer enrolls it: run cua devices enroll right after cua auth login. A device that enrolled before enrolls again on its own when you sign in again.
• Approve. A brand-new device on an account that already has an enrolled device needs approval from one of them (or a sign-in whose token itself proves a second factor with your identity provider). cua devices enroll shows a one-time code. Approve it on an enrolled device with cua devices approve <code>, or in the app, which asks for Touch ID.

Every enrolled device is notified when a new one joins, in the app's notification feed and in cua devices audit, so a device you don't recognize doesn't slip in unnoticed. Enrollment lasts 30 days. After that, a fresh sign-in or one approval re-verifies the device. Until then, unattended agents on an enrolled device keep working without prompts.

cua devices enroll
cua devices approve K7QX-M2RP
cua devices approve dev_0123456789abcdef01234567
cua devices ls
cua devices audit      # who opened which machine, from which device, and when
cua devices revoke dev_0123456789abcdef01234567

In the app, Settings > Devices shows this device's enrollment, your devices with Rename and Revoke, and Recent Access (which device opened which computer, and when). When another device asks to join, the app shows an approval sheet: Approve asks for Touch ID or your login password first, and Deny revokes that device.

Share it with other accounts#

--allow at setup, or later from an enrolled device, shares the computer with another account (id or verified email). Sharing asks for confirmation. Unsharing cuts that account's open connections.

cua host share friend@example.com
cua host unshare friend@example.com

Check, pause or remove#

On the computer, run:

cua host status     # setup, service, who is connected; missing permissions
cua host stop       # disconnect everyone and refuse new connections
cua host start      # share again
cua host remove     # unregister, uninstall the service, delete ~/.cua/host

cua host stop turns sharing off locally first, so it holds even when the relay is unreachable. In direct mode, cua host status prints the URL and the path of the env token. Add the computer elsewhere with spaces.add(url, token).

Uninstalling the app turns sharing off too. On Linux, sudo apt remove cua-spaces (and purge) removes the computer, and the Spaces it provides, from the relay, deletes the cua-spacesd-host.service user unit and stops the daemon. Your Spaces and data under ~/.cua stay on the computer (the Spaces are turned off).

An owner or admin can remove a team computer at app.cua.ai/machines. Removing a computer doesn't delete anything on it.

Use a spare Mac to host Spaces#

A spare Mac mini in a closet can run Spaces for your laptop and your agents. Your laptop, or a coding agent on it, asks for Spaces through the cua.ai relay or directly over Tailscale. The mini runs them with its own runtimes, Lume for macOS VMs and Docker for Linux. Its own desktop, shell and files stay private. To share a computer's own desktop instead, use the steps above.

Set up the spare Mac#

On the spare Mac:

cua host setup --profile spare --name "Mac mini (spare)"

--profile spare is shorthand for --no-desktop --provide-spaces. Setup joins the relay the way the steps above do. It signs you in for that one command and keeps no account session, only the computer's own token.

The computer has two settings, and each works on its own:

With Share this desktop off, a relayed caller reaches only the Spaces service. Change either setting at any time:

cua host config                                    # show both settings and the Spaces it runs
cua host config --desktop on --provide-spaces on   # share the desktop too
cua host config --max-spaces 6                     # at most 6 Spaces at once (default 4)

The app's This computer page has the same two switches, the Spaces the computer provides, and every remote create and delete.

Over ssh or Tailscale#

A spare Mac mini you only reach over ssh (on your Tailscale or your LAN) works the same way. Tailscale is only the ssh transport here: hosting Spaces still goes through the cua.ai relay.

ssh mini.your-tailnet.ts.net
 
# on the mini, non-interactively:
curl -fsSL https://cua.ai/install.sh | sh -s -- -y --select spaces,host --no-onboarding

-y accepts the install without the checklist, --select spaces,host picks the Cua Spaces app and hosting, and --no-onboarding skips the automatic cua auth login (there is no browser to sign in with yet). Then set up the host with a device code:

cua host setup --remote --profile spare --name "Mac mini (spare)"

If the mini has no saved account session, this prints a URL and a short code that you approve in a browser on another device. The sign-in is held only for setup. An existing account session is reused.

Create Spaces on it from your laptop#

Your laptop must be enrolled for your account. Then ask your coding agent, through the cua MCP server:

spin up 2 macos spaces on my spare mac mini

The agent calls create_space with on="host:spare mac mini", image="macos" and count=2. From the CLI:

cua spaces create macos:26 --on "spare mac mini" --count 2
cua spaces create linux --on host:0123abcd4567ef89

The SDK takes the same on: spaces.create(on="host:spare mac mini", image="macos").

The computer is matched by its ID, its exact name, or the words of its name, so "spare mac mini" finds Mac mini (spare) or office-mac-mini. When two computers fit equally well, the call fails with ambiguous_host and lists them with their IDs, so the agent can ask you which one you meant.

Each new Space joins the relay as a computer of its own and comes back as relay:<machine>. Open it, stream it and run commands in it like any other Space.

List and delete work as for any Space:

cua spaces ls
cua spaces delete relay:space-0123456789abcdef

cua spaces ls (and the app's sidebar) groups the Spaces a computer provides under that computer. In list_spaces each one carries host (the computer's ID) and host_name. Deleting asks the computer to delete the VM or container, and the Space leaves the relay.

Limits#

A request past a limit fails with limit_exceeded and says which limit and what to do. macOS Spaces need a Mac host: a Linux or Windows host refuses them with host_capability_missing.

macOS Spaces run as Lume VMs. They need an Apple silicon Mac on macOS 13 or later with Lume installed, about 50 GB of free disk and 8 GB of free memory per macOS Space. The first one downloads the image, so it takes longer than the next ones. The host's cua-spacesd starts the cua daemon when a request comes in.

Who can create Spaces on it#

• You, from any device enrolled for your account.
• Accounts you share the computer with as editors (cua host share or cua spaces share relay:<machine> <who> --role editor). They see and delete only the Spaces they created. You see and delete all of them.
• Nobody else. The relay refuses a device that is not enrolled, and the computer refuses an account shared as a viewer.

Every remote create, delete and refusal is a line in the computer's hash-chained audit log (~/.cua/host/spaces-audit.jsonl). cua host status and the app show it, and warn when the log does not verify.

Agents follow per-agent computer access: a persistent agent uses a Space on your spare Mac only after you allow it, and a grant on the computer does not reach the Spaces it provides.

cua agent allow-computer ada relay:space-0123456789abcdef

Over Tailscale without the relay#

A spare Mac your laptop reaches by its Tailscale (or LAN) address can host Spaces without the cua.ai relay: no sign-in on either computer and no enrolled devices. Set it up on its Tailscale address:

cua host setup --direct 100.101.102.103:3211 --profile spare --name "Mac mini (spare)"

Use the Mac's own address from tailscale ip -4. With --direct 0.0.0.0:3211 it listens on every interface, and setup picks its Tailscale address (else its LAN address) for the next step. Setup prints the exact command to run on your laptop, with the Mac's token:

cua spaces add 100.101.102.103:3211 --host --name "Mac mini (spare)" --token <token>

The laptop keeps the token in its Spaces credential store (~/.cua/spaces-credentials.json, 0600) and lists the Mac in ~/.cua/direct-hosts.json. Then create Spaces on it as on any host:

cua spaces create macos:26 --on "spare mac mini" --count 2

on="host:<name>" looks at your computers on the relay first, then at the hosts you added with --host, with the same matching rules. Each new Space runs on the Mac with the same limits (four Spaces, two macOS VMs). It is not put on the relay: the Mac forwards a port on its own address to the Space's cua-spacesd, and your laptop adds it as direct:100.101.102.103:<port>. cua spaces ls lists it under the Mac, list_spaces marks it "via": "direct", and cua spaces delete, stop and start ask the Mac to do it. When a Space starts again, or the Mac restarts, the Mac opens the same port again.

Spare Mac errors#

If it doesn't work#

Next#

• Connect your agent: let an agent use the new computer.
• Create a Space: run a Space on it.
• Plans and Teams: share computers with your team.