cua Spaces

Spaces are exposed as MCP tools by the cua MCP server (cua mcp). If the tools below are missing, ask the user to run cua agents setup or cua auth login.

Get a Space

Tool	Use
`list_spaces`	See the Spaces you can use. Start here.
`create_space`	A new Space: `on` = `local` (free, the user's machine), `aws`, `gcp` or `modal` (the user's own cloud account, billed there), or `host:<name>` (one of the user's machines set up with `cua host setup`); `reuse: true` returns a reachable one first.
`add_space` / `remove_space`	Register an existing machine by URL and token, or forget one without deleting it.
`delete_space`	Delete a Space's sandbox and stop its cost.
`stop_space` / `start_space`	Turn a local Space (or one your machines provide) off and back on: suspended or stopped, as `power` in `list_spaces` says.

Prefer an existing Space. A Space in the user's own cloud account costs money: delete the ones you created when the task ends.

Work in it

Tool	Use
`space_bash`	Run a shell command (`space`, `command`, optional `timeout`).
`space_write`	Write text to a file.
`upload` / `download`	Copy files or folders in and out.
`send_file`	Drop a host file into the Space's Downloads (sha256 verified).
`list_tools` / `call_tool`	Reach MCP services running inside the Space.

Show it to the user

Tool	Use
`open_space_viewer`	Open the full desktop viewer.
`show_space_pip` / `hide_space_pip`	Picture-in-picture on the user's screen.
`list_space_windows` / `stream_space_window`	Show one window from the Space.
`stream_endpoint`	Get a ticketed media URL for the desktop or a window.

Agents, apps and network

Tool	Use
`agent_capabilities`	Which agent harnesses the Space supports.
`agent_start`	Start an agent run (`space`, `agent`, `prompt`).
`agent_status` / `agent_message` / `agent_stop` / `agent_list`	Follow, steer and stop runs.
`teleport_manifest`	Preview what moving an app session would copy.
`teleport_app`	Move a signed-in app session (tabs, profile) into the Space.
`hotspot_start` / `hotspot_status` / `hotspot_stop`	Share the host's network with a Space.

Set up a host over ssh (Tailscale or LAN)

To host Spaces on a machine you reach only over ssh (a spare Mac mini on the user's Tailscale, or the LAN):

ssh into it (Tailscale is only the ssh transport, the same as any LAN or internet address).
Run the install script non-interactively: curl -fsSL https://cua.ai/install.sh | sh -s -- -y --select spaces,host --no-onboarding.
Sign in on the mini: cua auth login --remote prints a device code and a URL. Show both to the user and have them approve it (on another signed-in device or at the URL).
cua host setup --share spaces --name "<name>" hosts Spaces only (no desktop sharing), through the cua.ai relay.
Tell the user: the mini needs an active GUI login session (cua-spacesd runs as a LaunchAgent in the Aqua session, so it won't start at the login window; auto-login is recommended for a headless mini), and it needs a one-time grant of Screen Recording and Accessibility to cua-spacesd in System Settings.
From the laptop: create_space(on="host:<name>", count=2), or cua spaces create macos:26 --on "<name>" --count 2.

host:<name> only resolves machines set up with cua host setup (they register with the relay). direct:<addr> attaches one Space that is already running at that address (add_space) and cannot host new ones.

Rules

Run teleport_manifest and tell the user what will move before teleport_app; sensitive items need their explicit acknowledgement.
Only start a hotspot when the Space needs the host's network (VPN, intranet), and stop it afterwards.
Name the Space you used in your answer.

Links to things you ran

Any link to something you ran (preview, dashboard, file): use cua share, never localhost; open it once to check it works before sending.

The share tool (or cua share 3000, cua share space:dev:3000, cua share ./report.html) returns a link that opens on the user's other signed-in devices, phone included. It checks the link loads and reports check.ok; do not send a link whose check failed. Links are private by default; use access: "public" with a ttl only when the user wants anyone to open it. share_list and share_stop manage them.

cua-spaces