Space lifecycle

add_space#

Add an existing machine as a Space by address and token.

Tries a GetCapabilities handshake with the Space's cua-spacesd first. A local:<name> or cloud:<name> id without one is still a Space, with an empty capability set (its declared services, tunnels and public URLs work); a direct URL without one is added as an MCP Space when it answers MCP initialize (service mcp), and refused with spacesd_not_available when it answers neither. The Space is stored in ~/.cua/spaces.json and its token in ~/.cua/spaces-credentials.json (0600). Re-adding the same address updates it.

Parameters#

Result#

JSON: the registered Space (id, name, provider, spacesd_version, features, os, services, added_at) and phase: "ready".

Errors#

invalid_argument, unauthenticated

remove_space#

Forget a registered Space without touching it.

Only the registration and its stored token are removed. The sandbox keeps running, including a Space in your cloud (its cloud resources and relay machine stay); delete_space deletes a Space that create_space made.

Parameters#

Result#

JSON: {"removed": <Space>}, the registration that was removed.

Errors#

invalid_argument, not_found, ambiguous_sandbox

list_spaces#

List the Spaces this connection can see.

Every registered Space (cloud, local, direct and relay) with its id (local:<name>, cloud:<name>, direct:<host:port>, relay:<machine-id>), provider, spacesd version (empty without one) and supported features as of the last handshake. The signed-in account's machines on the relay are listed too: those are the names create_space accepts as on="host:<machine>". A Space a machine provides carries host (that machine's id) and host_name; group them under it when you show them. A Space in your cloud carries cloud (the provider: aws, gcp, modal), cloud_place (account and region, to show with it) and cloud_delete (where delete_space can delete it: here, host:<machine>, or elsewhere).

Parameters#

No parameters.

Result#

JSON: an array of Spaces (id, name, provider, spacesd_version, features, os, services, added_at, for a Space one of your machines provides host and host_name, for a Space that can be turned off and on power (suspend or stop) and power_state, and for a Space in your cloud cloud, cloud_place and cloud_delete), each with phase: "ready".

Errors#

invalid_argument, relay, unauthenticated

create_space#

Create a Space: a new sandbox on this machine, on one of your machines, or in the cloud.

Creates a new sandbox where on says (local: this machine, free; cloud: Cua cloud, metered; aws, gcp or modal: the user's own cloud account, connected with cloud_connect, billed there; default: the user's default location, else local), waits until it is ready (its spacesd when the image runs one, else its declared services), and registers it as local:<name> or cloud:<name>. kind (auto, container, vm) and runtime (auto, or an engine the location offers for the kind) are chosen automatically by default: the canonical Linux image runs as a gVisor container, macOS images as Lume VMs, Windows and disk-only images as VMs (QEMU locally, KubeVirt in the cloud). An impossible combination fails with invalid_placement and lists the valid values. Any image works; without cua-spacesd the capability set is empty. reuse=true returns a reachable registered Space in the same location with the requested services instead of creating one. On the user's own machines: on="host:<machine>" creates the Space on a machine set up with cua host setup --provide-spaces (for example "spin up 2 macOS Spaces on my spare Mac mini" is on="host:spare mac mini", image="macos", count=2). The machine is matched by id, exact name, or the words of its name; when several fit equally the call fails with ambiguous_host listing them (ask the user which, then pass on="host:<id>"). The host runs it with its own runtimes (Lume for macOS VMs on a Mac, Docker for Linux), the Space joins the relay and is returned as relay:<machine> with host set. A Mac runs at most two macOS VMs (Apple's macOS license, enforced by Apple Virtualization); a host at a limit fails with limit_exceeded. Only the machine's owner and the accounts it is shared with as editors can create there, from an enrolled device. on="direct:<addr>" is not accepted here: a direct address is one already-running Space, attached with add_space, not a host this call can create on.

Parameters#

Result#

JSON: the registered Space, phase: "ready" and reused (true when reuse returned an existing Space); with wait: false, {"id", "phase": "starting"} at once; with count above 1, an array of them.

Errors#

invalid_argument, invalid_placement, fleet, fleet_admission_denied, cloud_credit_exhausted, sandbox, timeout, ambiguous_host, limit_exceeded

Notes#

• Cloud needs Fleet credentials (cua auth login); local needs a container engine, QEMU or Lume (cua runtime doctor).

delete_space#

Delete a Space's sandbox and forget it.

Deletes the sandbox of a Space that create_space made (cloud: metering stops; local: the instance is deleted; on one of your machines, on="host:...": that machine deletes it and it leaves the relay) and forgets it. A Space in your cloud (list_spaces: cloud, cloud_place, cloud_delete) is deleted permanently through the records of the device that created it: cloud_delete "here" deletes it from this device; "host:<machine>" asks that host (it must be online, and only its owner may); "elsewhere" is refused with where it was created: delete it there, or remove_space. Another Space added by address (direct:, relay:) is only forgotten: cua did not create it. Any hotspot on the Space is stopped first. To forget a Space without deleting anything, use remove_space.

Parameters#

Result#

Text: what was deleted (Deleted <id> (...)), or Removed <id> (...) for a Space added by address.

Errors#

invalid_argument, not_found, ambiguous_sandbox, fleet, sandbox

stop_space#

Turn a Space off: suspend it (memory kept) or stop it (disk kept).

Turns a Space off the way its provider can: a local container or QEMU VM is suspended (its memory is kept and it resumes where it was), a local Lume VM is stopped (its disk is kept and it boots again), a Space one of your machines provides is stopped by that machine, which frees its memory, and a Space in your own cloud (on="aws", "gcp") is stopped there: compute billing stops, its disk stays (storage is still billed). Anything streaming from the Space and any hotspot on it end first. A Fleet cloud Space, a Modal sandbox, a Space added by address and your own computers on the relay cannot be turned off (wrong_provider); delete_space deletes a Space instead. start_space turns it on again.

Parameters#

Result#

JSON: space, state (suspended or stopped), power (suspend or stop) and message.

Errors#

invalid_argument, not_found, ambiguous_sandbox, wrong_provider, sandbox, relay, permission_denied, cloud

Notes#

• list_spaces says which Spaces turn off (power: suspend or stop; absent when it cannot) and how they were left (power_state).

start_space#

Turn a Space back on: resume or boot it.

Turns a Space stop_space turned off on again: resumes a suspended one, boots a stopped one (a Space one of your machines provides, or one in your cloud, joins the relay again), and leaves a running one as it is. Returns once it answers again (bounded). The same Spaces turn on as turn off.

Parameters#

Result#

JSON: space, state (running), power (suspend or stop) and message.

Errors#

invalid_argument, not_found, ambiguous_sandbox, wrong_provider, sandbox, relay, permission_denied, cloud, timeout