System, diagnostics and shared types
cua.env.v1 SystemService, the image self-test report, and the types every spacesd service shares: ErrorInfo, principals and geometry.
The handshake (GetCapabilities), session init, health, shutdown, viewer tickets and joining a relay (AttachRelay); the report of the image self-test (SystemService.Diagnose / DiagnoseOnce); and the shared types: errors (google.rpc.Status carrying ErrorInfo), principals and geometry.
Source: libs/cua/proto/cua/env/v1/system.proto, libs/cua/proto/cua/env/v1/diagnose.proto, libs/cua/proto/cua/env/v1/common.proto.
SystemService#
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.
SystemService.GetCapabilities#
/cua.env.v1.SystemService/GetCapabilities, unary: GetCapabilitiesRequest to GetCapabilitiesResponse.
Returns version, platform and the feature list. Cheap; safe to poll.
SystemService.Init#
/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.
SystemService.Health#
/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).
SystemService.Metrics#
/cua.env.v1.SystemService/Metrics, unary: MetricsRequest to MetricsResponse.
A point-in-time sample of guest resource usage.
SystemService.Shutdown#
/cua.env.v1.SystemService/Shutdown, unary: ShutdownRequest to ShutdownResponse.
Stops or restarts the driver, or powers off or reboots the guest.
SystemService.Diagnose#
/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.
SystemService.DiagnoseOnce#
/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.
SystemService.CreateViewerTicket#
/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.
SystemService.AttachRelay#
/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.
SystemService.DetachRelay#
/cua.env.v1.SystemService/DetachRelay, unary: DetachRelayRequest to DetachRelayResponse.
Leaves the relay attached with AttachRelay and stops accepting relay
assertions. Root-token holder only.
Types in cua/env/v1/system.proto#
GetCapabilitiesRequest#
Request for SystemService.GetCapabilities.
No fields.
GetCapabilitiesResponse#
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. |
bulk | 17 | BulkLane | The bulk lane, when the guest has one: a second disk the host shares with it, through which same-machine file transfers skip the network. Unset when the guest has no such disk. |
BulkLane#
A disk shared between a guest and the machine hosting it, carrying file
content for ReadFileRequest.bulk_slot and UploadChunkRequest.bulk_slot.
The host-side client finds the disk's file, reads the identity from its
first bytes (the guest writes them) and uses the lane only when it equals
id: a client that cannot open that file, or finds another identity,
transfers over the network as before.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | bytes | Identity the guest wrote at the start of the disk. 16 bytes. |
slots | 2 | uint32 | Number of slots. |
slot_bytes | 3 | uint64 | Size of each slot in bytes. |
data_offset | 4 | uint64 | Offset of slot 0 in the disk. Slot i starts at data_offset + i * slot_bytes. |
OperatingSystem#
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. |
Feature#
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). |
SideChannels#
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. |
Limits#
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. |
InitRequest#
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 a 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. |
new_machine | 10 | bool | This guest just became a new machine: a Space claimed from a warm pool, or restored or forked from a memory snapshot that other Spaces share. The driver regenerates its per-machine secrets (the machine-seal keypair, the media QUIC certificate, the ticket key used without a token), resets the sealed-delivery replay guard, rewrites /etc/machine-id (and a separate dbus copy) where it may, mixes entropy into the guest's random pool (crediting it and forcing a reseed where it has the privilege), steps the clock to now, and revokes forwards, the hotspot, the volume mount and media sessions opened before, so no two Spaces share keys or random state. Senders that pinned the old machine-seal key for this Space must re-pin: send it only when the guest is a different Space than the one the snapshot was taken of (never to resume a Space from its own checkpoint). Drivers before protocol revision 10 ignore it (InitResponse.new_machine stays false). |
entropy | 11 | bytes | Random bytes from the caller's CSPRNG, mixed into the guest's entropy pool and into every secret new_machine regenerates (a restored guest's pool is its snapshot's). At least 32 bytes; at most 4096. |
PresenceSettings#
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. |
AudioUplinkAccess#
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. |
InitResponse#
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. |
new_machine | 3 | bool | True if InitRequest.new_machine was applied: this guest's per-machine secrets were regenerated (see InitRequest.new_machine). |
HealthRequest#
Request for SystemService.Health.
No fields.
HealthResponse#
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. |
ComponentHealth#
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. |
MetricsRequest#
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. |
MetricsResponse#
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; 0 when it has no size of its own (gVisor's root overlay reports "unlimited"), never a sentinel such as 2^63. |
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). |
ShutdownRequest#
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. |
ShutdownResponse#
Response for SystemService.Shutdown. Sent before the shutdown begins.
No fields.
CreateViewerTicketRequest#
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_VIEW_ONLY: a viewer that can look and cannot touch. Input is asked for by name. |
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. |
CreateViewerTicketResponse#
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). |
AttachRelayRequest#
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). |
AttachRelayResponse#
Response for SystemService.AttachRelay.
| Field | # | Type | Description |
|---|---|---|---|
machine_id | 1 | string | The machine id this driver joined as. |
DetachRelayRequest#
Request for SystemService.DetachRelay.
No fields.
DetachRelayResponse#
Response for SystemService.DetachRelay.
| Field | # | Type | Description |
|---|---|---|---|
detached | 1 | bool | False when no relay was attached. |
OsFamily#
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. |
Runtime#
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. |
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. |
Architecture#
CPU architecture.
| Value | # | Description |
|---|---|---|
ARCHITECTURE_UNSPECIFIED | 0 | Not reported. |
ARCHITECTURE_X86_64 | 1 | x86-64 / amd64. |
ARCHITECTURE_ARM64 | 2 | AArch64 / arm64. |
DisplayServer#
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. |
AudioUplinkMode#
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. |
HealthStatus#
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. |
ShutdownMode#
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. |
Types in cua/env/v1/diagnose.proto#
DiagnoseOptions#
Options shared by Diagnose and DiagnoseOnce.
| Field | # | Type | Description |
|---|---|---|---|
strict | 1 | bool | Treat warnings (and skips not allowed by the manifest) as failures. |
only | 2 | repeated string | Run only checks whose id equals, or starts with <entry>., one of these (for example "stream" or "auth.token_file"). Empty runs all. |
skip | 3 | repeated string | Skip checks matched the same way as only. |
effects | 4 | DiagnoseEffects | Which checks may change guest state. Unspecified means NONE. |
expect_manifest | 5 | bytes | A manifest (JSON, same schema as /etc/cua-image/manifest.json) to check against instead of the one baked into the image. Empty uses the image's own. |
timeout | 6 | google.protobuf.Duration | Overall budget. Unset means 120 seconds. Checks still running when it expires fail with a timeout. |
host_time | 7 | google.protobuf.Timestamp | The caller's wall clock, for the clock-skew check. Unset skips the comparison. |
DiagnoseRequest#
Request for SystemService.Diagnose.
| Field | # | Type | Description |
|---|---|---|---|
options | 1 | DiagnoseOptions | What to run. |
DiagnoseResponse#
One event of SystemService.Diagnose: started, then check, for each
check, and a final report.
| Field | # | Type | Description |
|---|---|---|---|
started | 1 | DiagnoseCheckStarted (oneof event) | A check began. |
check | 2 | DiagnoseCheck (oneof event) | A check finished. |
report | 3 | DiagnoseReport (oneof event) | The run finished. Always the last message. |
DiagnoseCheckStarted#
A check began.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Check id, for example "stream.encode.openh264". |
group | 2 | string | Check group, the id's first segment. |
DiagnoseOnceRequest#
Request for SystemService.DiagnoseOnce.
| Field | # | Type | Description |
|---|---|---|---|
options | 1 | DiagnoseOptions | What to run. |
DiagnoseOnceResponse#
Response for SystemService.DiagnoseOnce.
| Field | # | Type | Description |
|---|---|---|---|
report | 1 | DiagnoseReport | The final report. |
DiagnoseCheck#
The result of one check.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Stable id, <group>.<name>[.<detail>]. |
group | 2 | string | Group, the id's first segment (for example "auth"). |
status | 3 | CheckStatus | Outcome after severity is applied. |
severity | 4 | CheckSeverity | Severity from the manifest. |
claimed_by | 5 | repeated string | Manifest claims that make this check matter, for example "feature:desktop_stream" or "auth_mode:local". |
message | 6 | string | What happened, in one line. |
remediation | 7 | string | What to do about a warning or failure. Empty on pass. |
duration_ms | 8 | uint32 | Wall time of the check in milliseconds. |
facts | 9 | map of string to string | Measured values (for example {"backend": "openh264", "psnr_db": "41.2"}). |
artifacts | 10 | repeated DiagnoseArtifact | Evidence files. |
DiagnoseArtifact#
Evidence produced by a check.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | File name, unique within the report (for example "screenshot.display0.png"). |
media_type | 2 | string | Media type, for example "image/png". |
data | 3 | bytes | Contents, when small enough to inline (at most 1 MiB). Empty otherwise. |
path | 4 | string | Where the full file was written in the guest. Empty when not written. |
DiagnoseReport#
The whole report.
| Field | # | Type | Description |
|---|---|---|---|
schema_version | 1 | uint32 | Report schema version. Always 1 for this message. |
spacesd | 2 | DiagnoseSpacesd | The daemon that ran the checks. Unset when a shim produced the report for an image without cua-spacesd. |
image | 3 | DiagnoseImage | The image under test. |
environment | 4 | DiagnoseEnvironment | Where the guest runs. |
summary | 5 | DiagnoseSummary | Totals. |
checks | 6 | repeated DiagnoseCheck | Every check, in run order. |
fidelity | 7 | DiagnoseFidelity | Facts that make a task behave differently between variants of one image. Compared key by key by the eval-parity lane. |
producer | 8 | string | What produced the report: "cua-spacesd", or "cua-doctor-shim/<target>". |
started_at | 9 | google.protobuf.Timestamp | When the run started. |
DiagnoseSpacesd#
The daemon that ran the checks.
| Field | # | Type | Description |
|---|---|---|---|
version | 1 | string | cua-spacesd version. |
protocol_revision | 2 | uint32 | cua.env.v1 protocol revision it serves. |
git_sha | 3 | string | Source revision of the build, when known. |
cua_driver_version | 4 | string | Version of the linked cua-driver core. |
DiagnoseImage#
The image under test.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Image name from the manifest, for example "linux". |
ref | 2 | string | Reference the image was built as, when the manifest records it. |
variant | 3 | string | "rootfs" (container) or "containerdisk" (VM). |
os | 4 | string | "linux", "windows" or "macos". |
manifest_sha256 | 5 | string | SHA-256 of the manifest the checks ran against. Empty without one. |
manifest_source | 6 | string | Where the manifest came from: a guest path, "request", or empty when there is none. |
DiagnoseEnvironment#
Where the guest runs.
| Field | # | Type | Description |
|---|---|---|---|
runtime | 1 | string | Runtime: "container", "gvisor", "qemu", "kubevirt", "lume", "hyperv", "bare" or "unknown". |
runtime_detail | 2 | string | Free-form runtime detail, for example "runsc". |
arch | 3 | string | "x86_64" or "arm64". |
init | 4 | string | Init system: "systemd", "supervisord", "launchd", "scm" or "unknown". |
display_server | 5 | string | "x11", "wayland", "quartz", "win32" or "none". |
os | 6 | string | OS name and version, for example "Ubuntu 24.04". |
DiagnoseSummary#
Totals of a report.
| Field | # | Type | Description |
|---|---|---|---|
status | 1 | CheckStatus | Worst outcome: fail if any check failed, warn if any warned (fail under strict), else pass. |
pass | 2 | uint32 | Passed checks. |
warn | 3 | uint32 | Warnings. |
fail | 4 | uint32 | Failures. |
skip | 5 | uint32 | Skipped checks. |
duration_ms | 6 | uint32 | Wall time of the whole run in milliseconds. |
strict | 7 | bool | True when the run used strict. |
DiagnoseFidelity#
Facts that change how a task behaves. Every key is always present; an unknown value is the empty string.
| Field | # | Type | Description |
|---|---|---|---|
display | 1 | string | Primary display, "<width>x<height>@<scale>". |
fonts_sha256 | 2 | string | SHA-256 over the sorted list of installed font files. |
tz | 3 | string | Time zone name. |
locale | 4 | string | Locale, for example "C.UTF-8". |
clock_skew_ms | 5 | int64 | Guest clock minus the caller's clock, in milliseconds. 0 when the caller sent no host_time. |
encoder | 6 | string | Video encoder the stream would use, for example "openh264". |
a11y_backend | 7 | string | Accessibility backend, for example "atspi". |
audio_backend | 8 | string | Audio backend, for example "pipewire". |
cpu_model | 9 | string | CPU model string. |
cpu_count | 10 | uint32 | Logical CPUs. |
memory_mib | 11 | uint64 | Total memory in MiB. |
gpu | 12 | string | GPU description, or "none". |
kernel | 13 | string | Kernel release. |
runtime | 14 | string | Runtime, as in DiagnoseEnvironment.runtime. |
init | 15 | string | Init system, as in DiagnoseEnvironment.init. |
packages_sha256 | 16 | string | SHA-256 over the installed package list (name and version). |
app_versions | 17 | map of string to string | Versions of the apps the manifest lists (for example {"firefox": "130.0"}). |
tool_versions | 18 | map of string to string | Versions of the tools the manifest lists (dev tiers, for example {"node": "v22.20.0"}). |
simulator_runtimes | 19 | repeated string | Available simulator runtimes, sorted (for example "iOS 26.0"). Empty unless the manifest claims some. |
DiagnoseEffects#
Which checks may act on the guest.
| Value | # | Description |
|---|---|---|
DIAGNOSE_EFFECTS_UNSPECIFIED | 0 | Not set. Same as DIAGNOSE_EFFECTS_NONE. |
DIAGNOSE_EFFECTS_NONE | 1 | Read-only checks. Input, window and fixture checks are skipped. |
DIAGNOSE_EFFECTS_VIRTUAL_ONLY | 2 | Effectful checks run, but only against fixture windows the doctor itself launched on the guest's virtual display. Refused on bare hosts. |
CheckStatus#
Outcome of one check.
| Value | # | Description |
|---|---|---|
CHECK_STATUS_UNSPECIFIED | 0 | Not reported. |
CHECK_STATUS_PASS | 1 | Works as claimed. |
CHECK_STATUS_WARN | 2 | Works with a caveat, or something unclaimed is off. |
CHECK_STATUS_FAIL | 3 | Broken. |
CHECK_STATUS_SKIP | 4 | Not run; message says why. |
CheckSeverity#
How much a check matters for this image, derived from the manifest.
| Value | # | Description |
|---|---|---|
CHECK_SEVERITY_UNSPECIFIED | 0 | Not reported. |
CHECK_SEVERITY_REQUIRED | 1 | The image claims it: a failure fails the report. |
CHECK_SEVERITY_RECOMMENDED | 2 | Optional in the manifest: a failure is reported as a warning. |
CHECK_SEVERITY_INFO | 3 | Not claimed: a failure is reported as a warning. |
Types in cua/env/v1/common.proto#
Point#
A point in a two-dimensional coordinate space. Which space is always stated
by the enclosing message (see CoordinateSpace).
| Field | # | Type | Description |
|---|---|---|---|
x | 1 | double | Horizontal coordinate, growing to the right. |
y | 2 | double | Vertical coordinate, growing downward. |
Rect#
An axis-aligned rectangle in a coordinate space stated by the enclosing message.
| Field | # | Type | Description |
|---|---|---|---|
x | 1 | double | Left edge. |
y | 2 | double | Top edge. |
width | 3 | double | Width. Never negative. |
height | 4 | double | Height. Never negative. |
PixelSize#
A size in device (physical) pixels.
| Field | # | Type | Description |
|---|---|---|---|
width | 1 | uint32 | Width in pixels. |
height | 2 | uint32 | Height in pixels. |
WindowRef#
Opaque, server-issued reference to a window.
Native window identifiers (CGWindowID, HWND, X11 Window, portal tokens) are
never exposed. id stays stable for the life of the native window. epoch
changes whenever the server recycles an id or the window's identity is no
longer trustworthy (for example, the owning process restarted). A request
with a stale epoch fails with FAILED_PRECONDITION and
ERROR_REASON_STALE_HANDLE.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Opaque window identifier. Compare only for equality. |
epoch | 2 | uint64 | Identity generation of id. |
Display#
A display (monitor) attached to the guest desktop.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Opaque, stable display identifier. The alias "primary" is accepted wherever a display id is expected. |
name | 2 | string | Human-readable name, for example "Built-in Retina Display" or "XVFB-0". |
primary | 3 | bool | True for the primary display. |
bounds | 4 | Rect | Display bounds in global logical points (COORDINATE_SPACE_SCREEN). |
native_size | 5 | PixelSize | Size of the display's framebuffer in physical pixels. |
scale_factor | 6 | double | Physical pixels per logical point (for example 2.0 on Retina, 1.0 on most Linux framebuffers). |
refresh_rate_hz | 7 | uint32 | Nominal refresh rate in hertz, 0 when unknown (for example Xvfb). |
rotation_degrees | 8 | uint32 | Clockwise rotation in degrees: 0, 90, 180 or 270. |
DeliveryReport#
What the server actually did for an input or action request.
| Field | # | Type | Description |
|---|---|---|---|
delivery | 1 | Delivery | The delivery mode that was used. Never DELIVERY_AUTO or unspecified. |
focus_changed | 2 | bool | True if the focused window or frontmost app changed as a result. |
pointer_moved | 3 | bool | True if the user-visible pointer moved as a result. |
detail | 4 | string | Free-form, human-readable note (for example which platform path was used). Not for programmatic use. |
Principal#
Who is making a call. Sent as serialized bytes in the x-cua-principal-bin
metadata entry.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Stable identifier chosen by the client (for example a user id or an agent run id). |
display_name | 2 | string | Name shown to other participants. |
color | 3 | string | Preferred cursor color as #RRGGBB. The server may substitute a different color to keep participants distinguishable. |
kind | 4 | PrincipalKind | Whether the principal is a human or an automated agent. |
ErrorInfo#
Machine-readable error detail, packed as google.protobuf.Any inside the
google.rpc.Status in the grpc-status-details-bin trailer.
| Field | # | Type | Description |
|---|---|---|---|
reason | 1 | ErrorReason | The specific reason. More precise than the gRPC status code. |
message | 2 | string | Human-readable description. Not for programmatic use. |
feature | 3 | string | Capability feature name involved, when reason is ERROR_REASON_FEATURE_UNSUPPORTED (for example "a11y"). |
metadata | 4 | map of string to string | Structured context. Well-known keys: "expected_sequence", "expected_offset", "path", "pid", "tag", "retry_after_ms". |
KeepAlive#
Periodic empty message sent on long-lived server streams so proxies (gateways, load balancers) do not time out an idle stream. Clients ignore it apart from resetting their own liveness timers.
No fields.
CoordinateSpace#
The coordinate space a Point or Rect is expressed in.
| Value | # | Description |
|---|---|---|
COORDINATE_SPACE_UNSPECIFIED | 0 | Not set. Servers treat it as COORDINATE_SPACE_SCREEN. |
COORDINATE_SPACE_SCREEN | 1 | Global desktop space in logical points, origin at the top-left of the primary display. This is the space Display.bounds uses. |
COORDINATE_SPACE_WINDOW | 2 | Logical points relative to the top-left corner of the target window's frame. Requires a target window on the request. |
COORDINATE_SPACE_SCREENSHOT | 3 | Pixels of a screenshot previously returned by ComputerService.Screenshot, identified by screenshot_id on the request. The server performs the one conversion to native coordinates and fails with ERROR_REASON_STALE_GEOMETRY if the display or window geometry changed since the screenshot was taken. |
COORDINATE_SPACE_NORMALIZED | 4 | Normalized coordinates in [0, 1] relative to the target window, or the target display when no window is given. |
Delivery#
How synthetic input or an action is delivered to the guest.
| Value | # | Description |
|---|---|---|
DELIVERY_UNSPECIFIED | 0 | Not set. Servers treat it as DELIVERY_AUTO. |
DELIVERY_AUTO | 1 | Prefer background delivery and fall back to foreground delivery when the platform or target cannot receive background input. |
DELIVERY_BACKGROUND | 2 | Deliver without moving the user-visible pointer, changing the focused window or activating the target app. Fails with ERROR_REASON_WOULD_REQUIRE_ACTIVATION rather than falling back. |
DELIVERY_FOREGROUND | 3 | Activate the target (if any) and deliver through the global input stream, moving the real pointer and focus. |
PrincipalKind#
Kind of principal behind a call.
| Value | # | Description |
|---|---|---|
PRINCIPAL_KIND_UNSPECIFIED | 0 | Not set. Servers treat it as PRINCIPAL_KIND_HUMAN. |
PRINCIPAL_KIND_HUMAN | 1 | A person driving a client UI. |
PRINCIPAL_KIND_AGENT | 2 | An automated agent. |
ErrorReason#
Machine-readable error reasons shared by every service.
| Value | # | Description |
|---|---|---|
ERROR_REASON_UNSPECIFIED | 0 | Not set. |
ERROR_REASON_UNAUTHENTICATED | 1 | Missing or wrong bearer token, or an expired ticket. |
ERROR_REASON_FEATURE_UNSUPPORTED | 2 | The operation needs a feature the guest does not support. See ErrorInfo.feature and SystemService.GetCapabilities. |
ERROR_REASON_PERMISSION_DENIED | 3 | The guest OS denied permission (for example macOS TCC, UAC, AT-SPI disabled). |
ERROR_REASON_STALE_HANDLE | 4 | A WindowRef epoch no longer matches. |
ERROR_REASON_STALE_GEOMETRY | 5 | Geometry changed since the referenced screenshot or media frame. |
ERROR_REASON_STALE_SNAPSHOT | 6 | An accessibility element's snapshot is no longer current. |
ERROR_REASON_WOULD_REQUIRE_ACTIVATION | 7 | DELIVERY_BACKGROUND was requested but only foreground delivery could reach the target. |
ERROR_REASON_TARGET_UNAVAILABLE | 8 | The target window, app, display or element is gone. |
ERROR_REASON_DELIVERY_FAILED | 9 | The platform accepted the request but native delivery failed. |
ERROR_REASON_PROCESS_NOT_FOUND | 10 | No process matches the given pid or tag. |
ERROR_REASON_PATH_NOT_FOUND | 11 | The path does not exist. |
ERROR_REASON_PATH_EXISTS | 12 | The path already exists and overwrite was not requested. |
ERROR_REASON_NOT_A_DIRECTORY | 13 | A directory was required. |
ERROR_REASON_IS_A_DIRECTORY | 14 | A regular file was required. |
ERROR_REASON_DISK_FULL | 15 | The guest disk is full (HTTP 507 on the /files route). |
ERROR_REASON_CHECKSUM_MISMATCH | 16 | Received content does not match the declared SHA-256. |
ERROR_REASON_SESSION_NOT_FOUND | 17 | Unknown or expired upload, transfer, watcher, media session or forward. |
ERROR_REASON_OFFSET_MISMATCH | 18 | A chunk arrived at the wrong offset. metadata["expected_offset"] holds the offset the server expects next. |
ERROR_REASON_SEQUENCE_GAP | 19 | A sequenced input chunk skipped ahead. metadata["expected_sequence"] holds the sequence the server expects next. |
ERROR_REASON_RATE_LIMITED | 20 | Too many requests. metadata["retry_after_ms"] may hint a delay. |
ERROR_REASON_LIMIT_EXCEEDED | 21 | A request limit was exceeded (chunk size, message size, tree depth). |
ERROR_REASON_NOT_INITIALIZED | 22 | SystemService.Init has not configured a required default yet. |
ERROR_REASON_INTERNAL | 23 | An internal server error. Report a bug. |
ERROR_REASON_STALE_EPOCH | 24 | The request carries a fencing epoch lower than the Space's current epoch (ProcessService.AdvanceEpoch): a newer client has taken over, for example after the Space was restored from a checkpoint. metadata["current_epoch"] holds the current epoch. |