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 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 8 (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> (the Fleet gateway consumes authorization). The token grants full control of the machine: 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 /files | Signed URL from CreateSignedUrl | Upload and download with Range; 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.
| Service | Package | Page | RPCs |
|---|---|---|---|
SystemService | cua.env.v1 | System | 10 |
ProcessService | cua.env.v1 | Processes | 8 |
FilesystemService | cua.env.v1 | Filesystem | 16 |
ComputerService | cua.env.v1 | Computer and driver | 7 |
DriverService | cua.env.v1 | Computer and driver | 2 |
WindowsService | cua.env.v1 | Windows and accessibility | 11 |
AccessibilityService | cua.env.v1 | Windows and accessibility | 3 |
StreamService | cua.env.v1 | Streams and presence | 5 |
PresenceService | cua.env.v1 | Streams and presence | 3 |
TeleportService | cua.env.v1 | Teleport, tunnels and the volume | 7 |
TunnelService | cua.env.v1 | Teleport, tunnels and the volume | 6 |
VolumeService | cua.env.v1 | Teleport, tunnels and the volume | 3 |
HostSpacesService | cua.env.v1 | Host Spaces | 6 |
SandboxService | cua.daemon.v1 | Daemon: sandboxes | 19 |
RuntimeService | cua.daemon.v1 | Daemon: local runtimes | 5 |
SpaceService | cua.daemon.v1 | Daemon: Spaces | 16 |
DaemonService | cua.daemon.v1 | Daemon: service | 3 |
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 (the Fleet 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). |
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. |
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 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 are google.rpc.Status with typed details: spacesd packs ErrorInfo and the daemon packs DaemonErrorInfo.