Streams, teleport and tunnels
cua.env.v1 StreamService, PresenceService, TeleportService, TunnelService and VolumeService.
Media sessions (video and audio over the media wire, see libs/cua/proto/MEDIA.md) and presence; the receiving side of teleport (sending lives in the cua SDK), TCP port forwards, the reverse-SOCKS hotspot and the guest mount of Cua Volume. Host Spaces are on Host Spaces.
Source: libs/cua/proto/cua/env/v1/stream.proto, libs/cua/proto/cua/env/v1/presence.proto, libs/cua/proto/cua/env/v1/teleport.proto, libs/cua/proto/cua/env/v1/tunnel.proto, libs/cua/proto/cua/env/v1/volume.proto.
StreamService#
cua.env.v1.StreamService
Control plane for video streaming.
Video never travels over gRPC. This service discovers targets, negotiates
codec and limits, and mints a short-lived media ticket. The client then
opens the media plane (rcdp wire v2, see libs/cua/proto/MEDIA.md) on the
/media WebSocket of the same port, or on direct QUIC, authenticating
with the ticket. The ticket is bound to one media session and target and
is safe to put in a URL; it is not the root token.
Audio is a first-class track next to video: a media session may carry zero or one video track plus any number of downlink audio tracks (desktop mix or per-app), and optionally one uplink audio track (client microphone into a guest virtual source). All tracks share one media clock; see MEDIA.md §12.
StreamService.ListTargets#
/cua.env.v1.StreamService/ListTargets, unary: ListTargetsRequest to ListTargetsResponse.
Lists streamable targets: one desktop target per display, plus windows.
StreamService.OpenMedia#
/cua.env.v1.StreamService/OpenMedia, unary: OpenMediaRequest to OpenMediaResponse.
Creates a media session for a target and returns how to attach to it.
StreamService.SetPreferences#
/cua.env.v1.StreamService/SetPreferences, unary: SetPreferencesRequest to SetPreferencesResponse.
Changes frame rate, size or bitrate of an open media session.
StreamService.RequestKeyframe#
/cua.env.v1.StreamService/RequestKeyframe, unary: RequestKeyframeRequest to RequestKeyframeResponse.
Asks the encoder for a keyframe (IDR) on the next frame.
StreamService.CloseMedia#
/cua.env.v1.StreamService/CloseMedia, unary: CloseMediaRequest to CloseMediaResponse.
Closes a media session and revokes its ticket.
PresenceService#
cua.env.v1.PresenceService
Multi-user presence: who is looking at the guest and where their cursors
are. Agent cursors are published automatically when an agent principal
drives ComputerService or cua-driver tools.
Cursor updates are unary (UpdateCursor) so browsers on gRPC-Web can send
them; events arrive on the Join server stream.
| RPC | Request | Response | Kind |
|---|---|---|---|
Join | JoinRequest | JoinResponse | server stream |
UpdateCursor | UpdateCursorRequest | UpdateCursorResponse | unary |
Leave | LeaveRequest | LeaveResponse | unary |
PresenceService.Join#
/cua.env.v1.PresenceService/Join, server stream: JoinRequest to JoinResponse.
Joins presence and streams events until Leave or disconnect. The first
event is PresenceJoined with the caller's participant id and the
current roster.
PresenceService.UpdateCursor#
/cua.env.v1.PresenceService/UpdateCursor, unary: UpdateCursorRequest to UpdateCursorResponse.
Publishes the caller's cursor.
PresenceService.Leave#
/cua.env.v1.PresenceService/Leave, unary: LeaveRequest to LeaveResponse.
Leaves presence and ends the caller's Join stream.
TeleportService#
cua.env.v1.TeleportService
Receiving side of "teleport": moving an app session (browser profile cookies and storage, editor state) or a set of files from a user's machine into the guest.
The approval gate (biometric or explicit user consent for sensitive items) lives on the sending side, in the SDK; the guest never pulls. All uploads are unary chunks so browsers on gRPC-Web can send them.
TeleportService.GetManifest#
/cua.env.v1.TeleportService/GetManifest, unary: GetManifestRequest to GetManifestResponse.
Describes what the guest can accept for an app: whether the provider exists, whether the app is installed or running, and which bundle format version to send.
TeleportService.ImportSession#
/cua.env.v1.TeleportService/ImportSession, unary: ImportSessionRequest to ImportSessionResponse.
Uploads an rcdp-app-session bundle in offset-addressed chunks and, on
the final chunk, verifies and imports it. Resumable: resend from the
returned received_bytes.
TeleportService.BeginReceiveFiles#
/cua.env.v1.TeleportService/BeginReceiveFiles, unary: BeginReceiveFilesRequest to BeginReceiveFilesResponse.
Starts a file transfer into the guest's Downloads folder by declaring its manifest. Entries matching ignore rules are dropped here.
TeleportService.ReceiveFilesChunk#
/cua.env.v1.TeleportService/ReceiveFilesChunk, unary: ReceiveFilesChunkRequest to ReceiveFilesChunkResponse.
Uploads one chunk of one declared file.
TeleportService.CommitReceiveFiles#
/cua.env.v1.TeleportService/CommitReceiveFiles, unary: CommitReceiveFilesRequest to CommitReceiveFilesResponse.
Verifies every file's SHA-256 and publishes the transfer atomically.
TeleportService.AbortReceiveFiles#
/cua.env.v1.TeleportService/AbortReceiveFiles, unary: AbortReceiveFilesRequest to AbortReceiveFilesResponse.
Discards a transfer.
TeleportService.WipeImport#
/cua.env.v1.TeleportService/WipeImport, unary: WipeImportRequest to WipeImportResponse.
Removes what a committed import left in the guest: every file and
directory it created and every Keychain item it installed, as recorded
in the import's ledger. Guests that support it advertise the feature
"teleport.wipe". An unknown import_id is NOT_FOUND.
TunnelService#
cua.env.v1.TunnelService
Network tunnels between a client and the guest, carried over WebSocket upgrades on the spacesd port so they work through gateways, the relay and gRPC-Web-only networks.
Forward: client-to-guest TCP. Each WebSocket connection tows_pathbecomes one TCP connection to the guest port; binary frames carry the byte stream in both directions.- Hotspot: guest-to-client egress (reverse SOCKS5). A SOCKS5 listener on guest loopback relays each outbound connection over the client's WebSocket, and the client dials it from its own network. Replaces the unauthenticated rcdp-socks.
- Spawn: the guest-to-host channel of child Spaces. A listener on guest loopback relays each connection over the WebSocket of the host that runs the Space, which serves this Space's own children (create, list, delete) and nothing else. The host knows which Space a connection comes from by the WebSocket it opened, never by anything the guest says.
TunnelService.Forward#
/cua.env.v1.TunnelService/Forward, unary: ForwardRequest to ForwardResponse.
Authorizes TCP forwarding to a guest port and returns the WebSocket to connect to.
TunnelService.ListForwards#
/cua.env.v1.TunnelService/ListForwards, unary: ListForwardsRequest to ListForwardsResponse.
Lists active forwards.
TunnelService.CloseForward#
/cua.env.v1.TunnelService/CloseForward, unary: CloseForwardRequest to CloseForwardResponse.
Revokes a forward and closes its connections.
TunnelService.StartHotspot#
/cua.env.v1.TunnelService/StartHotspot, unary: StartHotspotRequest to StartHotspotResponse.
Starts the reverse-SOCKS hotspot for the calling client.
TunnelService.StopHotspot#
/cua.env.v1.TunnelService/StopHotspot, unary: StopHotspotRequest to StopHotspotResponse.
Stops the hotspot.
TunnelService.GetHotspotStatus#
/cua.env.v1.TunnelService/GetHotspotStatus, unary: GetHotspotStatusRequest to GetHotspotStatusResponse.
Reports hotspot state and counters.
TunnelService.StartExit#
/cua.env.v1.TunnelService/StartExit, unary: StartExitRequest to StartExitResponse.
Makes this Space an exit for the Spaces of its tree ("Exit through" a
Space): a SOCKS5 listener on guest loopback that connects from this
Space's own network (under this Space's network rules, which its host
enforces). It is reached only through a Forward to that loopback
port. Starting it again keeps the running exit.
TunnelService.StopExit#
/cua.env.v1.TunnelService/StopExit, unary: StopExitRequest to StopExitResponse.
Stops the exit (its connections close).
TunnelService.StartHostPorts#
/cua.env.v1.TunnelService/StartHostPorts, unary: StartHostPortsRequest to StartHostPortsResponse.
Publishes host ports on the guest's loopback: for each port, a listener
on 127.0.0.1:<port> whose connections the host that runs the Space
carries to the same port on its own loopback (the ports the Space's
localhost network setting opens, so localhost:3000 works as
written). Only that host may call it; starting it again replaces the
listeners.
TunnelService.StopHostPorts#
/cua.env.v1.TunnelService/StopHostPorts, unary: StopHostPortsRequest to StopHostPortsResponse.
Stops publishing host ports.
TunnelService.StartSpawn#
/cua.env.v1.TunnelService/StartSpawn, unary: StartSpawnRequest to StartSpawnResponse.
Starts the spawn channel and installs the Space's spawn capability. Only a caller holding the Space's own token (the host that runs it) may call it; starting it again replaces the channel and the capability.
TunnelService.StopSpawn#
/cua.env.v1.TunnelService/StopSpawn, unary: StopSpawnRequest to StopSpawnResponse.
Stops the spawn channel and removes the capability from the guest.
TunnelService.GetSpawnStatus#
/cua.env.v1.TunnelService/GetSpawnStatus, unary: GetSpawnStatusRequest to GetSpawnStatusResponse.
Reports the spawn channel's state.
TunnelService.PublishShareSlot#
/cua.env.v1.TunnelService/PublishShareSlot, unary: PublishShareSlotRequest to PublishShareSlotResponse.
Serves one public TCP share on a share slot: a port the cloud computer
publishes from this Space (CUA_SHARE_SLOTS), forwarded to a port of
this Space's own loopback only. The computer's firewall opens the slot
separately. Only the Space's owner (or its host) may call it.
TunnelService.UnpublishShareSlot#
/cua.env.v1.TunnelService/UnpublishShareSlot, unary: UnpublishShareSlotRequest to UnpublishShareSlotResponse.
Stops serving a share slot (its connections close).
TunnelService.ListShareSlots#
/cua.env.v1.TunnelService/ListShareSlots, unary: ListShareSlotsRequest to ListShareSlotsResponse.
The share slots served now, with the data each moved (the daemon's data cap and its sweep of slots no share explains).
VolumeService#
cua.env.v1.VolumeService
Cua Volume in the guest: the Space's view of the user's volume, mounted at a fixed path and served by the client (the host that runs the volume).
The client calls AttachVolume and opens the returned WebSocket
(/volume, ticket-authenticated), which it keeps open. Once it is
attached, cua-spacesd mounts the volume in the guest; the mount's traffic
travels as tunnel streams over that socket (the frame format of the
hotspot, OPEN carrying the target nfs or fs), and the client
answers them from its own copy of the volume, scoped to this Space. The
guest never holds storage keys and never has a network path to the
client. The mount goes away when the socket closes or on
DetachVolume.
| Guest | Backend | Mount path |
|---|---|---|
| macOS | nfs: the system NFS client | ~/Cua Volume |
| Linux | fs: FUSE (the file operations protocol) | /volume, else ~/Cua Volume |
| Windows | not yet: a preview (nfs, Client for NFS, on V:\) is off unless the guest sets CUA_VOLUME_WINDOWS_PREVIEW=1 |
On Windows a mount_path that is not a drive (for example
C:\Users\<user>\Cua Volume) becomes a directory symbolic link to the
drive the volume mounts on.
| RPC | Request | Response | Kind |
|---|---|---|---|
AttachVolume | AttachVolumeRequest | AttachVolumeResponse | unary |
DetachVolume | DetachVolumeRequest | DetachVolumeResponse | unary |
GetVolumeStatus | GetVolumeStatusRequest | GetVolumeStatusResponse | unary |
VolumeService.AttachVolume#
/cua.env.v1.VolumeService/AttachVolume, unary: AttachVolumeRequest to AttachVolumeResponse.
Prepares a mount and returns the WebSocket the client attaches.
VolumeService.DetachVolume#
/cua.env.v1.VolumeService/DetachVolume, unary: DetachVolumeRequest to DetachVolumeResponse.
Unmounts and closes the socket.
VolumeService.GetVolumeStatus#
/cua.env.v1.VolumeService/GetVolumeStatus, unary: GetVolumeStatusRequest to GetVolumeStatusResponse.
Reports the mount.
Types in cua/env/v1/stream.proto#
MediaTarget#
A streamable target.
| Field | # | Type | Description |
|---|---|---|---|
display_id | 1 | string (oneof target) | A whole display ("desktop" target), by display id or "primary". |
window | 2 | WindowRef (oneof target) | A single window. |
StreamTarget#
One entry of ListTargetsResponse.
| Field | # | Type | Description |
|---|---|---|---|
display | 1 | Display (oneof target) | A desktop target. |
window | 2 | WindowInfo (oneof target) | A window target. |
available | 3 | bool | False when the target is listed but cannot be streamed right now. |
limitation | 4 | string | Why not, when available is false (for example "screen recording permission not granted"). |
audio | 5 | AudioSource | The audio source that pairs with this target: the desktop mix for a display target, the owning app's audio for a window target (or the desktop mix, with AudioSource.limitation set, where per-app capture is unsupported). Unset when the guest has no audio capture. |
AudioSource#
A capturable audio source.
| Field | # | Type | Description |
|---|---|---|---|
source_id | 1 | string | Opaque id, stable while the source exists. "desktop" always names the desktop mix. |
kind | 2 | AudioSourceKind | What the source captures. |
name | 3 | string | Human-readable name, for example "Desktop audio" or "Firefox". |
app | 4 | AppInfo | Owning application, for AUDIO_SOURCE_KIND_APPLICATION. |
windows | 5 | repeated WindowRef | Windows of that application, for pairing with window video targets. |
available | 6 | bool | False when listed but not capturable right now. |
limitation | 7 | string | Why a source is unavailable, or degraded (for example "per-app capture needs Windows 10 2004+; falls back to desktop audio"). |
desktop_fallback | 8 | bool | True if capturing this source actually captures the desktop mix because per-app capture is unsupported. |
ListTargetsRequest#
Request for StreamService.ListTargets.
| Field | # | Type | Description |
|---|---|---|---|
include_windows | 1 | bool | Include window targets. Desktop targets are always included. |
window_filter | 2 | WindowFilter | Filter for window targets. |
ListTargetsResponse#
Response for StreamService.ListTargets.
| Field | # | Type | Description |
|---|---|---|---|
targets | 1 | repeated StreamTarget | Desktop targets first (primary display first), then windows front to back. Phantom and system windows are never listed. |
codecs | 2 | repeated MediaCodec | Codecs this driver can produce, in its preference order. |
audio_sources | 3 | repeated AudioSource | Every capturable audio source: the desktop mix first, then per-app sources. Empty when the guest has no audio capture. |
audio_codecs | 4 | repeated AudioCodec | Audio codecs this driver can produce, in its preference order. |
audio_uplink_allowed | 5 | bool | True if this caller may open an audio uplink (feature "audio.uplink" is supported and the caller's principal is allowed). |
audio_uplink_limitation | 6 | string | Why the uplink is not allowed, when it is not. |
AudioEncoding#
Audio encoding parameters shared by downlink and uplink requests. Zero and unset values select the defaults noted per field.
| Field | # | Type | Description |
|---|---|---|---|
codecs | 1 | repeated AudioCodec | Acceptable codecs in preference order. Empty means Opus, then PCM. |
sample_rate_hz | 2 | uint32 | Sample rate in Hz. 0 means 48000. Opus accepts 8000, 12000, 16000, 24000 and 48000. |
channels | 3 | uint32 | Channel count, 1 or 2. 0 means 2 (downlink) or 1 (uplink). |
bitrate_kbps | 4 | uint32 | Opus target bitrate in kbps (6 to 510). 0 means 64 for stereo, 32 for mono. Ignored for PCM. |
fec | 5 | optional bool | Opus in-band forward error correction. Unset means on. |
dtx | 6 | optional bool | Opus discontinuous transmission (send almost nothing during silence). Unset means on. |
frame_ms | 7 | uint32 | Frame duration in milliseconds: 10, 20, 40 or 60. 0 means 20. Shorter frames lower latency at a higher packet rate. |
expected_loss_percent | 8 | uint32 | Expected packet loss in percent (0 to 100), tuning the Opus FEC redundancy. 0 means 10 when fec is on. |
AudioOptions#
Audio options for OpenMediaRequest.
| Field | # | Type | Description |
|---|---|---|---|
enabled | 1 | bool | Enable downlink audio. When false, no audio tracks are sent and the other fields except uplink are ignored. |
source_ids | 2 | repeated string | Sources to send, one track each, by AudioSource.source_id. Empty means the source that pairs with the video target (StreamTarget.audio). |
encoding | 3 | AudioEncoding | Downlink encoding. |
uplink | 4 | AudioUplinkOptions | Optional microphone uplink. |
AudioUplinkOptions#
Client-to-guest audio (for example the user's microphone), played into a guest virtual audio source so apps inside can "hear" the user.
Off by default and gated separately from video and input: it requires the
"audio.uplink" feature, a session policy other than
SESSION_POLICY_VIEW_ONLY, and the caller's principal to be allowed by
InitRequest.audio_uplink. A denied uplink does not fail OpenMedia; the
response reports why in AudioUplinkGrant.
| Field | # | Type | Description |
|---|---|---|---|
enabled | 1 | bool | Request an uplink track. |
encoding | 2 | AudioEncoding | Encoding the client will send. |
virtual_source_name | 3 | string | Name of the guest virtual source (microphone) to create or reuse. Empty means "cua-uplink". |
set_default_input | 4 | bool | Make the virtual source the guest's default input device while the uplink is active. |
OpenMediaRequest#
Request for StreamService.OpenMedia.
| Field | # | Type | Description |
|---|---|---|---|
target | 1 | MediaTarget | What to stream. |
codecs | 2 | repeated MediaCodec | Acceptable codecs in client preference order. Empty means any. |
max_fps | 3 | uint32 | Maximum frames per second. 0 means 30. |
max_dimension | 4 | uint32 | Maximum long edge in pixels. 0 means native. |
bitrate_kbps | 5 | uint32 | Target H.264 bitrate in kbps (250 to 100000). 0 means encoder default. |
policy | 6 | SessionPolicy | Input policy for clients attached to this session. |
geometry_control | 7 | GeometryControl | Geometry control. |
ticket_ttl | 8 | google.protobuf.Duration | Ticket lifetime for attaching. Unset means 60 seconds; at most 10 minutes. The ticket only has to be valid when the socket attaches; an attached socket stays open past expiry. |
prefer_quic | 9 | bool | Include OpenMediaResponse.quic when direct QUIC media is available. |
audio | 10 | AudioOptions | Audio tracks. Unset means no audio (the v2.0 behavior). |
disable_video | 11 | bool | Open an audio-only session: no video track is produced. target still selects the paired audio source when audio.source_ids is empty. |
presence_participant_id | 12 | string | The viewer's presence participant, its input's owner (PRESENCE.md §7). |
AudioTrack#
One negotiated downlink audio track.
| Field | # | Type | Description |
|---|---|---|---|
track_id | 1 | uint32 | Track id carried in every audio packet header (MEDIA.md §12). Unique within the media session; never 0. |
source | 2 | AudioSource | The source it captures. |
NegotiatedAudioEncoding#
Negotiated audio encoding.
| Field | # | Type | Description |
|---|---|---|---|
codec | 1 | AudioCodec | Selected codec. |
sample_rate_hz | 2 | uint32 | Sample rate in Hz. |
channels | 3 | uint32 | Channel count. |
bitrate_kbps | 4 | uint32 | Target bitrate in kbps (0 for PCM). |
fec | 5 | bool | In-band FEC on. |
dtx | 6 | bool | DTX on. |
frame_ms | 7 | uint32 | Frame duration in milliseconds. |
AudioUplinkGrant#
Outcome of an uplink request.
| Field | # | Type | Description |
|---|---|---|---|
granted | 1 | bool | True if the uplink is open. |
denied_reason | 2 | string | Why not, when denied (for example "principal not allowed", "view_only session", "no virtual audio device"). |
track_id | 3 | uint32 | Track id the client must put in uplink packet headers. |
encoding | 4 | NegotiatedAudioEncoding | Encoding the server expects. |
virtual_source_name | 5 | string | Name of the guest virtual source the audio is played into. |
NegotiatedAudio#
Negotiated audio for a media session.
| Field | # | Type | Description |
|---|---|---|---|
tracks | 1 | repeated AudioTrack | Downlink tracks, in the order requested. |
encoding | 2 | NegotiatedAudioEncoding | Downlink encoding, shared by every downlink track. |
uplink | 3 | AudioUplinkGrant | Uplink outcome, when an uplink was requested. |
QuicEndpoint#
Direct QUIC media endpoint. Only reachable when the client can reach the guest's UDP port directly (not through a gateway or the relay).
| Field | # | Type | Description |
|---|---|---|---|
port | 1 | uint32 | UDP port (normally 3212). |
certificate_sha256 | 2 | string | Lowercase hex SHA-256 of the server's self-signed certificate (DER), to pin. |
alpn | 3 | string | ALPN protocol id, "rcdp/2". |
MediaGeometry#
Geometry of a media session's frames.
| Field | # | Type | Description |
|---|---|---|---|
frame_size | 1 | PixelSize | Frame size in pixels. |
scale | 2 | double | Frame pixels per logical point of the target. |
logical_bounds | 3 | Rect | Target bounds in global logical points when the session opened. |
geometry_epoch | 4 | uint64 | Geometry generation; matches geometry_epoch on the media plane. |
OpenMediaResponse#
Response for StreamService.OpenMedia.
| Field | # | Type | Description |
|---|---|---|---|
media_session_id | 1 | string | Media session id. |
ticket | 2 | string | Bearer ticket for the media socket. |
ticket_expires_at | 3 | google.protobuf.Timestamp | When the ticket stops being accepted for new attaches. |
ws_path | 4 | string | WebSocket path relative to the spacesd base URL, including the ticket, for example "/media?ticket=…". Works through gateways and the relay. |
quic | 5 | QuicEndpoint | Direct QUIC endpoint, when requested and available. |
codec | 6 | MediaCodec | Negotiated codec. |
max_fps | 7 | uint32 | Effective frame rate cap. |
max_dimension | 8 | uint32 | Effective long-edge cap. |
bitrate_kbps | 9 | uint32 | Effective bitrate in kbps, 0 when not applicable. |
policy | 10 | SessionPolicy | Effective policy (may be lower than requested). |
geometry_control | 11 | GeometryControl | Effective geometry control. |
geometry | 12 | MediaGeometry | Initial geometry. |
wire_version | 13 | uint32 | Media wire protocol version. 2 for this contract. |
audio | 14 | NegotiatedAudio | Negotiated audio. Unset when audio was not requested or is not available (see the "audio.*" capabilities). |
SetPreferencesRequest#
Request for StreamService.SetPreferences.
| Field | # | Type | Description |
|---|---|---|---|
media_session_id | 1 | string | Which session. |
max_fps | 2 | uint32 | New frame rate cap. 0 keeps the current value. |
max_dimension | 3 | uint32 | New long-edge cap. 0 keeps the current value. |
bitrate_kbps | 4 | uint32 | New bitrate in kbps. 0 keeps the current value. |
audio_enabled | 5 | optional bool | Pause (false) or resume (true) all downlink audio tracks. Unset keeps the current state. Paused tracks send nothing; the session keeps its track ids. |
audio_bitrate_kbps | 6 | uint32 | New Opus bitrate in kbps. 0 keeps the current value. |
audio_fec | 7 | optional bool | Turn Opus FEC on or off. Unset keeps the current value. |
audio_dtx | 8 | optional bool | Turn Opus DTX on or off. Unset keeps the current value. |
audio_frame_ms | 9 | uint32 | New frame duration in milliseconds (10, 20, 40 or 60). 0 keeps the current value. Takes effect with a new audio config epoch. |
audio_expected_loss_percent | 10 | optional uint32 | New expected loss percentage for FEC tuning. Unset keeps the current value. |
audio_uplink_muted | 11 | optional bool | Mute (true) or unmute (false) the uplink's virtual source. Unset keeps the current state. |
SetPreferencesResponse#
Response for StreamService.SetPreferences. When this returns, capture
has been reconfigured; frames from the old configuration may still be in
flight and are distinguished by codec_epoch on the media plane.
| Field | # | Type | Description |
|---|---|---|---|
max_fps | 1 | uint32 | Effective frame rate cap. |
max_dimension | 2 | uint32 | Effective long-edge cap. |
bitrate_kbps | 3 | uint32 | Effective bitrate in kbps. |
audio_enabled | 4 | bool | True if downlink audio is flowing (not paused). |
audio_encoding | 5 | NegotiatedAudioEncoding | Effective downlink audio encoding. Unset when the session has no audio. |
audio_uplink_muted | 6 | bool | True if the uplink's virtual source is muted. |
RequestKeyframeRequest#
Request for StreamService.RequestKeyframe.
| Field | # | Type | Description |
|---|---|---|---|
media_session_id | 1 | string | Which session. |
RequestKeyframeResponse#
Response for StreamService.RequestKeyframe.
No fields.
CloseMediaRequest#
Request for StreamService.CloseMedia.
| Field | # | Type | Description |
|---|---|---|---|
media_session_id | 1 | string | Which session. |
CloseMediaResponse#
Response for StreamService.CloseMedia.
No fields.
MediaCodec#
Video codec on the media plane.
| Value | # | Description |
|---|---|---|
MEDIA_CODEC_UNSPECIFIED | 0 | Not set. |
MEDIA_CODEC_H264 | 1 | H.264, one Annex B access unit per packet; keyframes carry SPS/PPS. |
MEDIA_CODEC_BGRA | 2 | Raw top-down BGRA, tightly packed. Loopback / debugging only. |
MEDIA_CODEC_PNG | 3 | One PNG per frame. Fallback when no encoder is available. |
SessionPolicy#
What a media session's attached clients may do to the target.
| Value | # | Description |
|---|---|---|
SESSION_POLICY_UNSPECIFIED | 0 | Not set. Treated as SESSION_POLICY_VIEW_ONLY. |
SESSION_POLICY_VIEW_ONLY | 1 | Video only; interactive input is refused. |
SESSION_POLICY_BACKGROUND_ONLY | 2 | Input allowed, but only background delivery (never activates or moves the real pointer). |
SESSION_POLICY_ALLOW_ACTIVATION | 3 | Input allowed and may activate the target. |
GeometryControl#
Whether a session may resize its target window to fit the viewer.
| Value | # | Description |
|---|---|---|
GEOMETRY_CONTROL_UNSPECIFIED | 0 | Not set. Treated as GEOMETRY_CONTROL_OBSERVE_ONLY. |
GEOMETRY_CONTROL_OBSERVE_ONLY | 1 | Never resize the target. |
GEOMETRY_CONTROL_BIDIRECTIONAL | 2 | Viewer may resize the target. Exclusive per target: a second bidirectional session fails with FAILED_PRECONDITION instead of stealing the lease. Window targets only. |
AudioCodec#
Audio codec on the media plane.
| Value | # | Description |
|---|---|---|
AUDIO_CODEC_UNSPECIFIED | 0 | Not set. |
AUDIO_CODEC_OPUS | 1 | Opus (RFC 6716), one Opus packet per media packet. The default. |
AUDIO_CODEC_PCM_S16LE | 2 | Raw interleaved signed 16-bit little-endian PCM. Lossless, for debugging and tests; roughly 1.5 Mbit/s for 48 kHz stereo. |
AudioSourceKind#
What an audio source captures.
| Value | # | Description |
|---|---|---|
AUDIO_SOURCE_KIND_UNSPECIFIED | 0 | Not reported. |
AUDIO_SOURCE_KIND_DESKTOP | 1 | Everything the guest plays (the default output's mix). |
AUDIO_SOURCE_KIND_APPLICATION | 2 | Audio of one application only. |
Types in cua/env/v1/presence.proto#
Participant#
A participant.
| Field | # | Type | Description |
|---|---|---|---|
participant_id | 1 | string | Server-assigned participant id, unique per Join. |
principal | 2 | Principal | Who it is. color is the server-assigned color, which may differ from the requested one. |
joined_at | 3 | google.protobuf.Timestamp | When it joined. |
CursorPosition#
Where a cursor is.
| Field | # | Type | Description |
|---|---|---|---|
display_id | 1 | string | Target the cursor is over. Unset means the primary desktop. |
window | 2 | WindowRef | Window the cursor is over, when the participant is viewing a window stream. |
position | 3 | Point | Position normalized to [0, 1] within the window (if set) or the display, so viewers at different scales agree. |
visible | 4 | bool | False hides the cursor (for example the pointer left the viewer). |
shape | 5 | CursorShape | The pointer shape the guest would show at position, computed by the server for participants that joined with JoinRequest.cursor_shapes. Ignored in UpdateCursorRequest. CURSOR_SHAPE_UNSPECIFIED (older daemons, or not probed yet) is drawn as the arrow. |
shape_source | 6 | CursorShapeSource | How shape was determined. |
JoinRequest#
Request for PresenceService.Join.
| Field | # | Type | Description |
|---|---|---|---|
principal | 1 | Principal | Who is joining. Overrides the x-cua-principal-bin metadata. |
keepalive_interval | 2 | google.protobuf.Duration | Interval between keepalive events. Unset means 30 seconds. |
cursor_shapes | 3 | bool | Asks the server to compute cursor shapes (CursorPosition.shape) and send CursorShapeChanged. Honored only when the capability "presence.cursor_shape" is supported; otherwise shapes stay unspecified. |
roster_interval | 4 | google.protobuf.Duration | Interval between RosterHeartbeat events, which list everyone present so a client can drop a participant whose leave it missed. Unset or zero means no heartbeats. Clamped to at least one second. |
cursor_batches | 5 | bool | Asks for one CursorBatch per server tick, carrying every cursor that moved in it, instead of one CursorMoved per cursor. |
cursor_datagrams | 6 | bool | Asks for a presence datagram channel (PresenceJoined.datagrams): cursors as unreliable, latest-wins QUIC datagrams in both directions, with this stream kept for everything else. Ignored when the server has no QUIC listener; the stream then carries cursors as before. |
PresenceJoined#
First event of a Join stream.
| Field | # | Type | Description |
|---|---|---|---|
participant | 1 | Participant | The caller. |
roster | 2 | repeated ParticipantCursor | Everyone else currently present, with their last known cursors. |
datagrams | 3 | PresenceDatagrams | The presence datagram channel, when requested and available. See libs/cua/proto/PRESENCE.md. |
PresenceDatagrams#
Where and how to open the presence datagram channel.
| Field | # | Type | Description |
|---|---|---|---|
endpoint | 1 | QuicEndpoint | The QUIC listener (normally UDP 3212); alpn is "cua-presence/1". |
ticket | 2 | string | Single-use credential binding the QUIC connection to this participant. |
tick | 3 | google.protobuf.Duration | Server cursor tick on the channel (normally 33 ms). |
ParticipantCursor#
A participant and their cursor.
| Field | # | Type | Description |
|---|---|---|---|
participant | 1 | Participant | The participant. |
cursor | 2 | CursorPosition | Their last cursor, unset if never published. |
ParticipantLeft#
A participant left.
| Field | # | Type | Description |
|---|---|---|---|
participant_id | 1 | string | Their participant id. |
reason | 2 | LeaveReason | Why. |
RosterHeartbeat#
Everyone present, sent every JoinRequest.roster_interval. A participant
missing from it has left.
| Field | # | Type | Description |
|---|---|---|---|
participant_ids | 1 | repeated string | Participant ids present, the recipient included. |
at | 2 | google.protobuf.Timestamp | When the server sent it. |
CursorBatch#
Every cursor that moved in one server tick.
| Field | # | Type | Description |
|---|---|---|---|
moves | 1 | repeated CursorMoved | The moves, at most one per participant. |
tick | 2 | uint64 | Server tick number. Ticks are the server's cursor interval apart; a gap means ticks without moves. |
at | 3 | google.protobuf.Timestamp | When the server sent it. |
CursorMoved#
A participant's cursor moved.
| Field | # | Type | Description |
|---|---|---|---|
participant_id | 1 | string | Whose cursor. |
cursor | 2 | CursorPosition | New position. |
at | 3 | google.protobuf.Timestamp | When the server received it. |
CursorShapeChanged#
A participant's cursor shape changed. Sent to every subscriber that asked for shapes, including the participant itself, so each client can draw its own cursor with the guest's shape.
| Field | # | Type | Description |
|---|---|---|---|
participant_id | 1 | string | Whose cursor. |
shape | 2 | CursorShape | New shape. |
source | 3 | CursorShapeSource | How it was determined. |
at | 4 | google.protobuf.Timestamp | When the server determined it. |
JoinResponse#
One message of the PresenceService.Join stream.
| Field | # | Type | Description |
|---|---|---|---|
joined | 1 | PresenceJoined (oneof event) | First event. |
participant_joined | 2 | Participant (oneof event) | Someone joined. |
participant_left | 3 | ParticipantLeft (oneof event) | Someone left. |
cursor_moved | 4 | CursorMoved (oneof event) | Someone's cursor moved. Coalesced to at most 30 per second per participant. |
keepalive | 5 | KeepAlive (oneof event) | Idle stream heartbeat. |
cursor_shape_changed | 6 | CursorShapeChanged (oneof event) | Someone's cursor shape changed (only with JoinRequest.cursor_shapes). |
roster_heartbeat | 7 | RosterHeartbeat (oneof event) | Everyone present (only with JoinRequest.roster_interval). |
cursor_batch | 8 | CursorBatch (oneof event) | Cursors that moved in one tick (only with JoinRequest.cursor_batches). |
UpdateCursorRequest#
Request for PresenceService.UpdateCursor.
| Field | # | Type | Description |
|---|---|---|---|
participant_id | 1 | string | The caller's participant id from PresenceJoined.participant. |
cursor | 2 | CursorPosition | New position. |
UpdateCursorResponse#
Response for PresenceService.UpdateCursor.
No fields.
LeaveRequest#
Request for PresenceService.Leave.
| Field | # | Type | Description |
|---|---|---|---|
participant_id | 1 | string | The caller's participant id. |
LeaveResponse#
Response for PresenceService.Leave.
No fields.
CursorShape#
A pointer shape, in a small portable vocabulary. Clients draw their own art for each value in the participant's color.
| Value | # | Description |
|---|---|---|
CURSOR_SHAPE_UNSPECIFIED | 0 | Unknown or not probed. Draw the arrow. |
CURSOR_SHAPE_ARROW | 1 | The ordinary arrow. |
CURSOR_SHAPE_TEXT | 2 | Text insertion (I-beam). |
CURSOR_SHAPE_POINTER | 3 | A link or other clickable control (pointing hand). |
CURSOR_SHAPE_RESIZE_NS | 4 | Resize along the vertical axis (top or bottom edge). |
CURSOR_SHAPE_RESIZE_EW | 5 | Resize along the horizontal axis (left or right edge). |
CURSOR_SHAPE_RESIZE_NESW | 6 | Resize along the rising diagonal (top-right or bottom-left corner). |
CURSOR_SHAPE_RESIZE_NWSE | 7 | Resize along the falling diagonal (top-left or bottom-right corner). |
CURSOR_SHAPE_WAIT | 8 | Busy; input is not accepted. |
CURSOR_SHAPE_PROGRESS | 9 | Working in the background; input is still accepted. |
CURSOR_SHAPE_NOT_ALLOWED | 10 | The action is not permitted here. |
CURSOR_SHAPE_CROSSHAIR | 11 | Precise selection. |
CURSOR_SHAPE_GRAB | 12 | Open hand over something draggable. |
CURSOR_SHAPE_GRABBING | 13 | Closed hand while dragging. |
CURSOR_SHAPE_MOVE | 14 | Move in any direction. |
CursorShapeSource#
How a cursor shape was determined.
| Value | # | Description |
|---|---|---|
CURSOR_SHAPE_SOURCE_UNSPECIFIED | 0 | Not reported. |
CURSOR_SHAPE_SOURCE_HIT_TEST | 1 | Accessibility hit-test at the participant's position (role of the element under the point, window edges). Never moves the guest pointer. |
CURSOR_SHAPE_SOURCE_SYSTEM | 2 | The guest's real cursor, read while this participant's input is what positioned the pointer. |
CURSOR_SHAPE_SOURCE_PROBE | 3 | The guest's real cursor, read by briefly moving the idle pointer to the participant's position and restoring it (see PresenceSettings). |
LeaveReason#
Why a participant left.
| Value | # | Description |
|---|---|---|
LEAVE_REASON_UNSPECIFIED | 0 | Not reported. |
LEAVE_REASON_LEFT | 1 | It called Leave. |
LEAVE_REASON_DISCONNECTED | 2 | Its Join stream ended. |
LEAVE_REASON_TIMEOUT | 3 | No activity within the server's timeout (agents without a stream). |
LEAVE_REASON_RUN_ENDED | 4 | The agent run or driver session that owned the cursor ended. |
Types in cua/env/v1/teleport.proto#
GetManifestRequest#
Request for TeleportService.GetManifest.
| Field | # | Type | Description |
|---|---|---|---|
app | 1 | string | Provider / app id, for example "firefox", "chromium", "chrome", "vscode". Advertised as capability "teleport.<app>". |
scope | 2 | TeleportScope | Requested scope. |
GetManifestResponse#
Response for TeleportService.GetManifest.
| Field | # | Type | Description |
|---|---|---|---|
supported | 1 | bool | True if the guest has a provider for this app. |
limitation | 2 | string | Why not, when unsupported. |
app_installed | 3 | bool | True if the app is installed in the guest. |
app_running | 4 | bool | True if the app is running. Importing may require closing it. |
bundle_version | 5 | uint32 | Bundle format version the sender must produce. |
scopes | 6 | repeated TeleportScope | Scopes this provider can import. |
supported_apps | 7 | repeated string | Every app id the guest can import, for discovery. |
ImportOptions#
Options applied when an imported session is committed.
| Field | # | Type | Description |
|---|---|---|---|
replace_existing | 1 | bool | Replace existing state instead of merging. |
close_running_app | 2 | bool | Close the app (gracefully, then forcefully after 5 seconds) if it is running. |
launch_after | 3 | bool | Launch the app after importing. |
expires_at_ms | 4 | uint64 | Unix time in milliseconds at which the guest wipes the import on its own, as WipeImport would. 0 means no expiry. Checked every 60 seconds and when the guest daemon starts, so an expiry survives restarts. |
broker_grant | 5 | string | Set by the Cua Keyvault broker when it delivers a session it authorized (a consent grant, an unattended rule or a first-party approval), to keyvault; empty for a direct SDK send. Not a secret and not verified by the guest. cua-spacesd counts deliveries with and without it (present or absent) in its opt-in aggregate telemetry; nothing else reads it. |
ImportSessionRequest#
Request for TeleportService.ImportSession.
| Field | # | Type | Description |
|---|---|---|---|
import_id | 1 | string | Client-chosen import id, stable across retries. The first chunk (offset 0) creates the import. |
app | 2 | string | App id as in GetManifestRequest.app. |
scope | 3 | TeleportScope | Scope of the bundle. |
offset | 4 | uint64 | Offset of data[0] in the bundle. Must equal received_bytes; a chunk wholly below it is acknowledged as a duplicate. |
data | 5 | bytes | Bundle bytes. At most Limits.max_chunk_bytes. |
commit | 6 | bool | True on the last chunk: verify and import. May carry data. |
sha256 | 7 | string | Lowercase hex SHA-256 of the whole bundle. Required when commit. |
options | 8 | ImportOptions | Import options, read when commit. |
ImportResult#
Outcome of an import, returned on the final chunk.
| Field | # | Type | Description |
|---|---|---|---|
imported | 1 | repeated string | Items imported (for example "cookies", "localStorage"). |
skipped | 2 | repeated string | Items skipped, with reasons, as "item: reason". |
launched | 3 | bool | True if the app was launched. |
ImportSessionResponse#
Response for TeleportService.ImportSession.
| Field | # | Type | Description |
|---|---|---|---|
received_bytes | 1 | uint64 | Bundle bytes received so far. |
duplicate | 2 | bool | True if the chunk was a retry and was not written again. |
result | 3 | ImportResult | Set on the final chunk once the import completed. |
TransferEntry#
One entry of a file transfer manifest.
| Field | # | Type | Description |
|---|---|---|---|
relative_path | 1 | string | Path relative to the transfer root, "/"-separated. No "..", no absolute paths. |
directory | 2 | bool | True for a directory (no content). |
size | 3 | uint64 | File size in bytes. |
sha256 | 4 | string | Lowercase hex SHA-256 of the file content. |
mode | 5 | uint32 | Unix permission bits. 0 means 0o644 (files) or 0o755 (directories). |
modified_at | 6 | google.protobuf.Timestamp | Modification time to preserve. |
BeginReceiveFilesRequest#
Request for TeleportService.BeginReceiveFiles.
| Field | # | Type | Description |
|---|---|---|---|
transfer_id | 1 | string | Client-chosen transfer id, stable across retries. Repeating the call with the same id returns the current progress. |
destination_subdir | 2 | string | Subdirectory of the guest user's Downloads folder to place the transfer in. Empty places entries directly in Downloads. |
entries | 3 | repeated TransferEntry | All entries. Directories may be listed explicitly or implied by file paths. |
ignore_patterns | 4 | repeated string | gitignore-syntax patterns applied relative to the transfer root. |
honor_gitignore | 5 | bool | Also honor .gitignore files that are part of the transfer (their content must be uploaded first; the server evaluates them at commit). |
conflict_policy | 6 | ConflictPolicy | What to do with existing files. |
ttl | 7 | google.protobuf.Duration | How long partial data is kept without progress. Unset means 1 hour. |
TransferFileProgress#
Progress of one file in a transfer.
| Field | # | Type | Description |
|---|---|---|---|
index | 1 | uint32 | Index into the accepted entries. |
received_bytes | 2 | uint64 | Bytes received. |
BeginReceiveFilesResponse#
Response for TeleportService.BeginReceiveFiles.
| Field | # | Type | Description |
|---|---|---|---|
transfer_id | 1 | string | The transfer id. |
accepted | 2 | repeated TransferEntry | Entries that will be received, in the order indices refer to. |
ignored | 3 | repeated string | Relative paths dropped by ignore patterns. |
progress | 4 | repeated TransferFileProgress | Progress per accepted file, for resuming. |
max_chunk_bytes | 5 | uint32 | Largest chunk accepted. |
ReceiveFilesChunkRequest#
Request for TeleportService.ReceiveFilesChunk.
| Field | # | Type | Description |
|---|---|---|---|
transfer_id | 1 | string | Which transfer. |
index | 2 | uint32 | Index into BeginReceiveFilesResponse.accepted. |
offset | 3 | uint64 | Offset of data[0] in that file. Must equal its received bytes; a chunk wholly below is a duplicate. |
data | 4 | bytes | File bytes. At most max_chunk_bytes. |
ReceiveFilesChunkResponse#
Response for TeleportService.ReceiveFilesChunk.
| Field | # | Type | Description |
|---|---|---|---|
received_bytes | 1 | uint64 | Bytes received for that file. |
duplicate | 2 | bool | True if the chunk was a retry. |
CommitReceiveFilesRequest#
Request for TeleportService.CommitReceiveFiles.
| Field | # | Type | Description |
|---|---|---|---|
transfer_id | 1 | string | Which transfer. |
ReceivedFile#
A file placed by a committed transfer.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Final absolute guest path (after conflict renaming). |
size | 2 | uint64 | Size in bytes. |
sha256 | 3 | string | Verified lowercase hex SHA-256. |
CommitReceiveFilesResponse#
Response for TeleportService.CommitReceiveFiles.
| Field | # | Type | Description |
|---|---|---|---|
destination | 1 | string | Absolute guest path of the transfer root. |
files | 2 | repeated ReceivedFile | Files placed. |
skipped | 3 | repeated string | Relative paths skipped by CONFLICT_POLICY_SKIP or by .gitignore rules evaluated at commit. |
AbortReceiveFilesRequest#
Request for TeleportService.AbortReceiveFiles.
| Field | # | Type | Description |
|---|---|---|---|
transfer_id | 1 | string | Which transfer. |
AbortReceiveFilesResponse#
Response for TeleportService.AbortReceiveFiles.
No fields.
WipeImportRequest#
Request for TeleportService.WipeImport.
| Field | # | Type | Description |
|---|---|---|---|
import_id | 1 | string | Import to wipe, as sent in ImportSessionRequest.import_id. Ignored when all is set. |
all | 2 | bool | Wipe every ledgered import in the guest. |
WipeImportResponse#
Response for TeleportService.WipeImport.
| Field | # | Type | Description |
|---|---|---|---|
wiped_import_ids | 1 | repeated string | Import ids whose ledgers were wiped and removed. |
removed_paths | 2 | repeated string | Absolute guest paths removed (files, and directories the import created). |
keychain_items_removed | 3 | uint32 | Keychain items removed (macOS guests; 0 elsewhere). |
cookie_rows_removed | 4 | uint32 | Cookie rows deleted out of an existing Cookies database the import merged into (not itself in removed_paths: it was not the import's file to remove). |
TeleportScope#
Which part of an app's state to teleport.
| Value | # | Description |
|---|---|---|
TELEPORT_SCOPE_UNSPECIFIED | 0 | Not set. Treated as TELEPORT_SCOPE_SESSION. |
TELEPORT_SCOPE_SESSION | 1 | Sign-in state only: cookies, local storage, session storage. |
TELEPORT_SCOPE_PROFILE | 2 | The whole profile: session plus history, bookmarks, extensions, settings. |
ConflictPolicy#
What to do when a received file already exists.
| Value | # | Description |
|---|---|---|
CONFLICT_POLICY_UNSPECIFIED | 0 | Not set. Treated as CONFLICT_POLICY_RENAME. |
CONFLICT_POLICY_RENAME | 1 | Keep both: the new file becomes "name (1).ext". |
CONFLICT_POLICY_OVERWRITE | 2 | Replace the existing file. |
CONFLICT_POLICY_SKIP | 3 | Keep the existing file and drop the new one. |
Types in cua/env/v1/tunnel.proto#
PublishShareSlotRequest#
Request for TunnelService.PublishShareSlot.
| Field | # | Type | Description |
|---|---|---|---|
slot | 1 | uint32 | The slot (one of CUA_SHARE_SLOTS). |
port | 2 | uint32 | The Space port it reaches (on 127.0.0.1). |
allow | 3 | repeated string | Who may connect (CIDRs); empty: anyone. |
expect_hosts | 4 | repeated string | Minecraft Java: drop connections whose handshake names none of these hosts. Empty: no check. |
ttl | 5 | google.protobuf.Duration | How long it serves. Unset: 24 hours, the most. |
max_bytes | 6 | uint64 | The most bytes it may move (both ways); 0: no cap. Reaching it ends every connection and refuses new ones. |
PublishShareSlotResponse#
Response for TunnelService.PublishShareSlot.
| Field | # | Type | Description |
|---|---|---|---|
slot | 1 | uint32 | The slot. |
expires_at | 2 | google.protobuf.Timestamp | When it stops. |
UnpublishShareSlotRequest#
Request for TunnelService.UnpublishShareSlot.
| Field | # | Type | Description |
|---|---|---|---|
slot | 1 | uint32 | The slot. |
UnpublishShareSlotResponse#
Response for TunnelService.UnpublishShareSlot.
No fields.
ListShareSlotsRequest#
Request for TunnelService.ListShareSlots.
No fields.
ShareSlot#
One served share slot.
| Field | # | Type | Description |
|---|---|---|---|
slot | 1 | uint32 | The slot. |
port | 2 | uint32 | The Space port it reaches. |
bytes | 3 | uint64 | Bytes moved since it was published. |
max_bytes | 4 | uint64 | Its data cap (0: none). |
connections | 5 | uint32 | Open connections. |
expires_at | 6 | google.protobuf.Timestamp | When it stops. |
ListShareSlotsResponse#
Response for TunnelService.ListShareSlots.
| Field | # | Type | Description |
|---|---|---|---|
slots | 1 | repeated ShareSlot | The slots, with what each moved. |
ForwardRequest#
Request for TunnelService.Forward.
| Field | # | Type | Description |
|---|---|---|---|
port | 1 | uint32 | Guest TCP port to reach. |
host | 2 | string | Guest host to connect to. Empty means "127.0.0.1". Only loopback and the guest's own addresses are allowed. |
ttl | 3 | google.protobuf.Duration | How long the ticket accepts new connections. Unset means 10 minutes; at most 24 hours. Open connections survive expiry. |
ForwardResponse#
Response for TunnelService.Forward.
| Field | # | Type | Description |
|---|---|---|---|
forward_id | 1 | string | Forward id. |
ticket | 2 | string | Ticket accepted by the tunnel WebSocket. Reusable for many connections until expiry. |
ws_path | 3 | string | WebSocket path relative to the spacesd base URL, including the ticket, for example "/tunnel?ticket=…". |
expires_at | 4 | google.protobuf.Timestamp | When the ticket expires. |
ForwardInfo#
An active forward.
| Field | # | Type | Description |
|---|---|---|---|
forward_id | 1 | string | Forward id. |
host | 2 | string | Guest host. |
port | 3 | uint32 | Guest port. |
active_connections | 4 | uint32 | Open connections. |
bytes_in | 5 | uint64 | Bytes sent to the guest port. |
bytes_out | 6 | uint64 | Bytes received from the guest port. |
expires_at | 7 | google.protobuf.Timestamp | Ticket expiry. |
ListForwardsRequest#
Request for TunnelService.ListForwards.
No fields.
ListForwardsResponse#
Response for TunnelService.ListForwards.
| Field | # | Type | Description |
|---|---|---|---|
forwards | 1 | repeated ForwardInfo | Active forwards. |
CloseForwardRequest#
Request for TunnelService.CloseForward.
| Field | # | Type | Description |
|---|---|---|---|
forward_id | 1 | string | Which forward. |
CloseForwardResponse#
Response for TunnelService.CloseForward.
No fields.
StartHotspotRequest#
Request for TunnelService.StartHotspot.
| Field | # | Type | Description |
|---|---|---|---|
socks_port | 1 | uint32 | Guest loopback port for the SOCKS5 listener. 0 means 1080. |
set_system_proxy | 2 | bool | Point the guest's system proxy settings (and HTTP(S)_PROXY for new processes) at the hotspot. |
bypass | 3 | repeated string | Destinations (CIDRs or host suffixes) that bypass the hotspot and use the guest's own network. |
ticket_ttl | 4 | google.protobuf.Duration | How long the ticket accepts the client's WebSocket. Unset means 60 seconds. |
StartHotspotResponse#
Response for TunnelService.StartHotspot.
| Field | # | Type | Description |
|---|---|---|---|
hotspot_id | 1 | string | Hotspot id. |
ticket | 2 | string | Ticket for the hotspot WebSocket. |
ws_path | 3 | string | WebSocket path relative to the spacesd base URL, including the ticket, for example "/hotspot?ticket=…". The client keeps this socket open; the hotspot stops when it closes. |
socks_address | 4 | string | Guest-side SOCKS5 address, for example "127.0.0.1:1080". |
StartExitRequest#
Request for TunnelService.StartExit.
| Field | # | Type | Description |
|---|---|---|---|
socks_port | 1 | uint32 | Guest loopback port; 0 picks a free one. |
StartExitResponse#
Response for TunnelService.StartExit.
| Field | # | Type | Description |
|---|---|---|---|
socks_address | 1 | string | Where the exit listens on guest loopback ("127.0.0.1:41081"). |
StartHostPortsRequest#
Request for TunnelService.StartHostPorts.
| Field | # | Type | Description |
|---|---|---|---|
ports | 1 | repeated uint32 | Host ports to publish on the guest's loopback, at the same numbers. |
ticket_ttl | 2 | google.protobuf.Duration | How long the ticket accepts the host's WebSocket. Unset: 60 s. |
HostPortSkipped#
A host port the guest could not publish.
| Field | # | Type | Description |
|---|---|---|---|
port | 1 | uint32 | The host port. |
reason | 2 | string | Why, in plain words ("something in the Space listens there"). |
StartHostPortsResponse#
Response for TunnelService.StartHostPorts.
| Field | # | Type | Description |
|---|---|---|---|
session_id | 1 | string | The session to stop later. |
ticket | 2 | string | One-time ticket for the host's WebSocket. |
ws_path | 3 | string | WebSocket path relative to the spacesd base URL, with the ticket. |
listening | 4 | repeated uint32 | The ports listening on the guest's loopback now. |
skipped | 5 | repeated HostPortSkipped | The ports it could not take. |
StopHostPortsRequest#
Request for TunnelService.StopHostPorts.
No fields.
StopHostPortsResponse#
Response for TunnelService.StopHostPorts.
No fields.
StopExitRequest#
Request for TunnelService.StopExit.
No fields.
StopExitResponse#
Response for TunnelService.StopExit.
No fields.
StopHotspotRequest#
Request for TunnelService.StopHotspot.
| Field | # | Type | Description |
|---|---|---|---|
hotspot_id | 1 | string | Which hotspot. |
StopHotspotResponse#
Response for TunnelService.StopHotspot.
No fields.
GetHotspotStatusRequest#
Request for TunnelService.GetHotspotStatus.
No fields.
GetHotspotStatusResponse#
Response for TunnelService.GetHotspotStatus.
| Field | # | Type | Description |
|---|---|---|---|
state | 1 | HotspotState | State. |
hotspot_id | 2 | string | Hotspot id, when not stopped. |
peer_principal_id | 3 | string | Id of the principal whose client provides egress. |
socks_address | 4 | string | Guest-side SOCKS5 address. |
active_connections | 5 | uint32 | Open relayed connections. |
bytes_out | 6 | uint64 | Bytes sent from the guest through the hotspot. |
bytes_in | 7 | uint64 | Bytes received into the guest through the hotspot. |
StartSpawnRequest#
Request for TunnelService.StartSpawn.
| Field | # | Type | Description |
|---|---|---|---|
capability | 1 | string | The Space's spawn capability, minted by its host. The guest writes it to the token file (0600, owner: the user cua-spacesd runs as) for clients in the Space to present on the spawn listener. |
ticket_ttl | 2 | google.protobuf.Duration | How long the ticket accepts the host's WebSocket. Unset means 60 seconds. |
space_id | 3 | string | The Space's id, for the environment of new processes (CUA_SPACE). |
StartSpawnResponse#
Response for TunnelService.StartSpawn.
| Field | # | Type | Description |
|---|---|---|---|
spawn_id | 1 | string | Spawn channel id. |
ticket | 2 | string | Ticket for the spawn WebSocket. |
ws_path | 3 | string | WebSocket path relative to the spacesd base URL, including the ticket, for example "/spawn?ticket=…". The host keeps this socket open; the listener refuses connections while it is closed. |
address | 4 | string | Guest-side listener, as a URL clients in the Space use as their cua daemon, for example "http://127.0.0.1:41234". |
token_path | 5 | string | Where the guest wrote the capability. |
address_path | 6 | string | Where the guest wrote the listener's address (one line). |
StopSpawnRequest#
Request for TunnelService.StopSpawn.
| Field | # | Type | Description |
|---|---|---|---|
spawn_id | 1 | string | Which channel. Empty stops the current one. |
StopSpawnResponse#
Response for TunnelService.StopSpawn.
No fields.
GetSpawnStatusRequest#
Request for TunnelService.GetSpawnStatus.
No fields.
GetSpawnStatusResponse#
Response for TunnelService.GetSpawnStatus.
| Field | # | Type | Description |
|---|---|---|---|
started | 1 | bool | A channel is started. |
attached | 2 | bool | The host's WebSocket is attached. |
spawn_id | 3 | string | Channel id, when started. |
address | 4 | string | Guest-side listener URL, when started. |
active_connections | 5 | uint32 | Open relayed connections. |
HotspotState#
Hotspot state.
| Value | # | Description |
|---|---|---|
HOTSPOT_STATE_UNSPECIFIED | 0 | Not reported. |
HOTSPOT_STATE_STOPPED | 1 | No hotspot. |
HOTSPOT_STATE_WAITING_FOR_PEER | 2 | Started, waiting for the client WebSocket. |
HOTSPOT_STATE_ACTIVE | 3 | Relaying. |
Types in cua/env/v1/volume.proto#
AttachVolumeRequest#
Request for VolumeService.AttachVolume.
| Field | # | Type | Description |
|---|---|---|---|
mount_path | 1 | string | Where to mount. Empty means the guest's default (see the table above). |
ticket_ttl | 2 | google.protobuf.Duration | How long the ticket accepts the client's WebSocket. Unset means 60 seconds. |
binds | 3 | repeated VolumeBind | Folders of the volume to bind at other paths once it is mounted (Linux: bind mounts; macOS: symbolic links). Undone with the mount. |
VolumeMount#
A named volume mounted into a Space: the folder volumes/<name>/ of
the user's Cua Volume, bound at path in the guest.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | The volume's name: 1-63 of a-z, 0-9, ., _, -. |
path | 2 | string | Absolute path in the guest. |
read_only | 3 | bool | Mounted read-only. |
subpath | 4 | string | A folder inside the volume to mount instead of the whole volume. |
VolumeBind#
A folder of the mounted volume made available at another path.
| Field | # | Type | Description |
|---|---|---|---|
source | 1 | string | Folder inside the volume, relative to its root (volumes/shared/). |
target | 2 | string | Absolute path in the guest. Created when missing. |
read_only | 3 | bool | Mounted read-only (Linux). A link on macOS cannot enforce it; the client's view of the folder does. |
AttachVolumeResponse#
Response for VolumeService.AttachVolume.
| Field | # | Type | Description |
|---|---|---|---|
volume_id | 1 | string | Volume session id. |
ticket | 2 | string | Ticket for the volume WebSocket. |
ws_path | 3 | string | WebSocket path relative to the spacesd base URL, including the ticket, for example "/volume?ticket=…". |
mount_path | 4 | string | Where the volume will be mounted. |
backend | 5 | string | nfs or fs: the target name the guest's streams carry, which the client answers. |
DetachVolumeRequest#
Request for VolumeService.DetachVolume.
| Field | # | Type | Description |
|---|---|---|---|
volume_id | 1 | string | Which session. Empty means the current one. |
DetachVolumeResponse#
Response for VolumeService.DetachVolume.
No fields.
GetVolumeStatusRequest#
Request for VolumeService.GetVolumeStatus.
No fields.
GetVolumeStatusResponse#
Response for VolumeService.GetVolumeStatus.
| Field | # | Type | Description |
|---|---|---|---|
state | 1 | VolumeState | State. |
volume_id | 2 | string | Volume session id (empty when detached). |
mount_path | 3 | string | Mount path. |
backend | 4 | string | nfs or fs. |
detail | 5 | string | Why, when state is VOLUME_STATE_ERROR. |
active_streams | 6 | uint32 | Open streams to the client. |
bytes_out | 7 | uint64 | Bytes sent from the guest to the client. |
bytes_in | 8 | uint64 | Bytes received from the client. |
binds | 9 | repeated string | Targets of the binds that are in place. |
VolumeState#
State of the guest mount.
| Value | # | Description |
|---|---|---|
VOLUME_STATE_UNSPECIFIED | 0 | Not reported. |
VOLUME_STATE_DETACHED | 1 | No volume. |
VOLUME_STATE_WAITING_FOR_CLIENT | 2 | Attached by RPC, waiting for the client WebSocket. |
VOLUME_STATE_MOUNTING | 3 | Mounting. |
VOLUME_STATE_MOUNTED | 4 | Mounted and served. |
VOLUME_STATE_ERROR | 5 | The mount failed; see detail. |