Cua daemon
cua.daemon.v1: the local cua daemon API for sandboxes, local runtimes, Spaces, its identity and the media bridge.
The local cua daemon API (a Unix socket on the host, not cua-spacesd): sandbox lifecycle across locations, the local runtimes and images it orchestrates, Spaces and the machines that provide them, its identity (GetInfo) and the loopback media bridge for webviews.
Source: libs/cua/proto/cua/daemon/v1/sandboxes.proto, libs/cua/proto/cua/daemon/v1/runtime.proto, libs/cua/proto/cua/daemon/v1/spaces.proto, libs/cua/proto/cua/daemon/v1/daemon.proto.
SandboxService#
cua.daemon.v1.SandboxService
Sandbox lifecycle across providers (Fleet, local VMM, direct).
Sandboxes are daemon-agnostic: nothing here assumes cua-spacesd is installed in the guest.
SandboxService.ListSandboxes#
/cua.daemon.v1.SandboxService/ListSandboxes, unary: ListSandboxesRequest to ListSandboxesResponse.
Lists sandboxes known to the daemon.
SandboxService.CreateSandbox#
/cua.daemon.v1.SandboxService/CreateSandbox, unary: CreateSandboxRequest to CreateSandboxResponse.
Creates a sandbox where location says (local by default), or
connects to an existing machine (direct:<addr>).
SandboxService.CreateSandboxStream#
/cua.daemon.v1.SandboxService/CreateSandboxStream, server stream: CreateSandboxStreamRequest to CreateSandboxStreamResponse.
CreateSandbox, streaming what the create is doing: progress events
(pulling the image with its bytes, creating, booting, waiting for the
probes) in order, then exactly one result. A failed create ends the
stream with its status. Closing the stream cancels the create, as for
a CreateSandbox whose caller goes away.
SandboxService.CancelCreateSandbox#
/cua.daemon.v1.SandboxService/CancelCreateSandbox, unary: CancelCreateSandboxRequest to CancelCreateSandboxResponse.
Cancels a CreateSandbox of a named sandbox still running: the work
in flight stops (an image download, a boot, a claim) and what the
create made is deleted; a sandbox of that name that existed before is
never touched. Finished image downloads stay cached. Returns once the
clean-up is done. Idempotent: cancelled is false when no create of
that name was running. A CreateSandbox whose caller goes away (a
closed connection) is cleaned up the same way.
SandboxService.GetSandbox#
/cua.daemon.v1.SandboxService/GetSandbox, unary: GetSandboxRequest to GetSandboxResponse.
Returns one sandbox.
SandboxService.DeleteSandbox#
/cua.daemon.v1.SandboxService/DeleteSandbox, unary: DeleteSandboxRequest to DeleteSandboxResponse.
Deletes (or releases, or detaches from) a sandbox.
SandboxService.ConnectSandbox#
/cua.daemon.v1.SandboxService/ConnectSandbox, unary: ConnectSandboxRequest to ConnectSandboxResponse.
Reattaches to a sandbox by ref (a state file, a live cloud claim or an address) and keeps the handle in the daemon.
SandboxService.SuspendSandbox#
/cua.daemon.v1.SandboxService/SuspendSandbox, unary: SuspendSandboxRequest to SuspendSandboxResponse.
Suspends a sandbox (local: pause; Fleet: scale to zero).
SandboxService.ResumeSandbox#
/cua.daemon.v1.SandboxService/ResumeSandbox, unary: ResumeSandboxRequest to ResumeSandboxResponse.
Resumes a suspended sandbox.
SandboxService.RestartSandbox#
/cua.daemon.v1.SandboxService/RestartSandbox, unary: RestartSandboxRequest to RestartSandboxResponse.
Restarts a sandbox.
SandboxService.KeepAlive#
/cua.daemon.v1.SandboxService/KeepAlive, unary: KeepAliveRequest to KeepAliveResponse.
Extends a Fleet claim lease.
SandboxService.WaitReady#
/cua.daemon.v1.SandboxService/WaitReady, unary: WaitReadyRequest to WaitReadyResponse.
Waits until user-declared readiness probes pass.
SandboxService.ServiceRequest#
/cua.daemon.v1.SandboxService/ServiceRequest, unary: ServiceRequestRequest to ServiceRequestResponse.
Sends one HTTP request to a named service of a sandbox. Credentials (for example the Fleet bearer) stay in the daemon.
SandboxService.ForwardPort#
/cua.daemon.v1.SandboxService/ForwardPort, unary: ForwardPortRequest to ForwardPortResponse.
Forwards a daemon loopback port to a guest port.
SandboxService.CloseForward#
/cua.daemon.v1.SandboxService/CloseForward, unary: CloseForwardRequest to CloseForwardResponse.
Stops a forward started by ForwardPort.
SandboxService.GetEnvEndpoint#
/cua.daemon.v1.SandboxService/GetEnvEndpoint, unary: GetEnvEndpointRequest to GetEnvEndpointResponse.
Probes cua-spacesd in the sandbox and returns the daemon's loopback
passthrough endpoint for it. cua.env.v1 calls sent there are proxied
with the sandbox credentials attached by the daemon.
SandboxService.GetServiceEndpoint#
/cua.daemon.v1.SandboxService/GetServiceEndpoint, unary: GetServiceEndpointRequest to GetServiceEndpointResponse.
The daemon's loopback passthrough for a named service of a sandbox:
any HTTP request (any method, streamed both ways, headers passed
through) sent to url + path reaches that path on the service with the
sandbox's route and credentials attached by the daemon. For MCP
clients, SSE and anything else served over HTTP.
SandboxService.GetServiceUrl#
/cua.daemon.v1.SandboxService/GetServiceUrl, unary: GetServiceUrlRequest to GetServiceUrlResponse.
Returns a URL for a named service usable from this machine without credentials: the published loopback port locally, a signed service URL in the cloud.
SandboxService.CreatePublicUrl#
/cua.daemon.v1.SandboxService/CreatePublicUrl, unary: CreatePublicUrlRequest to CreatePublicUrlResponse.
Creates a shareable URL for a named service that expires: a signed service URL in the cloud; locally a loopback proxy URL with its own token, served by the daemon.
SandboxService.RevokePublicUrl#
/cua.daemon.v1.SandboxService/RevokePublicUrl, unary: RevokePublicUrlRequest to RevokePublicUrlResponse.
Revokes a URL created by CreatePublicUrl.
RuntimeService#
cua.daemon.v1.RuntimeService
Local runtime provisioning (cua runtime doctor|setup).
RuntimeService.Doctor#
/cua.daemon.v1.RuntimeService/Doctor, unary: DoctorRequest to DoctorResponse.
Inspects local runtimes (Lume, QEMU, container engine, runsc) without changing anything.
RuntimeService.Setup#
/cua.daemon.v1.RuntimeService/Setup, unary: SetupRequest to SetupResponse.
Installs or starts missing local runtime components. Every step is explicit and logged in the response.
RuntimeService.PullImage#
/cua.daemon.v1.RuntimeService/PullImage, unary: PullImageRequest to PullImageResponse.
Pulls an image into the local cache or container engine.
RuntimeService.BuildImage#
/cua.daemon.v1.RuntimeService/BuildImage, unary: BuildImageRequest to BuildImageResponse.
Builds an image from an images.cua.ai/v1alpha1 Image resource.
RuntimeService.PushImage#
/cua.daemon.v1.RuntimeService/PushImage, unary: PushImageRequest to PushImageResponse.
Copies an image (host architecture) to another registry reference.
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 cloud:<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.ResolveSpace#
/cua.daemon.v1.SpaceService/ResolveSpace, unary: ResolveSpaceRequest to ResolveSpaceResponse.
Resolves any accepted spelling (id, legacy id, URL, name) to a Space.
SpaceService.ClaimFleetSpace#
/cua.daemon.v1.SpaceService/ClaimFleetSpace, unary: ClaimFleetSpaceRequest to ClaimFleetSpaceResponse.
Deprecated.
Deprecated: use CreateSpace with location "cloud".
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 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.
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.
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.
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 Fleet bearer or 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/sandboxes.proto#
Sandbox#
A sandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Name (unique within its location; see id). |
provider | 2 | SandboxProvider | Provider. |
state | 3 | SandboxState | State. |
image | 4 | string | Image reference, for example "ghcr.io/trycua/linux:24.04". |
endpoints | 5 | map of string to string | Reachable endpoints by service name, for example {"env": "http://127.0.0.1:52011"}. |
labels | 6 | map of string to string | User labels. |
created_at | 7 | google.protobuf.Timestamp | Creation time. |
error | 8 | string | Failure reason when state is SANDBOX_STATE_FAILED. |
runtime_type | 9 | string | Runtime identifier as persisted in the state file (fleet, direct, docker, qemu, lume, ...). |
ephemeral | 10 | bool | True when the sandbox has no state file and is torn down on delete. |
services | 11 | map of string to uint32 | Declared services: logical name to guest port (0 when only the name is known, for example on Fleet). |
location | 12 | string | Where the sandbox runs: "local", "cloud", "direct" (a machine reached by address) or "relay". |
expires_at | 13 | google.protobuf.Timestamp | When the sandbox expires unless kept alive. Unset when unknown or never (cloud sandboxes held by the daemon are renewed while held). |
provider_details | 14 | map of string to string | Provider internals for debugging (cloud: pool, namespace, claim; local: backend, container_id). Not part of the portable API. |
id | 15 | string | Qualified ref: "local:<name>", "cloud:<name>" or "direct:<host:port>". Every request's name accepts it (and a bare name when that name is unique across locations). |
kind | 16 | string | What kind of machine it runs as: "container" or "vm"; empty when not known (an existing machine, or a cloud sandbox this daemon did not create). |
runtime | 17 | string | The engine that runs it: "gvisor", "runc", "qemu", "lume" or "kubevirt"; empty when not known. |
stop_reason | 18 | string | Why a local sandbox 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. |
ReadinessProbe#
A user-declared readiness probe. With no probes a sandbox is ready as soon as its provider reports it running.
| Field | # | Type | Description |
|---|---|---|---|
port | 1 | uint32 | Guest port to probe. |
http_path | 2 | string | HTTP path. Empty means a TCP connect probe. |
http_status | 3 | uint32 | Exact HTTP status to wait for. 0 accepts any 2xx. |
Sidecar#
An extra container sharing a sandbox's network namespace: the sandbox
reaches its ports on localhost, and services may name them. Local
containers and cloud container (gVisor) sandboxes only.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Name, unique within the sandbox (a DNS label other than main). Empty derives it from the image. |
image | 2 | string | Image reference. |
command | 3 | repeated string | argv replacing the image's entrypoint. Empty lets the image decide. |
env | 4 | map of string to string | Environment (plain values, not secrets). |
ports | 5 | repeated uint32 | Ports it listens on. |
RegistrySecret#
Credentials for a private registry. Write-only: never logged, stored in state files or returned.
| Field | # | Type | Description |
|---|---|---|---|
registry | 1 | string | Registry host (ghcr.io, localhost:5000). Empty means the image's. |
username | 2 | string | User name (AWS for ECR tokens). |
password | 3 | string | Password or token. |
ImageLayer#
One image build step, as in images.cua.ai/v1alpha1 recipes.
| Field | # | Type | Description |
|---|---|---|---|
type | 1 | string | apt_install, pip_install, uv_install, run or app_install. |
packages | 2 | repeated string | Packages (the install types). |
command | 3 | string | Shell command (run). |
app_id | 4 | string | App id (app_install). |
BuildFile#
A local file copied into a built image.
| Field | # | Type | Description |
|---|---|---|---|
source | 1 | string | Path on the daemon's machine. |
destination | 2 | string | Absolute path in the image. |
ImageBuild#
Image layers built on top of the sandbox's image. Cloud: a remote build through the images API, cached by content.
| Field | # | Type | Description |
|---|---|---|---|
layers | 1 | repeated ImageLayer | Steps, in order. |
env | 2 | map of string to string | Image environment. |
ports | 3 | repeated uint32 | Ports the image exposes. |
files | 4 | repeated BuildFile | Files copied into the image. |
timeout | 5 | google.protobuf.Duration | Build budget. Unset uses one hour. |
ListSandboxesRequest#
Request for SandboxService.ListSandboxes.
| Field | # | Type | Description |
|---|---|---|---|
provider | 1 | SandboxProvider | Deprecated. Deprecated: use location. Only sandboxes of this provider. Unspecified lists all. |
include_cloud | 2 | optional bool | Also list the account's live Fleet claims (not only the ones this machine knows) when the provider filter allows cloud sandboxes. Unset means true. Without Fleet credentials nothing is added. |
location | 3 | string | Only sandboxes in this location: "local", "cloud" or "direct". Empty lists every location. Wins over provider. |
ListSandboxesResponse#
Response for SandboxService.ListSandboxes.
| Field | # | Type | Description |
|---|---|---|---|
sandboxes | 1 | repeated Sandbox | Sandboxes. |
warnings | 2 | repeated string | What the listing left out, for example "cloud sandboxes not listed: <reason>". The listing still succeeds. |
CreateSandboxRequest#
Request for SandboxService.CreateSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Desired name. Empty lets the daemon generate one. |
provider | 2 | SandboxProvider | Deprecated. Deprecated: use location. Used only when location is empty. |
image | 3 | string | Image reference (local and cloud sandboxes). |
pool | 4 | string | Cloud: claim from this existing pool (Fleets advanced API). |
url | 5 | string | Deprecated: use location "direct:<addr>". The address of an existing machine. |
token | 6 | string | Access token for the direct provider's spacesd, if any. |
labels | 7 | map of string to string | User labels. |
os | 8 | string | Guest OS: linux (default), macos or windows. |
cpus | 9 | uint32 | vCPUs. 0 uses the provider default. |
memory_mb | 10 | uint64 | Memory in MiB. 0 uses the provider default. |
ports | 11 | repeated uint32 | Extra guest ports to publish (local) or expose as port-<n> services (Fleet). |
services | 12 | map of string to uint32 | Named services: logical name to guest port. env defaults to 3211. |
wait_for | 13 | repeated ReadinessProbe | Readiness probes. |
ready_timeout | 14 | google.protobuf.Duration | Total readiness budget. Unset uses the provider default. |
env | 15 | map of string to string | Guest environment. Local: container environment or cloud-init; cloud: the template environment (hashed into the managed pool key). |
fleet_runtime | 16 | string | Deprecated. Deprecated: use runtime. Cloud runtime (kubevirt, gvisor), used when runtime is empty. |
fleet_replicas | 17 | uint32 | Deprecated: initial replicas of a new managed Fleet pool (> 0 means warm). 0 leaves it to fleet_warm. |
fleet_ttl_seconds | 18 | uint32 | Fleet claim TTL in seconds after creation. 0 uses the default (managed pools: CUA_FLEET_CLAIM_TTL, renewed by the daemon while the sandbox is held). |
fleet_warm | 19 | optional bool | Managed Fleet pools (no pool): start a new pool with one warm replica. Unset uses CUA_FLEET_WARM. Existing pools are never resized. |
fleet_max_pool_size | 20 | uint32 | Managed Fleet pools: autoscaling ceiling. 0 uses the default (CUA_FLEET_MAX_POOL_SIZE, 10). |
command | 21 | repeated string | The sandbox's command (argv), replacing the image's entrypoint. Empty lets the image decide. Local containers: ENTRYPOINT; local Linux VMs: run by cloud-init; cloud pod runtimes: the template command. Cloud VMs (KubeVirt) and macOS guests reject it. |
sidecars | 22 | repeated Sidecar | Sidecar containers sharing the sandbox's network namespace. Local containers and cloud container sandboxes; VMs reject them. |
registry_secret | 23 | RegistrySecret | Credentials for a private image (and sidecar images on its registry): local pulls use them; the cloud stores them as the sandbox's registry pull Secret. Never logged or returned. |
build | 24 | ImageBuild | Image layers built on top of image before the sandbox starts. |
container_runtime | 25 | string | Deprecated. Deprecated: use runtime. Local container sandboxes: runc or gvisor, used when runtime is empty. Cloud sandboxes ignore it. |
fleet_apply | 26 | bool | With pool: update that pool's template to the sandbox fields given here (image, command, env, services, sidecars, cpus, memory) instead of failing with POOL_SPEC_MISMATCH when they differ. Managed pools refuse. |
owner_pid | 27 | uint32 | The client process that owns an ephemeral sandbox (no name). The daemon records it in the sandbox's lease, so a local ephemeral sandbox is reaped after its client dies even while the daemon runs. 0: the daemon itself owns it. |
network | 28 | string | Guest network: empty or default gives outbound network (like a Docker container); none cuts egress while published ports still work. Only local QEMU VMs honour none; containers, Lume and cloud sandboxes reject it. |
location | 29 | string | Where it runs: "local", "cloud", "direct:<addr>" (an existing machine running cua-spacesd), or a registered provider (SANDBOX_PROVIDER_CONTRIB, e.g. "e2b"). Empty uses the default (default.on in the config, CUA_DEFAULT_ON, else "local"); clients resolve the default on their side and send it explicitly. |
kind | 30 | string | What kind of machine: "auto" (empty), "container" or "vm". Auto decides from the image: macOS and Windows images are VMs, an image with a container rootfs is a container, a disk-only image is a VM. |
runtime | 31 | string | Which engine: "auto" (empty) or one the location offers for the kind. Local: "gvisor", "runc" (containers), "qemu", "lume" (VMs). Cloud: "gvisor" (containers), "kubevirt" (VMs). A registered provider offers its own engines. Anything else is DAEMON_ERROR_REASON_INVALID_PLACEMENT, listing the valid values. |
keep_on_failure | 32 | bool | Keep a named sandbox whose readiness check fails (its cloud claim, VM or container, and its record) for debugging. False: a failed create deletes what it made and releases the claim. Ephemeral sandboxes are always deleted. |
gpu | 33 | string | A GPU option of the runtime it runs on (GetGpuSupport): "paravirtual" (a macOS VM on Lume: GPU acceleration, experimental), "virgl" (QEMU on Linux), "nvidia" (a runc container on Linux), a contrib provider's GPU type; "auto" picks the runtime's own. Empty: no GPU. An option the runtime does not offer here is DAEMON_ERROR_REASON_INVALID_ARGUMENT or _UNSUPPORTED, saying why. |
CreateSandboxResponse#
Response for SandboxService.CreateSandbox.
| Field | # | Type | Description |
|---|---|---|---|
sandbox | 1 | Sandbox | The sandbox. |
CreateSandboxStreamRequest#
Request for SandboxService.CreateSandboxStream.
| Field | # | Type | Description |
|---|---|---|---|
create | 1 | CreateSandboxRequest | The create, as for CreateSandbox. |
CreateSandboxStreamResponse#
One message of SandboxService.CreateSandboxStream.
| Field | # | Type | Description |
|---|---|---|---|
progress | 1 | CreateSpaceProgress (oneof event) | What the create is doing now (space is empty). |
result | 2 | CreateSandboxResponse (oneof event) | The created sandbox (the last message). |
GetSandboxRequest#
Request for SandboxService.GetSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
GetSandboxResponse#
Response for SandboxService.GetSandbox.
| Field | # | Type | Description |
|---|---|---|---|
sandbox | 1 | Sandbox | The sandbox. |
CancelCreateSandboxRequest#
Request for SandboxService.CancelCreateSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | The sandbox's name. |
CancelCreateSandboxResponse#
Response for SandboxService.CancelCreateSandbox.
| Field | # | Type | Description |
|---|---|---|---|
cancelled | 1 | bool | A create of that name was running and was stopped. |
message | 2 | string | What was removed and what stays, for people. |
DeleteSandboxRequest#
Request for SandboxService.DeleteSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
DeleteSandboxResponse#
Response for SandboxService.DeleteSandbox.
No fields.
ConnectSandboxRequest#
Request for SandboxService.ConnectSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
ConnectSandboxResponse#
Response for SandboxService.ConnectSandbox.
| Field | # | Type | Description |
|---|---|---|---|
sandbox | 1 | Sandbox | The sandbox. |
SuspendSandboxRequest#
Request for SandboxService.SuspendSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
SuspendSandboxResponse#
Response for SandboxService.SuspendSandbox.
No fields.
ResumeSandboxRequest#
Request for SandboxService.ResumeSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
ResumeSandboxResponse#
Response for SandboxService.ResumeSandbox.
No fields.
RestartSandboxRequest#
Request for SandboxService.RestartSandbox.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
RestartSandboxResponse#
Response for SandboxService.RestartSandbox.
No fields.
KeepAliveRequest#
Request for SandboxService.KeepAlive.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
duration | 2 | google.protobuf.Duration | How long to extend the lease by. |
KeepAliveResponse#
Response for SandboxService.KeepAlive.
No fields.
WaitReadyRequest#
Request for SandboxService.WaitReady.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
probes | 2 | repeated ReadinessProbe | Probes to wait for. |
timeout | 3 | google.protobuf.Duration | Total budget. |
WaitReadyResponse#
Response for SandboxService.WaitReady.
No fields.
HttpHeader#
One HTTP header.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Header name. |
value | 2 | string | Header value. |
ServiceRequestRequest#
Request for SandboxService.ServiceRequest.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
service | 2 | string | Logical service name, for example "env" or "server". |
method | 3 | string | HTTP method. Empty means GET. |
path | 4 | string | Path (and query) under the service. |
body | 5 | bytes | Request body. |
timeout | 6 | google.protobuf.Duration | Timeout. Unset means 30 seconds. |
headers | 7 | repeated HttpHeader | Request headers (for example content-type, or accept and mcp-session-id for MCP). On Fleet the gateway bearer and claim header are added by the daemon and may not be set here. |
ServiceRequestResponse#
Response for SandboxService.ServiceRequest.
| Field | # | Type | Description |
|---|---|---|---|
status | 1 | uint32 | HTTP status. |
headers | 2 | repeated HttpHeader | Response headers. |
body | 3 | bytes | Response body. |
ForwardPortRequest#
Request for SandboxService.ForwardPort.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
port | 2 | uint32 | Guest port. |
ForwardPortResponse#
Response for SandboxService.ForwardPort.
| Field | # | Type | Description |
|---|---|---|---|
forward_id | 1 | string | Forward id for CloseForward. Empty when no listener was started (the port is only reachable as url). |
guest_port | 2 | uint32 | Guest port. |
local_addr | 3 | string | Loopback host:port accepting connections, when a TCP forward runs. |
url | 4 | string | URL to use (a loopback URL, or the Fleet gateway URL of the port's service). |
CloseForwardRequest#
Request for SandboxService.CloseForward.
| Field | # | Type | Description |
|---|---|---|---|
forward_id | 1 | string | Forward id. |
CloseForwardResponse#
Response for SandboxService.CloseForward.
No fields.
GetEnvEndpointRequest#
Request for SandboxService.GetEnvEndpoint.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
probe_timeout | 2 | google.protobuf.Duration | Probe timeout. Unset uses the daemon default. |
GetServiceEndpointRequest#
Request for SandboxService.GetServiceEndpoint.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
service | 2 | string | Service name, for example "mcp". |
GetServiceEndpointResponse#
Response for SandboxService.GetServiceEndpoint.
| Field | # | Type | Description |
|---|---|---|---|
url | 1 | string | Base URL, for example "http://127.0.0.1:52011/v1/sandboxes/dev/svc/mcp". Append the path. |
headers | 2 | repeated HttpHeader | Headers every request needs (the daemon's loopback bearer). |
GetEnvEndpointResponse#
Response for SandboxService.GetEnvEndpoint.
| Field | # | Type | Description |
|---|---|---|---|
url | 1 | string | Loopback passthrough base URL, for example "http://127.0.0.1:52011/v1/sandboxes/dev/env". Append the gRPC path. |
token | 2 | string | Bearer token for the passthrough (the daemon's loopback token). |
spacesd_version | 3 | string | spacesd version reported by the probe. |
GetServiceUrlRequest#
Request for SandboxService.GetServiceUrl.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
service | 2 | string | Logical service name. |
GetServiceUrlResponse#
Response for SandboxService.GetServiceUrl.
| Field | # | Type | Description |
|---|---|---|---|
url | 1 | string | The URL (no trailing slash). |
PublicUrl#
A shareable, expiring URL of a sandbox service.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Id for RevokePublicUrl. |
url | 2 | string | The URL. |
expires_at | 3 | google.protobuf.Timestamp | When it stops working. |
sandbox | 4 | string | Sandbox name. |
service | 5 | string | Logical service name. |
provider_details | 6 | map of string to string | Provider internals (cloud: namespace, claim; local: upstream). |
CreatePublicUrlRequest#
Request for SandboxService.CreatePublicUrl.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref or unique name (with upstream_url, only recorded). |
service | 2 | string | Logical service name. |
ttl | 3 | google.protobuf.Duration | Lifetime, 60 s to 24 h. Unset means 1 h. |
label | 4 | string | Label shown in listings (cloud). |
upstream_url | 5 | string | Share this loopback http:// URL instead of resolving name and service (an embedded SDK runtime asking the daemon to host its URL). |
CreatePublicUrlResponse#
Response for SandboxService.CreatePublicUrl.
| Field | # | Type | Description |
|---|---|---|---|
public_url | 1 | PublicUrl | The URL. |
RevokePublicUrlRequest#
Request for SandboxService.RevokePublicUrl.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Sandbox ref ("local:<name>", "cloud:<name>", "direct:<host:port>", a legacy id) or a name that is unique across locations. |
id | 2 | string | PublicUrl.id. |
RevokePublicUrlResponse#
Response for SandboxService.RevokePublicUrl.
No fields.
SandboxProvider#
Where a sandbox comes from. Deprecated: requests use the location
string (local, cloud, direct:<addr>), which also names third-party
providers; responses carry Sandbox.location.
| Value | # | Description |
|---|---|---|
SANDBOX_PROVIDER_UNSPECIFIED | 0 | Not set. |
SANDBOX_PROVIDER_FLEET | 1 | Claimed from a Fleet pool. |
SANDBOX_PROVIDER_LOCAL | 2 | Run locally through cua-vmm (Lume, QEMU, container). |
SANDBOX_PROVIDER_DIRECT | 3 | An existing machine reached by URL and token. |
SANDBOX_PROVIDER_CONTRIB | 4 | A contrib provider (third-party platform). |
SandboxState#
Sandbox lifecycle state.
| Value | # | Description |
|---|---|---|
SANDBOX_STATE_UNSPECIFIED | 0 | Not reported. |
SANDBOX_STATE_PROVISIONING | 1 | Being created or booted. |
SANDBOX_STATE_RUNNING | 2 | Running and ready (per its readiness probes). |
SANDBOX_STATE_STOPPED | 3 | Suspended or stopped; can resume. |
SANDBOX_STATE_DELETING | 4 | Being deleted. |
SANDBOX_STATE_FAILED | 5 | Failed; see Sandbox.error. |
Types in cua/daemon/v1/runtime.proto#
RuntimeCheck#
One doctor check.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Component, for example "lume", "qemu", "docker", "runsc". |
status | 2 | CheckStatus | Status. |
version | 3 | string | Detected version, when present. |
detail | 4 | string | Explanation or remediation. |
DoctorRequest#
Request for RuntimeService.Doctor.
No fields.
DoctorResponse#
Response for RuntimeService.Doctor.
| Field | # | Type | Description |
|---|---|---|---|
checks | 1 | repeated RuntimeCheck | Checks, in a stable order. |
report_json | 2 | string | The full host report (cua-vmm DoctorReport) as JSON. |
SetupRequest#
Request for RuntimeService.Setup.
| Field | # | Type | Description |
|---|---|---|---|
components | 1 | repeated string | Components to set up. Empty means every installable component. |
dry_run | 2 | bool | Report the plan without changing anything. |
SetupStep#
One setup step.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Component. |
status | 2 | CheckStatus | Status after the step. |
detail | 3 | string | What was done, or would be done on a dry run. |
SetupResponse#
Response for RuntimeService.Setup.
| Field | # | Type | Description |
|---|---|---|---|
steps | 1 | repeated SetupStep | Steps, in execution order. |
LocalImage#
A local image.
| Field | # | Type | Description |
|---|---|---|---|
reference | 1 | string | Reference. |
kind | 2 | string | container or vm. |
location | 3 | string | Local disk path (VM images) or engine image reference (containers). |
size_bytes | 4 | uint64 | Size in bytes, when known. |
PullImageRequest#
Request for RuntimeService.PullImage.
| Field | # | Type | Description |
|---|---|---|---|
reference | 1 | string | Reference, with an optional backend prefix (container:, vm:). |
PullImageResponse#
Response for RuntimeService.PullImage.
| Field | # | Type | Description |
|---|---|---|---|
image | 1 | LocalImage | The pulled image. |
BuildImageRequest#
Request for RuntimeService.BuildImage.
| Field | # | Type | Description |
|---|---|---|---|
spec_json | 1 | string | images.cua.ai/v1alpha1 Image resource as JSON. |
base | 2 | string | Base image, with an optional backend prefix (container:, vm:, disk:). |
push | 3 | string | Push the result to this reference. Empty keeps it local. |
BuildImageResponse#
Response for RuntimeService.BuildImage.
| Field | # | Type | Description |
|---|---|---|---|
result | 1 | string | reference@digest when pushed, else the local output directory. |
PushImageRequest#
Request for RuntimeService.PushImage.
| Field | # | Type | Description |
|---|---|---|---|
reference | 1 | string | Source reference. |
destination | 2 | string | Destination reference. |
PushImageResponse#
Response for RuntimeService.PushImage.
| Field | # | Type | Description |
|---|---|---|---|
digest | 1 | string | Pushed manifest digest. |
CheckStatus#
Status of one local runtime component.
| Value | # | Description |
|---|---|---|
CHECK_STATUS_UNSPECIFIED | 0 | Not reported. |
CHECK_STATUS_OK | 1 | Present and usable. |
CHECK_STATUS_INSTALLABLE | 2 | Missing, but cua runtime setup can install it. |
CHECK_STATUS_ERROR | 3 | Missing or broken and needs user action. |
CHECK_STATUS_NOT_APPLICABLE | 4 | Not applicable on this host. |
Types in cua/daemon/v1/spaces.proto#
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 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. |
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. |
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.
No fields.
ListSpacesResponse#
Response for SpaceService.ListSpaces.
| Field | # | Type | Description |
|---|---|---|---|
spaces | 1 | repeated Space | Spaces. |
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. |
ClaimFleetSpaceRequest#
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. |
ClaimFleetSpaceResponse#
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. |
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. |
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). |
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", "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. |
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. |
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. |
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. |
GetGpuSupportRequest#
Request for SpaceService.GetGpuSupport.
| Field | # | Type | Description |
|---|---|---|---|
location | 1 | string | "local" (empty) or "cloud". |
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 (cloud GPU types). |
GpuSupport#
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. |
GetGpuSupportResponse#
Response for SpaceService.GetGpuSupport.
| Field | # | Type | Description |
|---|---|---|---|
runtimes | 1 | repeated GpuSupport | One entry per runtime of the location. |
DeleteSpaceRequest#
Request for SpaceService.DeleteSpace.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | Space. |
DeleteSpaceResponse#
Response for SpaceService.DeleteSpace.
| Field | # | Type | Description |
|---|---|---|---|
message | 1 | string | What happened, for humans. |
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. |
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. |
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", "fleet", "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. |
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 Fleet credentials). |
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_FLEET | 7 | Fleet API failure. |
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_POOL_SPEC_MISMATCH | 16 | A named cloud pool's template differs from the requested sandbox fields (pass apply to update it). |
DAEMON_ERROR_REASON_CLAIM_SECRETS_NOT_DELIVERED | 17 | A claim bound but its per-claim secrets never reached the sandbox; the claim was released. |
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_FLEET_ADMISSION_DENIED | 21 | Fleet's admission refused a write, for example a sandbox size over the account's limits. The message is Fleet's and names the limit. |
DAEMON_ERROR_REASON_CLOUD_CREDIT_EXHAUSTED | 22 | The account is out of Cua Cloud credit (no credit left, and no card or plan): new cloud sandboxes are refused, running ones keep running. The message ends with the website billing page's URL. |
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, 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. |