System
cua.env.v1 SystemService: capabilities, init, health, shutdown, viewer tickets and relay attach.
cua.env.v1 SystemService: capabilities, init, health, shutdown, viewer tickets and relay attach.
The handshake (GetCapabilities), session init, health, shutdown, viewer tickets and joining a relay (AttachRelay).
Source: libs/cua/proto/cua/env/v1/system.proto.
cua.env.v1.SystemService
Discovery, bootstrap and lifecycle of the spacesd itself.
GetCapabilities is the probe the SDK uses to decide whether a sandbox has
cua-spacesd at all (sb.spacesd()), and which features it may rely on.
/cua.env.v1.SystemService/GetCapabilities, unary: GetCapabilitiesRequest to GetCapabilitiesResponse.
Returns version, platform and the feature list. Cheap; safe to poll.
/cua.env.v1.SystemService/Init, unary: InitRequest to InitResponse.
Configures the driver after boot or claim. Idempotent: repeating the same request is a no-op, and later calls overwrite earlier values.
/cua.env.v1.SystemService/Health, unary: HealthRequest to HealthResponse.
Liveness and per-component health. The same information in reduced form
is served unauthenticated as plain HTTP GET /health (204 when healthy).
/cua.env.v1.SystemService/Metrics, unary: MetricsRequest to MetricsResponse.
A point-in-time sample of guest resource usage.
/cua.env.v1.SystemService/Shutdown, unary: ShutdownRequest to ShutdownResponse.
Stops or restarts the driver, or powers off or reboots the guest.
/cua.env.v1.SystemService/Diagnose, server stream: DiagnoseRequest to DiagnoseResponse.
Runs the image self-test (the checks of cua-spacesd doctor) and
streams each check as it finishes, then the report. Requires the token
even in bootstrap modes: the report names paths, versions and units.
/cua.env.v1.SystemService/DiagnoseOnce, unary: DiagnoseOnceRequest to DiagnoseOnceResponse.
Diagnose as one unary call returning only the final report, for
clients that cannot read server streams.
/cua.env.v1.SystemService/CreateViewerTicket, unary: CreateViewerTicketRequest to CreateViewerTicketResponse.
Mints a viewer ticket: a scoped, expiring credential for the web viewer
served at /viewer on this port. It authorizes only the calls a viewer
makes (streaming, and clipboard and files when granted) and is safe in
a URL fragment. Viewer tickets cannot mint viewer tickets.
/cua.env.v1.SystemService/AttachRelay, unary: AttachRelayRequest to AttachRelayResponse.
Makes this running driver reachable through a cua-relay as a machine
of the owner's account, without restarting it (what cua-spacesd join
does at start). Callers then authenticate with relay-signed
assertions: the owner, accounts the relay shares the machine with, and
view-only accounts that may only watch. Only the root-token holder may
call it (never a relay caller or a viewer ticket). Feature
relay_attach.
/cua.env.v1.SystemService/DetachRelay, unary: DetachRelayRequest to DetachRelayResponse.
Leaves the relay attached with AttachRelay and stops accepting relay
assertions. Root-token holder only.
cua/env/v1/system.proto#Request for SystemService.GetCapabilities.
No fields.
Response for SystemService.GetCapabilities.
| Field | # | Type | Description |
|---|---|---|---|
version | 1 | string | cua-spacesd release version (semver), for example "0.3.1". |
protocol_version | 2 | uint32 | Major contract version. Always 1 for package cua.env.v1. |
protocol_revision | 3 | uint32 | Additive revision within the major version. Incremented whenever an RPC, field or enum value is added, so clients can reason about optional surface without probing. |
os | 4 | OperatingSystem | Guest operating system. |
runtime | 5 | Runtime | How the guest is hosted. |
runtime_detail | 6 | string | Free-form runtime detail (for example "runsc 20260901" or "kubevirt 1.4 / qemu 9.1"). |
arch | 7 | Architecture | Guest CPU architecture. |
display_server | 8 | DisplayServer | The graphical session type, or DISPLAY_SERVER_NONE when headless. |
displays | 9 | repeated Display | Displays attached to the guest desktop. Empty when headless. |
features | 10 | repeated Feature | Every feature the driver knows about, supported or not. Unsupported features carry a limitation. See Feature for canonical names. |
hostname | 11 | string | Guest hostname. |
initialized | 12 | bool | True once Init has succeeded at least once since the driver started. |
boot_time | 13 | google.protobuf.Timestamp | When the guest booted. |
side_channels | 14 | SideChannels | Where the media and tunnel sockets are served. |
limits | 15 | Limits | Server-enforced size limits clients must respect. |
machine_seal_public_key | 16 | bytes | This guest's long-term X25519 public key for sealed delivery (S1): Keyvault site-login and teleport bundle payloads sealed to it cross a relay as ciphertext. Generated on first start, 0600. Empty from a guest image that predates this (older images): callers must refuse to deliver such secrets over a relay: path unless the user explicitly opts in per delivery. 32 bytes when present. |
Guest operating system description.
| Field | # | Type | Description |
|---|---|---|---|
family | 1 | OsFamily | OS family. |
name | 2 | string | Distribution or product name, for example "Ubuntu" or "macOS". |
version | 3 | string | Version string, for example "24.04" or "15.4". |
kernel | 4 | string | Kernel release, for example "6.8.0-45-generic" or "Darwin 24.4.0". |
pretty_name | 5 | string | The full product string, for example "Ubuntu 24.04.3 LTS", "macOS 26.5.2 (25F84)" or "Windows Server 2022 Datacenter 10.0.20348". Empty from older drivers: use name and version. |
One capability and whether this guest supports it.
Canonical names (lowercase, dot-separated, stable forever):
"a11y", "background_input", "desktop_stream", "window_stream", "h264_hw",
"h264_sw", "quic_media", "pty", "fs_watch", "clipboard.text",
"clipboard.files", "presence", "windows", "launch_app", "driver",
"tunnel.forward", "hotspot", "teleport.<provider>" (for example
"teleport.firefox"), "audio.desktop" (desktop audio capture),
"audio.per_app" (per-application audio capture; when unsupported, per-app
requests fall back to desktop audio and limitation says so),
"audio.uplink" (client audio into a guest virtual source), "audio.opus",
"presence.cursor_shape" (server-computed cursor shapes; attributes
"hit_test", "system" and "probe" name the backends, "probe" is "off" when
PresenceSettings.cursor_probe is disabled), and "experimental.<name>"
for experimental fields.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Canonical feature name. |
supported | 2 | bool | True if the feature works on this guest. |
limitation | 3 | string | When unsupported or degraded: why, in one sentence a user can act on (for example "AT-SPI bus not running; start the session with dbus-run-session"). Empty when fully supported. |
attributes | 4 | map of string to string | Feature-specific details (for example {"encoder": "vaapi"} for "h264_hw", {"isolation": "runc"} for a container runtime). |
Where the non-gRPC sockets live, relative to the gRPC endpoint.
| Field | # | Type | Description |
|---|---|---|---|
media_ws_path | 1 | string | HTTP path of the media WebSocket, normally "/media". |
media_quic_port | 2 | uint32 | UDP port of the direct QUIC media listener, 0 when disabled. Normally the gRPC port plus one (3212). |
tunnel_ws_path | 3 | string | HTTP path of the TCP-over-WebSocket tunnel, normally "/tunnel". |
files_http_path | 4 | string | HTTP path of the signed-URL file route, normally "/files". |
mcp_http_path | 5 | string | HTTP path of the streamable-HTTP MCP endpoint exposing the cua-driver tool registry, normally "/mcp". Empty when disabled. |
Server-enforced limits.
| Field | # | Type | Description |
|---|---|---|---|
max_chunk_bytes | 1 | uint32 | Largest bytes payload accepted in one chunk message (upload chunks, stdin chunks, receive-files chunks). Normally 4 MiB. |
max_message_bytes | 2 | uint32 | Largest encoded gRPC message accepted or sent. Normally 8 MiB. |
preferred_chunk_bytes | 3 | uint32 | Recommended chunk size for bulk transfer. Normally 1 MiB. |
default_scrollback_bytes | 4 | uint64 | Default per-process scrollback ring size in bytes. |
Request for SystemService.Init.
| Field | # | Type | Description |
|---|---|---|---|
token | 1 | string | Access token to install. If the driver has no token yet (first claim), the call must arrive over an already-authenticated channel such as the Fleet gateway or loopback. If a token is configured, the call must be authenticated with it, and a different value here rotates it. Empty leaves the token unchanged. |
env | 2 | map of string to string | Environment variables added to every process started afterwards. Keys present here replace earlier values; an empty value unsets the key. |
default_user | 3 | string | Default OS user for processes and file operations. Empty keeps the current default (the driver's own user). |
default_workdir | 4 | string | Default working directory for processes. Empty keeps the user's home. |
ca_bundle | 5 | bytes | PEM-encoded CA certificates appended to the guest trust store. |
now | 6 | google.protobuf.Timestamp | Caller's wall clock. When set and the guest clock is off by more than one second, the driver steps the guest clock (VMs resumed from snapshot drift). |
labels | 7 | map of string to string | Opaque labels recorded for diagnostics (for example sandbox name, claim id). |
audio_uplink | 8 | AudioUplinkAccess | Who may open an audio uplink (StreamService.OpenMedia with audio.uplink.enabled). Unset leaves the current setting; the initial setting is disabled. |
presence | 9 | PresenceSettings | Presence settings of this Space. Unset leaves the current settings. |
Per-Space presence settings.
| Field | # | Type | Description |
|---|---|---|---|
cursor_probe | 1 | optional bool | Whether the server may read the real cursor shape at a participant's position by briefly moving the guest pointer there while it is idle (no injected input or agent action recently) and restoring it exactly. Gives app-specific shapes the accessibility hit-test cannot infer; hover states may flash under the probe. Unset leaves the current setting; the initial setting is enabled. |
Per-principal permission for audio uplink.
| Field | # | Type | Description |
|---|---|---|---|
mode | 1 | AudioUplinkMode | Access mode. |
principal_ids | 2 | repeated string | With AUDIO_UPLINK_MODE_ALLOWLIST: Principal.id values allowed to open an uplink. |
Response for SystemService.Init.
| Field | # | Type | Description |
|---|---|---|---|
token_changed | 1 | bool | True if this call installed or rotated the token. |
clock_adjusted | 2 | bool | True if the guest clock was stepped. |
Request for SystemService.Health.
No fields.
Response for SystemService.Health.
| Field | # | Type | Description |
|---|---|---|---|
status | 1 | HealthStatus | Overall status, the worst of all components. |
components | 2 | repeated ComponentHealth | Per-subsystem status (for example "capture", "a11y", "encoder", "filesystem"). |
uptime | 3 | google.protobuf.Duration | Time since the driver process started. |
Health of one subsystem.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Subsystem name. |
status | 2 | HealthStatus | Its status. |
detail | 3 | string | Why it is not serving, when applicable. |
Request for SystemService.Metrics.
| Field | # | Type | Description |
|---|---|---|---|
disk_path | 1 | string | Path whose filesystem is reported in disk_*. Empty means the default working directory's filesystem. |
Response for SystemService.Metrics.
| Field | # | Type | Description |
|---|---|---|---|
sampled_at | 1 | google.protobuf.Timestamp | When the sample was taken. |
cpu_count | 2 | uint32 | Logical CPUs visible to the guest. |
cpu_percent | 3 | double | CPU utilisation across all CPUs, 0 to 100. |
load_average_1m | 4 | double | 1-minute load average (0 on Windows). |
memory_total_bytes | 5 | uint64 | Total guest memory in bytes. |
memory_used_bytes | 6 | uint64 | Used guest memory in bytes (excluding reclaimable cache). |
disk_total_bytes | 7 | uint64 | Total bytes of the filesystem named by disk_path. |
disk_used_bytes | 8 | uint64 | Used bytes of that filesystem. |
managed_process_count | 9 | uint32 | Processes currently managed by ProcessService. |
media_session_count | 10 | uint32 | Open media sessions. |
network_rx_bytes | 11 | uint64 | Bytes received on all guest network interfaces since boot. |
network_tx_bytes | 12 | uint64 | Bytes sent on all guest network interfaces since boot. |
memory_limited | 13 | bool | memory_total_bytes is the guest's own limit: a virtual machine's memory or a container's cgroup memory limit. False when it is only the host's memory (a container without a limit, bare metal). |
disk_limited | 14 | bool | disk_total_bytes is the guest's own disk: a virtual machine's disk or a filesystem with a quota. False when it is the host's (a container's overlay, bare metal). |
Request for SystemService.Shutdown.
| Field | # | Type | Description |
|---|---|---|---|
mode | 1 | ShutdownMode | What to stop. |
grace_period | 2 | google.protobuf.Duration | How long to wait for in-flight RPCs and managed processes before forcing. Unset means 5 seconds. |
reason | 3 | string | Reason recorded in the driver log. |
Response for SystemService.Shutdown. Sent before the shutdown begins.
No fields.
Request for SystemService.CreateViewerTicket.
| Field | # | Type | Description |
|---|---|---|---|
ttl | 1 | google.protobuf.Duration | Lifetime. Unset means 1 hour; the maximum is 24 hours. Rotating the root token revokes every viewer ticket. |
policy | 2 | SessionPolicy | Highest session policy the viewer may open media with. Unset means SESSION_POLICY_ALLOW_ACTIVATION (a full interactive viewer). |
clipboard | 3 | bool | Allow ComputerService.GetClipboard and SetClipboard. |
files_root | 4 | string | Guest directory the viewer may read and write through FilesystemService (drag-and-drop uploads and folder sharing). Empty means no file access. ~ is the desktop user's home. |
audio_uplink | 5 | bool | Allow a microphone uplink track (still subject to InitRequest.audio_uplink). |
principal | 6 | Principal | Who is viewing, shown to other participants. The id is prefixed with viewer: by the server. |
Response for SystemService.CreateViewerTicket.
| Field | # | Type | Description |
|---|---|---|---|
ticket | 1 | string | The ticket. The viewer sends it as x-cua-env-authorization: Bearer <ticket> (or authorization). |
expires_at | 2 | google.protobuf.Timestamp | When it expires. |
viewer_path | 3 | string | Path of the viewer page with the ticket in the fragment, relative to this port: /viewer/#ticket=<ticket>. Fragments never reach servers or proxies. |
files_root | 4 | string | files_root resolved to an absolute guest path (empty without file access). |
Request for SystemService.AttachRelay.
| Field | # | Type | Description |
|---|---|---|---|
relay_url | 1 | string | Relay base URL (wss://relay.cua.ai, ws://relay:8080, https://...). |
machine_token | 2 | string | The machine token the relay issued when the owner registered this machine (POST /v1/machines). Kept in memory only. |
machine_id | 3 | string | The machine id the owner registered ([a-z0-9-]{8,64}). |
relay_jwks_json | 4 | string | The relay's signing keys (JWKS JSON) from the registration, pinned: the join handshake must present one of them. |
owner | 5 | string | The owning account id. |
owner_email | 6 | string | The owner's email (informational). |
Response for SystemService.AttachRelay.
| Field | # | Type | Description |
|---|---|---|---|
machine_id | 1 | string | The machine id this driver joined as. |
Request for SystemService.DetachRelay.
No fields.
Response for SystemService.DetachRelay.
| Field | # | Type | Description |
|---|---|---|---|
detached | 1 | bool | False when no relay was attached. |
Operating system family.
| Value | # | Description |
|---|---|---|
OS_FAMILY_UNSPECIFIED | 0 | Not reported. |
OS_FAMILY_LINUX | 1 | Linux. |
OS_FAMILY_MACOS | 2 | macOS. |
OS_FAMILY_WINDOWS | 3 | Windows. |
How the guest is hosted.
| Value | # | Description |
|---|---|---|
RUNTIME_UNSPECIFIED | 0 | Not reported. |
RUNTIME_UNKNOWN | 1 | Could not be determined. |
RUNTIME_KUBEVIRT | 2 | A KubeVirt virtual machine (Fleet). |
RUNTIME_GVISOR | 3 | A gVisor (runsc) sandboxed container. |
RUNTIME_LUME | 4 | A Lume (Apple Virtualization.framework) virtual machine. |
RUNTIME_QEMU | 5 | A QEMU virtual machine outside KubeVirt. |
RUNTIME_CONTAINER | 6 | A plain container (runc or equivalent). |
RUNTIME_BARE | 7 | Bare metal or an unmanaged host (for example a laptop joined through the relay). |
RUNTIME_HYPERV | 8 | A Hyper-V virtual machine. |
CPU architecture.
| Value | # | Description |
|---|---|---|
ARCHITECTURE_UNSPECIFIED | 0 | Not reported. |
ARCHITECTURE_X86_64 | 1 | x86-64 / amd64. |
ARCHITECTURE_ARM64 | 2 | AArch64 / arm64. |
Graphical session type.
| Value | # | Description |
|---|---|---|
DISPLAY_SERVER_UNSPECIFIED | 0 | Not reported. |
DISPLAY_SERVER_NONE | 1 | No graphical session. |
DISPLAY_SERVER_X11 | 2 | X11 (including Xvfb). |
DISPLAY_SERVER_WAYLAND | 3 | Wayland. |
DISPLAY_SERVER_QUARTZ | 4 | macOS Quartz / WindowServer. |
DISPLAY_SERVER_WIN32 | 5 | Windows desktop window manager. |
Audio uplink access mode.
| Value | # | Description |
|---|---|---|
AUDIO_UPLINK_MODE_UNSPECIFIED | 0 | Not set. Keeps the current mode. |
AUDIO_UPLINK_MODE_DISABLED | 1 | No uplinks. The initial mode. |
AUDIO_UPLINK_MODE_ALLOWLIST | 2 | Only principals in principal_ids. |
AUDIO_UPLINK_MODE_ANY | 3 | Any authenticated caller. |
Health status.
| Value | # | Description |
|---|---|---|
HEALTH_STATUS_UNSPECIFIED | 0 | Not reported. |
HEALTH_STATUS_SERVING | 1 | Fully operational. |
HEALTH_STATUS_DEGRADED | 2 | Operational with reduced function (see component details). |
HEALTH_STATUS_NOT_SERVING | 3 | Not operational. |
What SystemService.Shutdown stops.
| Value | # | Description |
|---|---|---|
SHUTDOWN_MODE_UNSPECIFIED | 0 | Not set. Rejected with INVALID_ARGUMENT, to avoid accidental power-off. |
SHUTDOWN_MODE_DRIVER_EXIT | 1 | Exit the driver. The service manager may restart it. |
SHUTDOWN_MODE_DRIVER_RESTART | 2 | Restart the driver in place (re-exec). |
SHUTDOWN_MODE_GUEST_POWEROFF | 3 | Power off the guest. |
SHUTDOWN_MODE_GUEST_REBOOT | 4 | Reboot the guest. |