Protocol
The gRPC contracts of cua-spacesd (cua.env.v1) and the cua daemon (cua.daemon.v1): ports, routes, auth and every RPC.
The gRPC contracts, generated from the .proto files in libs/cua/proto. cua.env.v1 is served by cua-spacesd inside a sandbox; cua.daemon.v1 is served by the local cua daemon. Changes are additive and pass buf breaking.
Contract revision: cua.env.v1 protocol version 1, revision 13 (reported by SystemService.GetCapabilities).
Clients use the SDK's SpacesdClient or cua spacesd ...; SpacesdClient.call_json reaches any RPC below. Sandboxes do not require cua-spacesd: only the computer interfaces and the Spaces primitives need it. It never injects input itself; pointer and keyboard actions go to Cua Driver.
| Port | Carries |
|---|---|
| TCP 3211 | Native gRPC (HTTP/2) and gRPC-Web (HTTP/1.1), gRPC reflection, and the HTTP routes below |
| UDP 3212 | QUIC media datagrams (ALPN rcdp/2, certificate pinned through StreamService.OpenMedia) |
The default bind is 0.0.0.0:3211 with a token and 127.0.0.1:3211 without one; a non-loopback bind without a token is refused. Clients send the env token as authorization: Bearer <token> or x-cua-env-authorization: Bearer <token> (a gateway may consume authorization). The token grants full control of the computer: never put it in a URL; browsers use tickets and signed URLs.
| Route | Auth | Purpose |
|---|---|---|
GET /health | None | 204 while serving, 503 while shutting down |
GET, HEAD, PUT, POST /files | Signed URL from CreateSignedUrl | Upload and download with Range; a URL signed for PUT also takes POST multipart/form-data (the first file part, answered with [{"name","path","type"}]); 403 when expired or tampered |
POST /mcp | Env token | Streamable-HTTP MCP over the Cua Driver tools; 501 when disabled |
GET /tunnel (WebSocket) | Ticket from TunnelService.Forward | Port forwarding |
GET /hotspot (WebSocket) | Ticket from StartHotspot | Reverse SOCKS egress |
GET /media (WebSocket) | Ticket from StreamService.OpenMedia | Video (H.264) and audio (Opus), media wire v2 (libs/cua/proto/MEDIA.md) |
Tickets go in ?ticket= or the WebSocket subprotocol cua.ticket.<ticket>. Tickets and signed URLs are keyed from the env token, so rotating the token revokes them.
Services#
Metadata and HTTP routes#
Well-known metadata keys and HTTP paths (cua_proto::metadata).
| Constant | Value | Meaning |
|---|---|---|
AUTHORIZATION | authorization | Bearer token header: authorization: Bearer <token>. |
ENV_AUTHORIZATION | x-cua-env-authorization | Alternate spacesd token header, x-cua-env-authorization: Bearer <token>, for paths where authorization belongs to an outer hop (a gateway consumes and strips it). Servers accept either header. |
PRINCIPAL_BIN | x-cua-principal-bin | Binary metadata carrying a serialized cua.env.v1.Principal. |
HEALTH_PATH | /health | Plain-HTTP, unauthenticated health route (204 when healthy). |
MEDIA_WS_PATH | /media | Media WebSocket path (ticket-authenticated). |
TUNNEL_WS_PATH | /tunnel | TCP-over-WebSocket tunnel path (ticket-authenticated). |
HOTSPOT_WS_PATH | /hotspot | Reverse-SOCKS hotspot WebSocket path (ticket-authenticated). |
SPAWN_WS_PATH | /spawn | Spawn channel WebSocket path (ticket-authenticated): the host that runs the Space serves its child-Space API over it. |
HOST_PORTS_WS_PATH | /hostports | Host ports WebSocket path (ticket-authenticated): the host that runs the Space carries its listed host ports, published on the Space's own loopback. |
SPAWN_TOKEN_FILE | spawn-token | File (in a [spawn_dirs] directory) holding a Space's spawn capability. |
SPAWN_ADDRESS_FILE | spawn-address | File (in a [spawn_dirs] directory) holding the spawn listener's URL. |
ENV_SPACE | CUA_SPACE | Environment of processes in a Space: its id. |
ENV_SPAWN | CUA_SPAWN | Environment of processes in a Space: the spawn listener's URL. |
ENV_SPAWN_TOKEN_FILE | CUA_SPAWN_TOKEN_FILE | Environment of processes in a Space: the capability's file. |
VOLUME_WS_PATH | /volume | Cua Volume WebSocket path (ticket-authenticated): the client serves the guest's volume mount over it. |
FILES_PATH | /files | Signed-URL file route. |
MCP_PATH | /mcp | Streamable-HTTP MCP endpoint for the cua-driver tool registry. |
SNAPSHOT_BLOBS_PATH | /v1/snapshots/blobs/{sha} | A host's checkpoint files, by SHA-256 (<path>/<sha256>), for copying them to the owner's other machines; authenticated by a snapshot read grant (HostSnapshotsService.ExportHostSnapshot), with HTTP range requests. Served by hosts that provide Spaces. |
VIEWER_PATH | /viewer | The web viewer (static page, unauthenticated; it reads its viewer ticket from the URL fragment). Served with and without the trailing slash; assets live under /viewer/. |
gRPC-Web fallbacks#
gRPC-Web cannot carry client streams, so every client-streaming RPC has a unary fallback (cua_proto::CLIENT_STREAM_FALLBACKS).
| Client stream | Unary fallback |
|---|---|
/cua.env.v1.ProcessService/StreamInput | /cua.env.v1.ProcessService/SendInput |
/cua.env.v1.FilesystemService/WriteFile | /cua.env.v1.FilesystemService/UploadChunk |
Errors#
Errors are google.rpc.Status with typed details: spacesd packs ErrorInfo and the daemon packs DaemonErrorInfo.