Add a Space

The Quickstart adds an existing machine by URL. The same spaces object also creates Spaces. Ids are the sandbox refs cua sb ls prints (local:<name>, cloud:<name>, direct:<host:port>, relay:<machine-id>); a bare name works when it matches one Space.

Create a Space#

created = await spaces.create(cua.SpaceCreateOptions(on="local", cpus=2, memory_mb=4096))
space = await spaces.space(created.space.id)

Runs ghcr.io/trycua/linux:24.04 (or image) with a fresh env token. on, kind and runtime work as for sandboxes; without on, the Space runs where cua config get default.on says (local unless you changed it; the Spaces app sets it in Settings, Default location). cua runtime doctor shows what this host has.

In the cloud#

Needs cua auth login, or CUA_CLIENT_ID and CUA_CLIENT_SECRET. Cloud Spaces are metered until deleted.

created = await spaces.create(cua.SpaceCreateOptions(on="cloud"))
space = await spaces.space(created.space.id)
# ...
await spaces.delete(created.space.id)

reuse=True returns a registered, reachable Space in the same location first (created.reused says so). With wait=False, created.pending_id names a Space that is not ready yet.

A Space from any image#

create takes image, command, env and services. An image that serves MCP becomes a Space of that service, with no cua-spacesd:

created = await spaces.create(cua.SpaceCreateOptions(
    image="<your-mcp-server-image>",
    command=["python", "-m", "acme_mcp", "--port", "8765"],
    services={"mcp": 8765},
))
space = await spaces.space(created.space.id)
tools = await space.list_tools("mcp")
result = await space.call_tool("add", '{"a": 2, "b": 3}', "mcp", None)

Spacesd features on an image without it fail with CapabilityMissing. The canonical images and machines set up with cua host setup run cua-spacesd.

Progress#

The app shows a progress bar, and under it while the image downloads 4.2 of 22.1 GB · 85 MB/s · about 4 min. cua spaces create prints the same on one updating line. In code, pass a listener:

class Show(cua.SpaceCreateListener):
    def on_progress(self, p):
        print(p.space, p.phase, p.bytes_done, p.bytes_total, p.bytes_per_second)
 
created = await spaces.create_with_progress(cua.SpaceCreateOptions(image="macos"), Show())

macOS images report bytes with a Lume whose pull API reports them (downloadedBytes); an older Lume reports only a percent.

Cancel a create#

• App: Cancel in the toolbar of a Space that is being created.
• CLI: Ctrl-C during cua spaces create or cua sb create (exit code 130), or from any terminal:

cua spaces cancel local:space-1a2b3c

• SDK: cancel_create takes the create's create_id, the id the Space will have (space in every progress report) or its name, and returns once the cleanup is done. The create fails with CuaError.Cancelled.

outcome = await spaces.cancel_create("local:space-1a2b3c")
print(outcome.state, outcome.message)  # cancelled, not_creating or already_created

Sandboxes: await sandboxes.cancel_create(name) returns what was removed, or None. A cancel works across processes and after a daemon restart.

A Lume without POST /lume/pull/cancel cannot stop a pull: the create still cancels, and the image finishes downloading in the background as a reusable base.

GPU acceleration#

cua spaces gpus
cua spaces create macos --gpu paravirtual

--gpu alone (or gpu="auto") picks the runtime's own option; the SDK takes SpaceCreateOptions(gpu=...) and SandboxCreateOptions(gpu=...), and spaces.gpu_support(on) lists what exists here.

In the app it is the GPU checkbox on the Resources step of New Space. For paravirtual, cua applies the unrestricted paravirtualized GPU feature level before each start of the VM and removes it when the last GPU VM is deleted, if cua set it. Metal apps in the guest may still need the per-workload shim: Unlock Metal for a workload.

List, delete, remove#

cua spaces ls

Lists registered Spaces and, when you are signed in, your machines on the relay (relay:<machine-id>, no add needed). Register or forget one from a shell:

cua spaces add 10.0.0.5:3211 --token "$CUA_ENV_TOKEN" --name studio
cua spaces rm studio

A Tailscale address works here too (its IP or MagicDNS name as the host:port): cua spaces add reaches it like any other address and the Space registers as direct:<addr>. That only attaches one already-running Space; hosting Spaces for on="host:<name>" still goes through the cua.ai relay, set up with cua host setup.

spaces.delete(id) deletes a Space's sandbox and forgets it (a Space added by address is only forgotten); spaces.remove(id) forgets a Space without touching it.

In TypeScript the methods are create, delete_, add and remove, with options from @trycua/cua/spaces. Agents use the MCP tools create_space, delete_space, add_space and remove_space (Use from an agent).