Daemon: Spaces
cua.daemon.v1 SpaceService: Spaces and the hosts that provide them, through the local cua daemon.
cua.daemon.v1 SpaceService: Spaces and the hosts that provide them, through the local cua daemon.
Spaces through the local cua daemon: create, list, power, delete, and the machines that provide Spaces.
Source: libs/cua/proto/cua/daemon/v1/spaces.proto.
cua.daemon.v1.SpaceService
Spaces: sandboxes with Spaces features (cua-spacesd, streams, agents,
teleport) that the user works in interactively. The daemon hosts one
cua_spaces::Spaces runtime: the registry in ~/.cua/spaces.json
(tokens in the 0600 spaces-credentials.json), Space creation in every
location, hotspots, and the Spaces MCP server (CallSpaceTool,
cua daemon mcp, /mcp).
Verbs: CreateSpace / DeleteSpace create and delete the sandbox;
AddSpace / RemoveSpace register an existing machine and forget it
without touching it.
/cua.daemon.v1.SpaceService/AddSpace, unary: AddSpaceRequest to AddSpaceResponse.
Adds an existing machine as a Space by address (host:port, a direct
http(s)://host:port, or a sandbox ref such as cloud:<name>) after a
GetCapabilities handshake.
/cua.daemon.v1.SpaceService/ListSpaces, unary: ListSpacesRequest to ListSpacesResponse.
Lists registered Spaces.
/cua.daemon.v1.SpaceService/RemoveSpace, unary: RemoveSpaceRequest to RemoveSpaceResponse.
Forgets a Space. Does not delete the underlying sandbox.
/cua.daemon.v1.SpaceService/ResolveSpace, unary: ResolveSpaceRequest to ResolveSpaceResponse.
Resolves any accepted spelling (id, legacy id, URL, name) to a Space.
/cua.daemon.v1.SpaceService/ClaimFleetSpace, unary: ClaimFleetSpaceRequest to ClaimFleetSpaceResponse.
Deprecated.
Deprecated: use CreateSpace with location "cloud".
/cua.daemon.v1.SpaceService/ProvisionLocalSpace, unary: ProvisionLocalSpaceRequest to ProvisionLocalSpaceResponse.
Deprecated.
Deprecated: use CreateSpace with location "local".
/cua.daemon.v1.SpaceService/ReleaseSpace, unary: ReleaseSpaceRequest to ReleaseSpaceResponse.
Deprecated.
Deprecated: use DeleteSpace.
/cua.daemon.v1.SpaceService/CreateSpace, unary: CreateSpaceRequest to CreateSpaceResponse.
Creates a Space (a sandbox, registered as a Space) where location
says, with the same location / kind / runtime model as
SandboxService.CreateSandbox.
/cua.daemon.v1.SpaceService/CreateSpaceStream, server stream: CreateSpaceStreamRequest to CreateSpaceStreamResponse.
CreateSpace, streaming what the create is doing: progress events
(pulling the image, booting, waiting for cua-spacesd, connecting) in
order, then exactly one result. A failed create ends the stream with
its status after the progress it made.
/cua.daemon.v1.SpaceService/CancelCreateSpace, unary: CancelCreateSpaceRequest to CancelCreateSpaceResponse.
Cancels a create that is still running, found by the caller's
create_id, the id the Space will have (every progress event carries
it in space) or its name: the work in flight stops (an image
download, a boot, a claim, a relay registration) and what the create
made is removed (its VM or container and disks, its cloud claim, its
relay machine, its registry entry). Nothing that existed before is
touched; finished image downloads stay cached so the next create
resumes. Returns once the clean-up is done; the create itself ends with
DAEMON_ERROR_REASON_CANCELLED. Idempotent, and works for a create
another process runs or one a daemon restart cut off.
/cua.daemon.v1.SpaceService/GetGpuSupport, unary: GetGpuSupportRequest to GetGpuSupportResponse.
The GPU options each runtime of a location offers on this host (the
wizard's GPU row; gpu of CreateSpace).
/cua.daemon.v1.SpaceService/DeleteSpace, unary: DeleteSpaceRequest to DeleteSpaceResponse.
Deletes a Space's sandbox and forgets it. A Space added by address
(direct:, relay:) is only forgotten: cua did not create it.
/cua.daemon.v1.SpaceService/ConnectSpace, unary: ConnectSpaceRequest to ConnectSpaceResponse.
Connects to a registered Space and returns a loopback env passthrough
(<loopback>/v1/spaces/<key>/env) that carries the Space's credentials,
so a client runs every cua.env.v1 call and media WebSocket through the
daemon without seeing the Space's token.
/cua.daemon.v1.SpaceService/ListSpaceTools, unary: ListSpaceToolsRequest to ListSpaceToolsResponse.
Lists the Spaces MCP tools (tools/list result as JSON).
/cua.daemon.v1.SpaceService/CallSpaceTool, unary: CallSpaceToolRequest to CallSpaceToolResponse.
Calls one Spaces MCP tool (the same implementation cua daemon mcp and
/mcp serve).
/cua.daemon.v1.SpaceService/ListHosts, unary: ListHostsRequest to ListHostsResponse.
Your machines that provide Spaces (the account's relay hosts and the
hosts added by their Tailscale or LAN address), each asked for its
limits: what CreateSpace takes as on="host:<id>" (the New Space
wizard's Run on menu). One that does not answer is listed offline when
it provided a Space before.
cua/daemon/v1/spaces.proto#A registered Space.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Space id, for example "space://direct/10.0.0.5:3211". |
name | 2 | string | Display name. |
spacesd_version | 3 | string | spacesd version reported at the last handshake. |
features | 4 | repeated string | Supported feature names reported at the last handshake. |
added_at | 5 | google.protobuf.Timestamp | When it was added. |
os | 6 | string | Guest OS family at the last handshake (GetCapabilities): "linux", "macos" or "windows"; empty when not reported. |
services | 7 | repeated string | Services the Space declares (never "env"), for example "mcp". A Space without cua-spacesd has an empty feature list and reaches these through generic MCP (list_tools / call_tool with service). |
os_name | 8 | string | Guest OS product or distribution at the last handshake (GetCapabilities os.name), for example "Ubuntu" or "macOS"; empty when not reported. The Spaces app picks the OS icon from it. |
os_pretty_name | 9 | string | The guest's full OS string at the last handshake (GetCapabilities os.pretty_name), for example "Ubuntu 24.04.3 LTS"; empty when the driver does not report one. |
image | 10 | string | The image the sandbox runs, as requested (local and cloud Spaces), for example "ghcr.io/trycua/linux:24.04"; empty when unknown (a Space added by address). |
image_digest | 11 | string | The digest of the variant that runs ("sha256:..."), when known. |
kind | 12 | string | Container or virtual machine: "container" or "vm" (the guest's runtime at the last handshake, else the local sandbox's record); empty when unknown. |
arch | 13 | string | The guest's CPU architecture: "arm64" or "amd64" (GetCapabilities arch at the last handshake, else the local sandbox's record); empty when unknown. |
host | 14 | string | For a Space a host provides (relay:<machine> created with on="host:<machine>"): the relay machine id of that host; for one a host added by its direct address created (direct:<addr>:<port>): that host's Space id (direct:<addr>:<port>); empty otherwise. Lists group these Spaces under their host. |
host_name | 15 | string | The display name of host, when known. |
power | 16 | string | How the Space turns off and on again (stop_space / start_space): "suspend" (its memory is kept), "stop" (its disk is kept), or empty when it cannot. Filled in when listed, not stored. |
power_state | 17 | string | "running", "suspended" or "stopped" as cua last recorded it; empty when unknown. Filled in when listed, not stored. |
cloud | 18 | string | A Space in the owner's own cloud: the provider ("aws", "gcp", "modal"); empty otherwise. |
cloud_place | 19 | string | Where it runs, for people ("AWS · us-west-2"); empty otherwise. |
cloud_delete | 20 | string | How this device would delete it permanently: "here" (this cua home created it and records it), "host:<machine>" (ask the device that created it, through the relay) or "elsewhere" (only from the device that created it). Empty for other Spaces. |
Request for SpaceService.AddSpace.
| Field | # | Type | Description |
|---|---|---|---|
url | 1 | string | Space URL. |
token | 2 | string | spacesd token (direct Spaces). |
name | 3 | string | Display name. Empty derives one. |
service | 4 | string | When url is not a cua-spacesd but an MCP endpoint: the service name it is registered under. Empty means "mcp". |
Response for SpaceService.AddSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The Space. |
Request for SpaceService.ListSpaces.
No fields.
Response for SpaceService.ListSpaces.
| Field | # | Type | Description |
|---|---|---|---|
spaces | 1 | repeated Space | Spaces. |
Request for SpaceService.RemoveSpace.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Space id. |
Response for SpaceService.RemoveSpace.
No fields.
Request for SpaceService.ResolveSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Id, legacy id, URL or display name. |
Response for SpaceService.ResolveSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The registered Space. |
Request for SpaceService.ClaimFleetSpace.
| Field | # | Type | Description |
|---|---|---|---|
image | 1 | string | Image. Empty uses the default Spaces image for the runtime. |
runtime | 2 | string | Fleet runtime (kubevirt, gvisor). Empty picks from the image. |
name | 3 | string | Display name. |
wait | 4 | optional bool | Wait for the claim to bind (default true when unset). |
reuse | 5 | bool | Reuse a reachable registered Fleet Space for the same image first. |
command | 6 | repeated string | Entrypoint override (pod runtimes). Empty keeps the image's. |
env | 7 | map of string to string | Guest environment. |
services | 8 | map of string to uint32 | Named services (name -> guest port), for example {"mcp": 8765}. |
spacesd | 9 | optional bool | Whether the image runs cua-spacesd. Unset: yes for the Spaces images, no for any other image. |
Response for SpaceService.ClaimFleetSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The Space, once bound. |
pending_json | 2 | string | With wait = false: the pending claim as JSON ({namespace, claim, pool, ...}). |
reused | 3 | bool | A registered Space was reused. |
Request for SpaceService.ProvisionLocalSpace.
| Field | # | Type | Description |
|---|---|---|---|
image | 1 | string | Image. Empty uses the default Spaces image. |
name | 2 | string | Name. Empty generates one. |
cpus | 3 | uint32 | vCPUs (0 = 2). |
memory_mb | 4 | uint64 | Memory in MiB (0 = 4096). |
timeout | 5 | google.protobuf.Duration | Provisioning budget (default 600 s). |
command | 6 | repeated string | Entrypoint override. Empty keeps the image's. |
env | 7 | map of string to string | Guest environment. |
services | 8 | map of string to uint32 | Named services (name -> guest port), for example {"mcp": 8765}. |
spacesd | 9 | optional bool | Whether the image runs cua-spacesd. Unset: yes for the Spaces images, no for any other image. |
Response for SpaceService.ProvisionLocalSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The Space. |
Request for SpaceService.ReleaseSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
Response for SpaceService.ReleaseSpace.
| Field | # | Type | Description |
|---|---|---|---|
message | 1 | string | What happened, for humans. |
Request for SpaceService.ConnectSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
Response for SpaceService.ConnectSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The Space. |
env_url | 2 | string | env passthrough base URL (speaks cua.env.v1, gRPC and gRPC-Web, and relays the /media and /tunnel WebSockets). |
token | 3 | string | Bearer for env_url (the daemon's loopback token). |
capabilities | 4 | bytes | cua.env.v1.GetCapabilitiesResponse of the Space, protobuf-encoded. |
services | 5 | repeated SpaceServiceEndpoint | The Space's declared services through the daemon (same bearer as env_url). env_url is empty when the Space runs no cua-spacesd. |
A declared service of a Space, reachable through the daemon.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Service name, for example "mcp". |
url | 2 | string | Base URL: requests to <url><path> reach <path> on the service. |
mcp_path | 3 | string | Its MCP endpoint path, for example "/mcp". |
Request for SpaceService.ListSpaceTools.
No fields.
Response for SpaceService.ListSpaceTools.
| Field | # | Type | Description |
|---|---|---|---|
tools_json | 1 | string | MCP tools/list result as JSON. |
Request for SpaceService.CallSpaceTool.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Tool name from the Spaces contract. |
arguments_json | 2 | string | Arguments as a JSON object. Empty means {}. |
Response for SpaceService.CallSpaceTool.
| Field | # | Type | Description |
|---|---|---|---|
content_json | 1 | string | MCP content parts as a JSON array. |
structured_json | 2 | string | MCP structured content as JSON, when present. |
is_error | 3 | bool | The call failed as a tool error. |
meta_json | 4 | string | The result's _meta as JSON, when present (forwarded verbatim from an in-Space MCP service). |
Request for SpaceService.CreateSpace.
| Field | # | Type | Description |
|---|---|---|---|
image | 1 | string | Image. Empty uses the canonical Linux image. |
location | 2 | string | Where it runs: "local", "cloud" or a registered provider. Empty uses the default (default.on in the config, CUA_DEFAULT_ON, else "local"); clients resolve the default on their side. |
kind | 3 | string | What kind of machine: "auto" (empty), "container" or "vm". |
runtime | 4 | string | Which engine: "auto" (empty), or one the location offers for the kind ("gvisor", "runc", "qemu", "lume" locally; "gvisor", "kubevirt" in the cloud). |
name | 5 | string | Name. Empty generates space-<hex>. |
cpus | 6 | uint32 | vCPUs (0 = the default, 2). |
memory_mb | 7 | uint64 | Memory in MiB (0 = the default, 4096). |
timeout | 8 | google.protobuf.Duration | Readiness budget (default 600 s). |
wait | 9 | optional bool | Wait until the Space is ready (default true when unset). With false the response carries only its id and phase "starting". |
reuse | 10 | bool | Return a reachable registered Space with the same image, location, kind and runtime instead of creating one (get-or-create). |
command | 11 | repeated string | Entrypoint override. Empty keeps the image's. |
env | 12 | map of string to string | Guest environment. |
services | 13 | map of string to uint32 | Named services (name -> guest port), for example {"mcp": 8765}. |
spacesd | 14 | optional bool | Whether the image runs cua-spacesd. Unset: yes for the canonical images, no for any other image. |
disk_gb | 15 | uint32 | Grow the VM's disk to this many GiB (local VMs only; 0 keeps the image's size). Lume grows the macOS APFS container before the first boot; Linux images grow their root partition at boot (cloud-init growpart). |
gpu | 16 | string | A GPU option of the runtime the Space runs on (GetGpuSupport): "paravirtual" (a macOS VM on Lume: GPU acceleration, experimental), "virgl", "nvidia", a provider's GPU type; "auto" picks the runtime's own. Empty: no GPU. Kept with the Space. |
create_id | 17 | string | The caller's own key for this create (an app's pending row id), for CancelCreateSpace before the Space's id is known. |
Response for SpaceService.CreateSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The Space (with wait = false: only its id). |
phase | 2 | string | "ready", or "starting" with wait = false. |
reused | 3 | bool | reuse returned an existing Space. |
Request for SpaceService.CreateSpaceStream.
| Field | # | Type | Description |
|---|---|---|---|
create | 1 | CreateSpaceRequest | The create, as for CreateSpace. wait is ignored: the stream always runs until the Space is ready or the create fails. |
What a create is doing.
| Field | # | Type | Description |
|---|---|---|---|
phase | 1 | string | "preparing", "pulling", "creating", "booting", "waiting_for_services", "connecting" or "ready", in that order. |
fraction | 2 | optional double | How far through the phase, 0.0 to 1.0, when its size is known (an image pull). |
detail | 3 | string | One short line, for example the image being pulled. |
bytes_done | 4 | optional uint64 | Bytes downloaded so far, when the step counts them (an image pull). |
bytes_total | 5 | optional uint64 | Bytes the download has in all. |
bytes_per_second | 6 | optional double | Smoothed download rate, bytes per second. |
space | 7 | string | The id the Space will have (local:<name>), for CancelCreateSpace. |
One message of SpaceService.CreateSpaceStream.
| Field | # | Type | Description |
|---|---|---|---|
progress | 1 | CreateSpaceProgress (oneof event) | What the create is doing now. |
result | 2 | CreateSpaceResponse (oneof event) | The created Space (the last message). |
Request for SpaceService.CancelCreateSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | The create's create_id, the id the Space will have, or its name. |
Response for SpaceService.CancelCreateSpace.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | The Space id the create had, when known. |
state | 2 | string | "cancelled", "not_creating" (nothing by that key is running) or "already_created" (it finished; delete it instead). |
message | 3 | string | What was removed and what stays, for people. |
Request for SpaceService.GetGpuSupport.
| Field | # | Type | Description |
|---|---|---|---|
location | 1 | string | "local" (empty) or "cloud". |
One GPU option of a runtime.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | What to pass as gpu. |
label | 2 | string | How a person names it ("GPU acceleration"). |
experimental | 3 | bool | Experimental. |
supported | 4 | bool | Works on this host (and account) now. |
reason | 5 | string | Why not, one short line. |
learn_more | 6 | string | A page that explains it. |
usd_per_hour | 7 | optional double | Estimated cost per hour while it runs (cloud GPU types). |
The GPU options of one runtime.
| Field | # | Type | Description |
|---|---|---|---|
runtime | 1 | string | "lume", "qemu", "container", "gvisor", "fleet", a provider's name. |
options | 2 | repeated GpuOption | Its options; empty: none. |
reason | 3 | string | Why it has none. |
Response for SpaceService.GetGpuSupport.
| Field | # | Type | Description |
|---|---|---|---|
runtimes | 1 | repeated GpuSupport | One entry per runtime of the location. |
Request for SpaceService.DeleteSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
Response for SpaceService.DeleteSpace.
| Field | # | Type | Description |
|---|---|---|---|
message | 1 | string | What happened, for humans. |
Request for SpaceService.ListHosts.
No fields.
One limit of a host and how much of it is used.
| Field | # | Type | Description |
|---|---|---|---|
resource | 1 | string | spaces (every Space it provides) or macos_vms (macOS VMs on that Mac). |
used | 2 | uint32 | In use now. |
limit | 3 | uint32 | The limit (0: none). |
reason | 4 | string | Why the limit exists, for people. |
One of your machines that provides Spaces.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | What on="host:<id>" takes: the relay machine id, or the name a direct host was added as. |
name | 2 | string | Its name. |
via | 3 | string | relay or direct. |
online | 4 | bool | It answered. |
os | 5 | string | Its operating system (macos, linux, windows), when it answered. |
limits | 6 | repeated SpacesHostLimit | Its limits, when it answered. |
Response for SpaceService.ListHosts.
| Field | # | Type | Description |
|---|---|---|---|
hosts | 1 | repeated SpacesHost | In order: relay hosts, then direct ones. |