trycua / cua-spaces
Work inside cua Spaces through the cua MCP server. A Space is a remote or local computer the user can watch; you can run commands in it, move files in and out, show its desktop or a single window on the user's screen, start coding agents inside it, teleport a signed-in app session into it, and share the host's network with it. Use when the user mentions Spaces, asks you to do work "in a Space", or wants a task isolated but visible.
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 orcua 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), cloud (metered), 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 metering. |
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 cloud Space 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 --remoteprints 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 --profile spare --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), orcua 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_manifestand tell the user what will move beforeteleport_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.