Daemon: Spaces and service
cua.daemon.v1 SpaceService and DaemonService: Spaces and the computers that provide them, the daemon's identity and the media bridge.
Spaces through the local cua daemon (create, list, power, delete, and the computers that provide Spaces), batch runs on your computers (PoolRequest), the daemon identity (GetInfo) and the loopback media bridge for webviews.
Source: libs/cua/proto/cua/daemon/v1/spaces.proto, libs/cua/proto/cua/daemon/v1/daemon.proto.
SpaceService#
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.
SpaceService.AddSpace#
/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 local:<name>) after a
GetCapabilities handshake.
SpaceService.ListSpaces#
/cua.daemon.v1.SpaceService/ListSpaces, unary: ListSpacesRequest to ListSpacesResponse.
Lists registered Spaces.
SpaceService.RemoveSpace#
/cua.daemon.v1.SpaceService/RemoveSpace, unary: RemoveSpaceRequest to RemoveSpaceResponse.
Forgets a Space. Does not delete the underlying sandbox.
SpaceService.ListVolumes#
/cua.daemon.v1.SpaceService/ListVolumes, unary: ListVolumesRequest to ListVolumesResponse.
Lists the named volumes of Cua Volume (needs Cua Spaces).
SpaceService.CreateVolume#
/cua.daemon.v1.SpaceService/CreateVolume, unary: CreateVolumeRequest to CreateVolumeResponse.
Creates a named volume.
SpaceService.DeleteVolume#
/cua.daemon.v1.SpaceService/DeleteVolume, unary: DeleteVolumeRequest to DeleteVolumeResponse.
Deletes a named volume and its files (history stays).
SpaceService.ResolveSpace#
/cua.daemon.v1.SpaceService/ResolveSpace, unary: ResolveSpaceRequest to ResolveSpaceResponse.
Resolves any accepted spelling (id, legacy id, URL, name) to a Space.
SpaceService.ProvisionLocalSpace#
/cua.daemon.v1.SpaceService/ProvisionLocalSpace, unary: ProvisionLocalSpaceRequest to ProvisionLocalSpaceResponse.
Deprecated.
Deprecated: use CreateSpace with location "local".
SpaceService.ReleaseSpace#
/cua.daemon.v1.SpaceService/ReleaseSpace, unary: ReleaseSpaceRequest to ReleaseSpaceResponse.
Deprecated.
Deprecated: use DeleteSpace.
SpaceService.CreateSpace#
/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.
SpaceService.CreateSpaceStream#
/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.
SpaceService.CancelCreateSpace#
/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 relay registration) and what the create
made is removed (its VM or container and disks, 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.
SpaceService.GetGpuSupport#
/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).
SpaceService.DeleteSpace#
/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. Its
child Spaces are deleted first, unless keep_children.
SpaceService.DeleteSpaces#
/cua.daemon.v1.SpaceService/DeleteSpaces, unary: DeleteSpacesRequest to DeleteSpacesResponse.
Deletes several Spaces (at most 3 at a time), turning running ones off first. One result per Space, in order; one failure never stops the rest.
SpaceService.LeaveSpaces#
/cua.daemon.v1.SpaceService/LeaveSpaces, unary: LeaveSpacesRequest to LeaveSpacesResponse.
Takes this account off Spaces shared with it (through the relay): a direct share ends, a team's Space leaves this account's list. One result per Space, in order.
SpaceService.RenameSpace#
/cua.daemon.v1.SpaceService/RenameSpace, unary: RenameSpaceRequest to RenameSpaceResponse.
Gives a Space a new name; its id stays the same. Only its owner can: a Space shared with you is refused. A Space that is a machine on the relay (shared, or one of your computers provides it) is renamed there too, so your other devices and the people it is shared with see the new name.
SpaceService.ForkSpace#
/cua.daemon.v1.SpaceService/ForkSpace, unary: ForkSpaceRequest to ForkSpaceResponse.
Starts Space name, a fork of local sandbox or checkpoint source
(with its memory when it is running; a QEMU checkpoint's forks share
its RAM copy-on-write), once its cua-spacesd answers. The one fork path:
Space.fork, Spaces.fork and batched forks all end here.
SpaceService.BuildSpace#
/cua.daemon.v1.SpaceService/BuildSpace, server stream: BuildSpaceRequest to BuildSpaceResponse.
Builds a Dockerfile or steps into pinned checkpoints, streaming progress
then one result. Fork it with ForkSpace.
SpaceService.ListBuilds#
/cua.daemon.v1.SpaceService/ListBuilds, unary: ListBuildsRequest to ListBuildsResponse.
The builds.
SpaceService.DeleteBuild#
/cua.daemon.v1.SpaceService/DeleteBuild, unary: DeleteBuildRequest to DeleteBuildResponse.
Deletes a build.
SpaceService.SetSpaceLifetime#
/cua.daemon.v1.SpaceService/SetSpaceLifetime, unary: SetSpaceLifetimeRequest to SetSpaceLifetimeResponse.
Gives a Space a lifetime of duration from now (replacing an earlier
one). When it passes, this daemon deletes the Space (or turns it off,
on_expire "suspend"), whether or not the client is still running.
SpaceService.SetSpaceEgress#
/cua.daemon.v1.SpaceService/SetSpaceEgress, unary: SetSpaceEgressRequest to SetSpaceEgressResponse.
Replaces a Space's egress policy (empty removes it).
SpaceService.GetSpaceNetwork#
/cua.daemon.v1.SpaceService/GetSpaceNetwork, unary: GetSpaceNetworkRequest to GetSpaceNetworkResponse.
A Space's network: its settings, what they open, where they are enforced (or why its network is cut), and what is always blocked.
SpaceService.SetSpaceNetwork#
/cua.daemon.v1.SpaceService/SetSpaceNetwork, unary: SetSpaceNetworkRequest to SetSpaceNetworkResponse.
Replaces a Space's network settings (a child's stay within its
parent's unless widen).
SpaceService.GetSpaceNetworkLog#
/cua.daemon.v1.SpaceService/GetSpaceNetworkLog, unary: GetSpaceNetworkLogRequest to GetSpaceNetworkLogResponse.
What a Space tried to reach and its network refused, most recent first.
SpaceService.SetSpaceClipboard#
/cua.daemon.v1.SpaceService/SetSpaceClipboard, unary: SetSpaceClipboardRequest to SetSpaceClipboardResponse.
Sets when the Space's viewers may move the clipboard between this computer and the Space ("viewing", "ask" or "off").
SpaceService.SetSpaceVolume#
/cua.daemon.v1.SpaceService/SetSpaceVolume, unary: SetSpaceVolumeRequest to SetSpaceVolumeResponse.
Sets what the Space sees of the Cua Volume ("own" or "off"), now.
SpaceService.SetSpaceChildren#
/cua.daemon.v1.SpaceService/SetSpaceChildren, unary: SetSpaceChildrenRequest to SetSpaceChildrenResponse.
Lets a Space make child Spaces of its own, or stops it. Turning it off ends the Space's spawn capability at once; children it already made keep running until they are deleted or their lifetime ends.
SpaceService.GetTreeBudget#
/cua.daemon.v1.SpaceService/GetTreeBudget, unary: GetTreeBudgetRequest to GetTreeBudgetResponse.
A tree's budget (kept on its top-level Space) and what its children
use now. space may be any Space of the tree.
SpaceService.SetTreeBudget#
/cua.daemon.v1.SpaceService/SetTreeBudget, unary: SetTreeBudgetRequest to SetTreeBudgetResponse.
Sets a tree's budget: how many child Spaces, vCPUs and memory its children may hold at once, and what they may cost. Unset limits take the defaults; all unset removes the budget.
SpaceService.ListStreamWindows#
/cua.daemon.v1.SpaceService/ListStreamWindows, unary: ListStreamWindowsRequest to ListStreamWindowsResponse.
The windows other Spaces show in space's Stream section
(stream_space_window with into), as window rows with an origin.
Entries whose window closed or whose origin Space stopped are dropped.
SpaceService.OpenStreamEntry#
/cua.daemon.v1.SpaceService/OpenStreamEntry, unary: OpenStreamEntryRequest to OpenStreamEntryResponse.
Opens one of those windows (its window_id from ListStreamWindows) and
decides the route at open time: straight from the origin Space when the
caller owns it or holds a grant on it, else through this daemon's media
bridge. The ticket is scoped to the origin and the window.
SpaceService.ListOrphans#
/cua.daemon.v1.SpaceService/ListOrphans, unary: ListOrphansRequest to ListOrphansResponse.
Child Spaces whose parent is gone, or not this machine's to judge: the ones it ends after a grace period (only on proof the parent is gone) and the ones it only lists.
SpaceService.ConnectSpace#
/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.
SpaceService.ListSpaceTools#
/cua.daemon.v1.SpaceService/ListSpaceTools, unary: ListSpaceToolsRequest to ListSpaceToolsResponse.
Lists the Spaces MCP tools (tools/list result as JSON).
SpaceService.CallSpaceTool#
/cua.daemon.v1.SpaceService/CallSpaceTool, unary: CallSpaceToolRequest to CallSpaceToolResponse.
Calls one Spaces MCP tool (the same implementation cua daemon mcp and
/mcp serve).
SpaceService.ListHosts#
/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.
SpaceService.GetSpaceThumbnail#
/cua.daemon.v1.SpaceService/GetSpaceThumbnail, unary: GetSpaceThumbnailRequest to GetSpaceThumbnailResponse.
The Space's latest thumbnail (a small JPEG of its primary display)
from the daemon's cache, which every client on this machine shares:
the cached image when it is younger than max_age, else a fresh
capture through cua-spacesd (the cached one again, with its older
captured_at, when the capture fails). Asking keeps the daemon
refreshing running Spaces' thumbnails in the background for a while.
SpaceService.PoolRequest#
/cua.daemon.v1.SpaceService/PoolRequest, unary: PoolRequestRequest to PoolRequestResponse.
Batch runs on your machines (cua sb run): one request to this
machine's own coordinator (target local: work that never leaves
this machine) or to whichever of the account's machines coordinates
them (pool). method, the JSON params and the JSON answer are the
Cua Spaces pool requests (submit, run, runs, jobs, job,
cancel_run, cancel_job, status); a daemon without them answers
UNIMPLEMENTED.
SpaceService.GetSpaceRoute#
/cua.daemon.v1.SpaceService/GetSpaceRoute, unary: GetSpaceRouteRequest to GetSpaceRouteResponse.
Which way the daemon's connection to a Space goes now (see
GetSpaceRouteResponse). Connects first when the daemon has no
connection to it yet.
SpaceService.GetResources#
/cua.daemon.v1.SpaceService/GetResources, unary: GetResourcesRequest to GetResourcesResponse.
What this computer, its extra Spaces and your other computers use now:
processor, memory and disk, as one snapshot. The daemon's single
sampler measures it; a snapshot a few seconds old is returned as it is.
With visible, the call also says a window shows the numbers for the
next 30 seconds, so the sampler runs every 10 seconds (every 5 minutes
otherwise). Numbers only: no names, paths or processes.
SpaceService.WatchResources#
/cua.daemon.v1.SpaceService/WatchResources, server stream: WatchResourcesRequest to WatchResourcesResponse.
The same numbers as a stream: one snapshot first, then an update with
only the entries that changed by more than 1 point or 256 MB, and a
low_disk event whenever the free-disk warning level changes
(including back to ok). A hidden watcher (visible false) is
sampled every 5 minutes and still hears low_disk, for the menu bar.
Cancel the stream to stop; call again with the other visible to
switch.
SpaceService.WatchSpaces#
/cua.daemon.v1.SpaceService/WatchSpaces, server stream: WatchSpacesRequest to WatchSpacesResponse.
Says when the Space list changed, so a client reads it again
(ListSpaces) when something happened instead of on a timer: one
message at once (the generation now), then one per change. This
computer's Spaces are announced within a second; your other computers
on the mesh within about a second of connecting or going away (the mesh
coordinator pushes it); computers not on the mesh within 10 seconds.
Cancel the stream to stop.
DaemonService#
cua.daemon.v1.DaemonService
The daemon itself: identity, the loopback bridge for webviews, shutdown.
| RPC | Request | Response | Kind |
|---|---|---|---|
GetInfo | GetInfoRequest | GetInfoResponse | unary |
OpenMediaBridge | OpenMediaBridgeRequest | OpenMediaBridgeResponse | unary |
Shutdown | ShutdownRequest | ShutdownResponse | unary |
DaemonService.GetInfo#
/cua.daemon.v1.DaemonService/GetInfo, unary: GetInfoRequest to GetInfoResponse.
Returns the daemon identity and its loopback endpoint.
DaemonService.OpenMediaBridge#
/cua.daemon.v1.DaemonService/OpenMediaBridge, unary: OpenMediaBridgeRequest to OpenMediaBridgeResponse.
Opens a media session in a sandbox and returns a loopback WebSocket URL that relays it. The URL carries a short-lived bridge ticket; the browser never sees the spacesd token.
DaemonService.Shutdown#
/cua.daemon.v1.DaemonService/Shutdown, unary: ShutdownRequest to ShutdownResponse.
Stops the daemon after the response is sent.
Types in cua/daemon/v1/spaces.proto#
WatchSpacesRequest#
SpaceService.WatchSpaces takes no arguments.
No fields.
WatchSpacesResponse#
One event of SpaceService.WatchSpaces.
| Field | # | Type | Description |
|---|---|---|---|
generation | 1 | uint64 | Moves on every change of the list (only increases while the daemon runs; a new daemon starts again from 0). |
Space#
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 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", "hetzner", "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. |
stop_reason | 21 | string | Why a local Space stopped without being asked to, in plain words: "out of memory", "killed", "exited" or "exited with code N". Empty otherwise, and once it is started again. Filled in when listed, not stored. |
durable | 27 | string | A durable Space (CreateSpaceRequest.durable): its name. It is created again on another of your machines when its machine goes away, and keeps this name. Empty for other Spaces. 21 is stop_reason (public); durable moved to 27 in the sync. |
labels | 22 | map of string to string | Labels set at create (CreateSpaceRequest.labels), kept by the device that created it. |
expires_at_unix | 23 | int64 | When the Space ends (Unix seconds); 0 without a lifetime. |
on_expire | 24 | string | What happens then: "delete" or "suspend"; empty without a lifetime. |
created_at_unix | 25 | int64 | When it was created (Unix seconds; when added, for a Space added by address); 0 when unknown. |
egress | 26 | EgressPolicy | The egress policy last set on the Space; unset when it has none. |
egress_enforced | 31 | string | Where egress is enforced: "host"; empty without one. |
volumes | 30 | repeated VolumeMount | Named volumes mounted in the Space (CreateSpaceRequest.volumes). |
image_config | 28 | string | JSON image configuration of a Space made from a build. |
sharing | 32 | SpaceSharing | A Space that is a machine on the relay: who owns it and who else has it, as this account sees it. Unset for other Spaces. Filled in when listed, not stored. |
display_name | 33 | string | The name it was given with RenameSpace; empty when it keeps the one it was created with (name). Apps show this one when it is set. A Space that is a machine on the relay is renamed there, so its name changes instead. |
network_settings | 34 | NetworkSettings | Its network settings. Unset for a Space created before they existed (it gets them on its next start). |
network_note | 35 | string | Why its network is not what was asked, in plain words (a runtime that can't protect it yet started it without network). Empty otherwise. |
parent | 36 | string | The Space it was created from (a child), by id; empty for a top-level Space. |
root | 37 | string | The top-level Space of its tree, by id; empty for a top-level Space. |
network_notice_pending | 38 | bool | Its network settings changed by an update (an old Space moved to the new defaults); apps and the CLI say so once. |
depth | 39 | uint32 | How far below its tree's top-level Space it is: 0 for a top-level Space, 1 for its children, ... |
origin | 40 | string | How it was made: "user", "child" or "fork-batch:<id>". |
clipboard | 41 | string | When viewers may move the clipboard between this computer and the Space: "viewing" (only while you're viewing, the default), "ask" or "off". Empty from a daemon that predates the setting, which means "viewing". |
volume | 42 | string | What the Space sees of the Cua Volume: "own" (its own folder, the default) or "off". Empty means "own". |
children | 43 | bool | The Space may make child Spaces of its own (SetSpaceChildren): cua, the SDKs and the agent's tools in it create, list and delete Spaces that belong to it, on a channel only it can reach. |
tree_address | 44 | string | A VM's address in its tree (198.19.0.0/16), where the other members of its tree reach it; empty otherwise. |
SetSpaceClipboardRequest#
Request for SpaceService.SetSpaceClipboard.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
clipboard | 2 | string | "viewing", "ask" or "off". |
SetSpaceClipboardResponse#
Response for SpaceService.SetSpaceClipboard.
No fields.
SetSpaceVolumeRequest#
Request for SpaceService.SetSpaceVolume.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
volume | 2 | string | "own" (its own folder) or "off". |
SetSpaceVolumeResponse#
Response for SpaceService.SetSpaceVolume.
No fields.
SpaceSharing#
Who a Space belongs to and who else has it (Space.sharing).
| Field | # | Type | Description |
|---|---|---|---|
owner_id | 1 | string | The owner's account id. |
owner_email | 2 | string | The owner's email, when known. |
owner_name | 3 | string | The owner's display name, when known. |
role | 4 | string | What this account may do: "owner", "editor" or "viewer". |
team | 5 | string | The team this account reaches it through (its key), when it is a team's and not shared with this account directly. |
team_name | 6 | string | That team's display name (its key when the name is not known). |
editors | 7 | repeated string | Owner view: accounts (emails or ids) that may use it. |
viewers | 8 | repeated string | Owner view: accounts that may only watch. |
teams | 9 | repeated SpaceTeamShare | Owner view: the teams it is a machine of. |
SpaceTeamShare#
A team a Space is shared with.
| Field | # | Type | Description |
|---|---|---|---|
key | 1 | string | The team's key (org id). |
name | 2 | string | Its display name. |
role | 3 | string | "editor" or "viewer". |
AddSpaceRequest#
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". |
AddSpaceResponse#
Response for SpaceService.AddSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The Space. |
ListSpacesRequest#
Request for SpaceService.ListSpaces.
| Field | # | Type | Description |
|---|---|---|---|
known_now | 1 | bool | Answer with what is known now: this machine's Spaces at once, the account's other computers as far as they answered within a moment (the response says how far it got). Without it the daemon waits for the relay and fails when it cannot be read. |
ListSpacesResponse#
Response for SpaceService.ListSpaces.
| Field | # | Type | Description |
|---|---|---|---|
spaces | 1 | repeated Space | Spaces. |
incomplete | 2 | bool | known_now only: some of the account's computers have not answered yet, so the list may grow (an empty one is not "no Spaces"). |
reaching | 3 | uint32 | known_now only: how many computers are still being reached (0 when unknown). |
stale | 4 | bool | known_now only: the other computers' rows are the last known ones, not yet confirmed by the relay. |
notice | 5 | string | known_now only: why the account's computers could not be read, when they could not. |
creating | 6 | repeated CreatingSpace | known_now only: Spaces your other computers are creating now, from what each published in its relay machine record (CUA-2349). |
CreatingSpace#
A Space another of your computers is creating.
| Field | # | Type | Description |
|---|---|---|---|
machine_id | 1 | string | The computer's relay machine id. |
machine_name | 2 | string | The computer's name. |
name | 3 | string | The Space's name. |
os | 4 | string | macos, linux, windows, or empty when unknown. |
phase | 5 | string | The create's phase (preparing, pulling, booting, ...). |
percent | 6 | uint32 | How far along the whole create is, 0 to 100. |
updated_at_ms | 7 | uint64 | When the computer published it, unix ms. |
NamedVolume#
A named volume: the folder volumes/<name>/ of Cua Volume.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Volume name. |
mounted_in | 2 | repeated string | Ids of the Spaces that mount it. |
ListVolumesRequest#
Request for SpaceService.ListVolumes.
No fields.
ListVolumesResponse#
Response for SpaceService.ListVolumes.
| Field | # | Type | Description |
|---|---|---|---|
volumes | 1 | repeated NamedVolume | The volumes, by name. |
CreateVolumeRequest#
Request for SpaceService.CreateVolume.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | 1-63 of a-z, 0-9, ., _, -. Fails when it exists. |
CreateVolumeResponse#
Response for SpaceService.CreateVolume.
| Field | # | Type | Description |
|---|---|---|---|
volume | 1 | NamedVolume | The new volume. |
DeleteVolumeRequest#
Request for SpaceService.DeleteVolume.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Volume name. |
force | 2 | bool | Delete although Spaces mount it. |
DeleteVolumeResponse#
Response for SpaceService.DeleteVolume.
| Field | # | Type | Description |
|---|---|---|---|
files | 1 | uint64 | Files removed. |
RemoveSpaceRequest#
Request for SpaceService.RemoveSpace.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Space id. |
RemoveSpaceResponse#
Response for SpaceService.RemoveSpace.
No fields.
ResolveSpaceRequest#
Request for SpaceService.ResolveSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Id, legacy id, URL or display name. |
ResolveSpaceResponse#
Response for SpaceService.ResolveSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The registered Space. |
ProvisionLocalSpaceRequest#
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. |
ProvisionLocalSpaceResponse#
Response for SpaceService.ProvisionLocalSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The Space. |
ReleaseSpaceRequest#
Request for SpaceService.ReleaseSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
ReleaseSpaceResponse#
Response for SpaceService.ReleaseSpace.
| Field | # | Type | Description |
|---|---|---|---|
message | 1 | string | What happened, for humans. |
ConnectSpaceRequest#
Request for SpaceService.ConnectSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
ConnectSpaceResponse#
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. |
route | 6 | string | Which way the daemon's connection to the Space went when connecting, as GetSpaceRouteResponse.route describes it. |
bulk | 7 | string | Host file of the bulk lane to this Space's guest on the daemon's machine (a Linux VM's shared disk), or empty. A client on that machine moves large files through it; the client proves the file is this guest's before it does (see cua.env.v1.BulkLane). |
transport | 8 | string | What carries the daemon's connection, as GetSpaceRouteResponse.transport says. |
fallback_reason | 9 | string | Why it took the relay's HTTPS path although the mesh was wanted, as GetSpaceRouteResponse.fallback_reason says. |
GetSpaceRouteRequest#
Request for SpaceService.GetSpaceRoute.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
GetSpaceRouteResponse#
Response for SpaceService.GetSpaceRoute.
| Field | # | Type | Description |
|---|---|---|---|
route | 1 | string | One line: local <host:port> (a Space on this machine), direct <address>, relay <relay URL> (the relay's HTTPS path), mesh direct <ip:port> rtt <ms> ms (end to end over the mesh, straight to the machine), mesh relayed (over the mesh, through the relay as ciphertext) or cloud. Empty when the Space runs no cua-spacesd. |
direct | 2 | bool | Whether calls go straight to the machine: local, direct or mesh direct. |
transport | 3 | string | What carries the connection: local, direct, mesh (end to end), relay_https (the relay's HTTPS path: the relay can read the session in transit), cloud, or empty when the Space runs no cua-spacesd. For a badge. |
fallback_reason | 4 | string | Why the connection took the relay's HTTPS path although the mesh was wanted (the relay or the computer has no mesh, or the mesh did not answer). Empty on the mesh, and when the HTTPS path was chosen (CUA_MESH=off). |
SpaceServiceEndpoint#
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". |
ListSpaceToolsRequest#
Request for SpaceService.ListSpaceTools.
No fields.
ListSpaceToolsResponse#
Response for SpaceService.ListSpaceTools.
| Field | # | Type | Description |
|---|---|---|---|
tools_json | 1 | string | MCP tools/list result as JSON. |
CallSpaceToolRequest#
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 {}. |
CallSpaceToolResponse#
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). |
CreateSpaceResponse#
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. |
network | 4 | string | The network applied: none or empty. |
CreateSpaceStreamResponse#
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). |
CancelCreateSpaceRequest#
Request for SpaceService.CancelCreateSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | The create's create_id, the id the Space will have, or its name. |
CancelCreateSpaceResponse#
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. |
SetSpaceLifetimeRequest#
Request for SpaceService.SetSpaceLifetime.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
duration | 2 | google.protobuf.Duration | How long from now. Zero ends it on the daemon's next check. |
on_expire | 3 | string | delete (default) or suspend. Empty keeps the Space's current choice. |
SetSpaceLifetimeResponse#
Response for SpaceService.SetSpaceLifetime.
| Field | # | Type | Description |
|---|---|---|---|
expires_at | 1 | google.protobuf.Timestamp | When the lifetime ends. |
DeleteSpaceRequest#
Request for SpaceService.DeleteSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
keep_children | 2 | bool | Keep its child Spaces: they become top-level Spaces and keep running. Unset: they are deleted first. |
DeleteSpaceResponse#
Response for SpaceService.DeleteSpace.
| Field | # | Type | Description |
|---|---|---|---|
message | 1 | string | What happened, for humans. |
DeleteSpacesRequest#
Request for SpaceService.DeleteSpaces.
| Field | # | Type | Description |
|---|---|---|---|
spaces | 1 | repeated string | Space ids or names. |
SpaceBulkResult#
The outcome for one Space of DeleteSpaces or LeaveSpaces.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | The Space as asked. |
ok | 2 | bool | It went through. |
error | 3 | string | Why not, in plain words; empty when ok. |
message | 4 | string | What happened, for humans. |
DeleteSpacesResponse#
Response for SpaceService.DeleteSpaces.
| Field | # | Type | Description |
|---|---|---|---|
results | 1 | repeated SpaceBulkResult | One per Space asked, in order. |
LeaveSpacesRequest#
Request for SpaceService.LeaveSpaces.
| Field | # | Type | Description |
|---|---|---|---|
spaces | 1 | repeated string | Space ids or names. |
LeaveSpacesResponse#
Response for SpaceService.LeaveSpaces.
| Field | # | Type | Description |
|---|---|---|---|
results | 1 | repeated SpaceBulkResult | One per Space asked, in order. |
RenameSpaceRequest#
Request for SpaceService.RenameSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space id or name. |
name | 2 | string | The new name: lowercase letters, digits and dashes, starting and ending with a letter or digit, at most 63. |
RenameSpaceResponse#
Response for SpaceService.RenameSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The Space as it is listed now. |
ListHostsRequest#
Request for SpaceService.ListHosts.
No fields.
SpacesHostLimit#
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. |
SpacesHost#
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. |
load | 7 | SpacesHostLoad | How loaded it is, when it answered and reports it. |
SpacesHostLoad#
What a host offers and how much of it is free (its job runner's view).
| Field | # | Type | Description |
|---|---|---|---|
millicpus_total | 1 | uint32 | CPU it offers, in thousandths. |
millicpus_free | 2 | uint32 | Of that, free. |
memory_total_mb | 3 | uint64 | Memory it offers (MiB). |
memory_free_mb | 4 | uint64 | Of that, free. |
spaces | 5 | uint32 | Spaces running there (provided Spaces and jobs). |
problem | 6 | string | Why it takes nothing now (empty: it does). |
kinds | 7 | repeated string | Kinds it creates. |
PoolRequestRequest#
Request for SpaceService.PoolRequest.
| Field | # | Type | Description |
|---|---|---|---|
target | 1 | string | local or pool. |
method | 2 | string | The request. |
params_json | 3 | string | Its params, JSON. |
PoolRequestResponse#
Response for SpaceService.PoolRequest.
| Field | # | Type | Description |
|---|---|---|---|
status | 1 | uint32 | HTTP-like status (200 when it worked). |
body_json | 2 | string | The answer, JSON. |
ListHostsResponse#
Response for SpaceService.ListHosts.
| Field | # | Type | Description |
|---|---|---|---|
hosts | 1 | repeated SpacesHost | In order: relay hosts, then direct ones. |
GetSpaceThumbnailRequest#
Request for SpaceService.GetSpaceThumbnail.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
max_age | 2 | google.protobuf.Duration | How old a cached thumbnail may be (unset: any age; zero: always capture). |
GetSpaceThumbnailResponse#
Response for SpaceService.GetSpaceThumbnail.
| Field | # | Type | Description |
|---|---|---|---|
image | 1 | bytes | Encoded image. |
format | 2 | string | "jpeg". |
width | 3 | uint32 | Pixel width. |
height | 4 | uint32 | Pixel height. |
captured_at | 5 | google.protobuf.Timestamp | When it was captured. |
ForkSpaceRequest#
Request for SpaceService.ForkSpace.
| Field | # | Type | Description |
|---|---|---|---|
source | 1 | string | A local sandbox (running or stopped) or a checkpoint. |
name | 2 | string | The new Space's name (empty: <source>-<random>). |
ForkSpaceResponse#
Response for SpaceService.ForkSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The fork, connected. |
CreateSpaceRequest#
Request for SpaceService.CreateSpace.
| Field | # | Type | Description |
|---|---|---|---|
image | 1 | string | Image. Empty uses the canonical Linux image. |
location | 2 | string | Where it runs: "local" 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). |
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 and, injected, for any image on a local container or microVM. False runs the image as it is. |
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. |
durable | 18 | bool | Keep the Space running on your machines (on "auto"): when its machine goes away it is created again on another one, with the same name. It needs the cua daemon of Cua Spaces and an account with machines that provide Spaces. |
forkable | 19 | bool | A fork source (a "bake" Space): a local QEMU VM's guest RAM is a shared file, so its checkpoints take milliseconds and forks of them share its pages. Other kinds ignore it. |
network | 20 | string | Guest network: empty or default gives outbound network; none gives none (QEMU VMs only; published ports still reach the guest). |
labels | 21 | map of string to string | Labels kept with the Space (Space.labels): up to 64 pairs, keys up to 63 bytes, values up to 256, none empty. Not with durable or reuse. |
egress | 22 | EgressPolicy | Egress policy, from the first instruction. Not with durable, reuse or wait = false. |
headless | 23 | bool | No desktop: only cua-spacesd runs (exec, files, processes, MCP), with no display, window manager or audio; a local VM gets no display hardware. The same switch as CreateSandboxRequest.headless. |
volumes | 25 | repeated VolumeMount | Named volumes of Cua Volume to mount in the Space. |
instance_type | 26 | string | Cloud host machine type (a pin). |
region | 27 | string | Cloud host region (a pin). |
network_settings | 28 | NetworkSettings | Network settings. Unset: what network and egress say ("internet" when neither says anything). |
parent | 29 | string | Create it as a child of this Space (id or name): its network is no more open than the parent's. |
widen | 32 | bool | With parent: let it be more open than its parent (recorded on the Space). (30 and 31 are kept for other create options.) |
children | 33 | optional bool | Let the Space make child Spaces of its own (SetSpaceChildren). Unset: off. |
SetSpaceChildrenRequest#
Request for SpaceService.SetSpaceChildren.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Id or name. |
enabled | 2 | bool | On or off. |
SetSpaceChildrenResponse#
Response for SpaceService.SetSpaceChildren.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | Space | The Space as it is now. |
CreateSpaceStreamRequest#
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. |
CreateSpaceProgress#
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. |
GetGpuSupportRequest#
Request for SpaceService.GetGpuSupport.
| Field | # | Type | Description |
|---|---|---|---|
location | 1 | string | "local" (empty) or a registered provider. |
GpuOption#
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 (a provider's GPU types). |
GpuSupport#
The GPU options of one runtime.
| Field | # | Type | Description |
|---|---|---|---|
runtime | 1 | string | "lume", "qemu", "container", "gvisor", a provider's name. |
options | 2 | repeated GpuOption | Its options; empty: none. |
reason | 3 | string | Why it has none. |
GetGpuSupportResponse#
Response for SpaceService.GetGpuSupport.
| Field | # | Type | Description |
|---|---|---|---|
runtimes | 1 | repeated GpuSupport | One entry per runtime of the location. |
TreeBudgetLimits#
What a tree's children may hold and cost. Unset: the default.
| Field | # | Type | Description |
|---|---|---|---|
max_spaces | 1 | optional uint32 | Child Spaces at once (default 16). |
max_vcpus | 2 | optional uint32 | vCPUs at once (default 16). |
max_memory_mb | 3 | optional uint64 | Memory at once, MiB (default 32768). |
usd_per_hour | 4 | optional double | Cost per hour of what runs at once, in linked clouds (default 2.0). |
usd_total | 5 | optional double | Cost in total (default: no total cap). |
GetTreeBudgetRequest#
Request for SpaceService.GetTreeBudget.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Any Space of the tree (id or name). |
SetTreeBudgetRequest#
Request for SpaceService.SetTreeBudget.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Any Space of the tree (id or name); the budget is kept on its root. |
limits | 2 | TreeBudgetLimits | The limits. |
GetTreeBudgetResponse#
Response for SpaceService.GetTreeBudget.
| Field | # | Type | Description |
|---|---|---|---|
budget | 1 | TreeBudget | The budget and use. |
SetTreeBudgetResponse#
Response for SpaceService.SetTreeBudget.
| Field | # | Type | Description |
|---|---|---|---|
budget | 1 | TreeBudget | The budget and use. |
TreeBudget#
A tree's budget and use.
| Field | # | Type | Description |
|---|---|---|---|
root | 1 | string | The tree's top-level Space. |
set | 2 | TreeBudgetLimits | What the owner set (unset fields take the default). |
max_spaces | 3 | uint32 | Child Spaces it may hold at once. |
max_vcpus | 4 | uint32 | vCPUs it may hold at once. |
max_memory_mb | 5 | uint64 | Memory it may hold at once (MiB). |
usd_per_hour | 6 | double | Cost per hour it may run at. |
usd_total | 7 | optional double | Cost in total it may reach, when capped. |
spaces | 8 | uint32 | Child Spaces now (creates in flight included). |
vcpus | 9 | uint32 | vCPUs they hold. |
memory_mb | 10 | uint64 | Memory they hold (MiB). |
usd_per_hour_used | 11 | double | Cost per hour they run at. |
usd_spent | 12 | double | What its children have cost so far. |
ListOrphansRequest#
Request for SpaceService.ListOrphans.
No fields.
Orphan#
A child Space whose parent is gone or out of reach.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | The child. |
parent | 2 | string | Its parent's id. |
state | 3 | string | "ending": its parent is provably gone and it ends after the grace; "listed": its parent is not this machine's to judge, so it stays until deleted or its own lifetime ends. |
why | 4 | string | Why, in words. |
ends_in_secs | 5 | int64 | Seconds until it ends ("ending" only). |
ListOrphansResponse#
Response for SpaceService.ListOrphans.
| Field | # | Type | Description |
|---|---|---|---|
orphans | 1 | repeated Orphan | By child id. |
ListStreamWindowsRequest#
Request for SpaceService.ListStreamWindows.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | The Space whose Stream section shows them (id or name). |
StreamOrigin#
Where a window row's picture comes from.
| Field | # | Type | Description |
|---|---|---|---|
space_id | 1 | string | The origin Space (canonical id). |
name | 2 | string | Its name. |
os | 3 | string | Its OS: macos, linux, windows or empty. |
window_id | 4 | string | The window's handle in the origin. |
StreamWindow#
A window another Space shows, as a row of this Space's window list.
| Field | # | Type | Description |
|---|---|---|---|
window_id | 1 | string | The handle to open it with (OpenStreamEntry). |
title | 2 | string | Title. |
app_name | 3 | string | App name. |
app_id | 4 | string | App id. |
pid | 5 | uint32 | Owning process in the origin. |
origin | 6 | StreamOrigin | The Space it comes from. |
ListStreamWindowsResponse#
Response for SpaceService.ListStreamWindows.
| Field | # | Type | Description |
|---|---|---|---|
windows | 1 | repeated StreamWindow | The rows, in registration order. |
OpenStreamEntryRequest#
Request for SpaceService.OpenStreamEntry.
| Field | # | Type | Description |
|---|---|---|---|
window_id | 1 | string | The row's window_id. |
max_fps | 2 | uint32 | Frames per second cap (0 = 30). |
ticket_ttl_seconds | 3 | uint32 | Ticket lifetime in seconds (0 = default). |
mint | 4 | bool | Mint the ticket here even when the route is direct. By default a direct route returns only the decision (the client opens the origin Space itself, with its own credentials); a proxied route always mints. |
OpenStreamEntryResponse#
Response for SpaceService.OpenStreamEntry.
| Field | # | Type | Description |
|---|---|---|---|
route | 1 | string | direct (from the origin) or proxied (through this daemon's bridge). |
access | 2 | string | What the caller holds on the origin: owner, grant or none. |
minted_by | 3 | string | The Space whose spacesd minted the ticket. |
ticket_json | 4 | string | The ticket (StreamTicket as JSON), scoped to that Space and window. Empty for a direct route that was not asked to mint. |
origin_space | 5 | string | The origin Space (canonical id). |
origin_window_id | 6 | string | The window's handle in the origin. |
Types in cua/daemon/v1/daemon.proto#
DaemonErrorInfo#
Structured error detail of daemon RPCs.
| Field | # | Type | Description |
|---|---|---|---|
reason | 1 | DaemonErrorReason | Reason. |
message | 2 | string | Human-readable message. |
metadata | 3 | map of string to string | Extra context. |
GetInfoRequest#
Request for DaemonService.GetInfo.
No fields.
GetInfoResponse#
Response for DaemonService.GetInfo.
| Field | # | Type | Description |
|---|---|---|---|
version | 1 | string | cua-daemon version. |
pid | 2 | uint32 | Process id. |
socket_path | 3 | string | Unix socket path, when listening on one. |
loopback_url | 4 | string | Loopback base URL (http://127.0.0.1:<port>) serving the same services, the env passthrough and the media bridge. |
loopback_token | 5 | string | Bearer token of the loopback listener. |
features | 6 | repeated string | Compiled-in SDK features, for example "env", "sandboxes", "local". |
started_at | 7 | google.protobuf.Timestamp | When the daemon started. |
executable | 8 | string | The daemon's executable (symlinks resolved), so a client bound to an app bundle can tell its own daemon from another app's. Empty from daemons that predate it. |
build_id | 9 | string | The executable's build as it was when the daemon started (version, size and modification time), so a client can tell a daemon whose executable was rebuilt or updated since. Empty from daemons that predate it. |
warm_spaces | 10 | uint32 | Local Spaces the daemon keeps ready to claim (its warm pool). Zero from daemons that predate warm pools. |
warm_memory_bytes | 11 | uint64 | Memory those Spaces hold, in bytes. |
warm_reason | 12 | string | Why the daemon keeps that many ready, in a few words (for example "no repeat traffic" or "burst: 12.0 creates/min, 3 kept ready"). |
OpenMediaBridgeRequest#
Request for DaemonService.OpenMediaBridge.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox name. |
open_media_json | 2 | string | cua.env.v1.OpenMediaRequest in canonical proto3 JSON. Empty opens the primary display with defaults. |
OpenMediaBridgeResponse#
Response for DaemonService.OpenMediaBridge.
| Field | # | Type | Description |
|---|---|---|---|
ws_url | 1 | string | Loopback WebSocket URL, for example "ws://127.0.0.1:52011/v1/bridge/media?ticket=...". Speaks rcdp wire v2 unchanged. |
ticket | 2 | string | Bridge ticket (also in ws_url). |
expires_at | 3 | google.protobuf.Timestamp | When the bridge ticket stops accepting new attaches. |
open_media_response_json | 4 | string | cua.env.v1.OpenMediaResponse in canonical proto3 JSON, with the upstream ticket removed. |
ShutdownRequest#
Request for DaemonService.Shutdown.
No fields.
ShutdownResponse#
Response for DaemonService.Shutdown.
No fields.
DaemonErrorReason#
Why a daemon call failed. Packed as DaemonErrorInfo in the
google.rpc.Status details of every daemon error.
| Value | # | Description |
|---|---|---|
DAEMON_ERROR_REASON_UNSPECIFIED | 0 | Unknown. |
DAEMON_ERROR_REASON_INVALID_ARGUMENT | 1 | Bad input. |
DAEMON_ERROR_REASON_NOT_FOUND | 2 | No such sandbox, forward or bridge. |
DAEMON_ERROR_REASON_PROVIDER_NOT_CONFIGURED | 3 | The provider is not configured in the daemon (for example no local runtime). |
DAEMON_ERROR_REASON_UNSUPPORTED | 4 | The provider or build cannot do this. |
DAEMON_ERROR_REASON_SPACESD_NOT_AVAILABLE | 5 | No cua-spacesd answered in the sandbox. |
DAEMON_ERROR_REASON_TIMEOUT | 6 | A deadline elapsed. |
DAEMON_ERROR_REASON_RUNTIME | 8 | Local runtime failure. |
DAEMON_ERROR_REASON_ENV | 9 | spacesd call failure. |
DAEMON_ERROR_REASON_HTTP | 10 | HTTP failure talking to a sandbox service. |
DAEMON_ERROR_REASON_INTERNAL | 11 | Daemon bug or I/O failure. |
DAEMON_ERROR_REASON_UNAUTHENTICATED | 12 | Missing or wrong daemon token. |
DAEMON_ERROR_REASON_CAPABILITY_MISSING | 13 | The Space's spacesd reports a feature the call needs as unsupported. |
DAEMON_ERROR_REASON_HOST_CAPABILITY_MISSING | 14 | A host-side prerequisite (app-session providers, an operator display, a local runtime) is not available. |
DAEMON_ERROR_REASON_TELEPORT_REFUSED | 15 | The teleport consent gate refused. |
DAEMON_ERROR_REASON_AMBIGUOUS_SANDBOX | 18 | A bare sandbox name matches sandboxes in more than one location. The qualified candidates are in DaemonErrorInfo.metadata["candidates"] (comma-separated, for example "local:box,cloud:box"). |
DAEMON_ERROR_REASON_INSUFFICIENT_DISK | 19 | A pull, build or VM create would leave less than the configured minimum free disk space; nothing was written (cua cache prune frees space). |
DAEMON_ERROR_REASON_INVALID_PLACEMENT | 20 | A location, kind or runtime that does not exist, or a combination of them (or with the image) that does not. The accepted values are in DaemonErrorInfo.metadata["valid"] (comma-separated, for example "auto,gvisor,runc") and the axis in metadata["axis"] ("on", "kind", "runtime" or "image"). |
DAEMON_ERROR_REASON_CANCELLED | 23 | The create was cancelled (CancelCreateSpace, or its caller went away); what it made is gone. The message says what was removed and what stays (finished image downloads stay cached). |
DAEMON_ERROR_REASON_CLOUD | 24 | Your own cloud account (AWS, Google Cloud, Hetzner, Modal) refused or failed a call Cua made there: a missing permission, a quota, a region without the machine type. The message names the cloud's own error. |
DAEMON_ERROR_REASON_HOST_CAPACITY | 25 | This host has no room for another Space now: its VMs are at their memory or CPU limit (CUA_VM_MAX_RSS_FRACTION, CUA_VM_VCPU_OVERCOMMIT) or the machine is low on memory. Nothing was started; the message says which limit, by how much, and what to do. |
DAEMON_ERROR_REASON_PERMISSION_DENIED | 26 | Signed in, but not allowed: the relay refused the call for this account (for example renaming a Space shared with you; only its owner can). Unlike UNAUTHENTICATED, signing in again does not help. Older daemons answered these as UNAUTHENTICATED. |