Streams and display
Stream a Space's desktop or windows, and show a Space to the operator.
Stream a Space's desktop or windows, and show a Space to the operator.
| Tool | Description |
|---|---|
stream_endpoint | Return a ticketed media endpoint for the Space's desktop or one window. |
list_space_windows | List the windows open inside the Space. |
stream_space_window | Draw one Space window on the operator's desktop. |
show_space_pip | Pin the Space as picture-in-picture on the operator's desktop. |
hide_space_pip | Unpin the picture-in-picture window. |
open_space_viewer | Open the full Space viewer on the operator's desktop. |
Return a ticketed media endpoint for the Space's desktop or one window.
Opens a media session (StreamService.OpenMedia) for the desktop or one window and returns its ticketed WebSocket URL (rcdp wire v2, see libs/cua/proto/MEDIA.md). The ticket is short-lived, bound to that one session, and safe to put in a URL; it is not the Space's token. Works for every provider because the token comes from the SDK, not from the guest.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:stream_endpoint; mutating, idempotent |
| Requires (spacesd) | desktop_stream |
| Swift SDK | Space.streamEndpoint(forceRefresh:) |
| Rust | Streams::open |
| Parameter | Type | Default | Description |
|---|---|---|---|
app_name | string | none | Stream the largest visible window of this app (case-insensitive substring). Ignored when window_id is set. |
display | string | none | Display id for a desktop stream. Default: the primary display. |
max_fps | integer | 30 | Maximum frames per second. Default 30. At least 0. |
space | string | required | Space id or name. |
ticket_ttl | integer | 60 | Ticket lifetime in seconds (at most 600). Default 60. At least 0. |
window_id | string | none | Window handle from list_space_windows. Streams that window. |
JSON: space, media_session_id, ws_url (ticket included), ticket, ticket_expires_at, codec (h264, bgra or png), wire_version, frame_size and needs_gateway_headers.
invalid_argument, not_found, ambiguous_sandbox, spacesd_not_available, capability_missing, stream
List the windows open inside the Space.
The windows a viewer can stream now, from StreamService.ListTargets: on screen, sized, normal app windows (no hidden, minimized or system-UI windows), each with its handle, title, app and bounds.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:list_space_windows, in spaces:readonly; read-only, idempotent |
| Requires (spacesd) | windows |
| Swift SDK | Space.windows() |
| Rust | Streams::windows |
| Parameter | Type | Default | Description |
|---|---|---|---|
app_name | string | none | Only windows of this app (case-insensitive substring). |
space | string | required | Space id or name. |
JSON: an array of windows (window_id, epoch, title, app_name, app_id, pid, bounds, on_screen, focused, available, limitation).
invalid_argument, not_found, ambiguous_sandbox, spacesd_not_available, capability_missing
Draw one Space window on the operator's desktop.
FOR THE HUMAN. Opens a bidirectional window on the operator's desktop showing one Space window (the Cua Spaces app draws it from a media ticket). Pass app_name to auto-pick that app's largest visible window, or an exact window_id.
| Providers | all (cloud, local, direct, relay) |
| Platforms | macos (the operator's machine) |
| Metering | free |
| Approval | permission spaces:stream_space_window; mutating, idempotent |
| Requires (spacesd) | window_stream |
| Requires (this machine) | operator_display |
| Swift SDK | space.operatorDisplay.streamWindowToOperatorDesktop(_:) |
| Rust | OperatorDisplay::stream_window |
| Parameter | Type | Default | Description |
|---|---|---|---|
app_name | string | none | Auto-pick this app's largest visible window, e.g. "Firefox". |
space | string | required | Space id or name. |
title | string | none | Label for the operator's window. Default: the window title. |
window_id | string | none | Exact window handle from list_space_windows (overrides app_name). |
Text: Streaming <window> of <space> to your desktop (bidirectional).
invalid_argument, not_found, ambiguous_sandbox, spacesd_not_available, capability_missing, host_capability_missing, stream
Pin the Space as picture-in-picture on the operator's desktop.
FOR THE HUMAN, NOT FOR YOU. Pins an always-on-top picture-in-picture overlay of the Space onto the user's own desktop. Call it only when the user asks to see a Space; never to observe your own work.
| Providers | all (cloud, local, direct, relay) |
| Platforms | macos (the operator's machine) |
| Metering | free |
| Approval | permission spaces:show_space_pip; mutating, idempotent |
| Requires (spacesd) | desktop_stream |
| Requires (this machine) | operator_display |
| Swift SDK | space.operatorDisplay.pinPictureInPictureOnOperatorDesktop() |
| Rust | OperatorDisplay::pin_pip |
| Parameter | Type | Default | Description |
|---|---|---|---|
space | string | required | Space id or name. |
Text: Pinned <space> as picture-in-picture on your desktop.
invalid_argument, not_found, ambiguous_sandbox, spacesd_not_available, capability_missing, host_capability_missing
Unpin the picture-in-picture window.
| Providers | all (cloud, local, direct, relay) |
| Platforms | macos (the operator's machine) |
| Metering | free |
| Approval | permission spaces:hide_space_pip; mutating, idempotent |
| Requires (this machine) | operator_display |
| Swift SDK | space.operatorDisplay.unpinPictureInPictureFromOperatorDesktop() |
| Rust | OperatorDisplay::unpin_pip |
| Parameter | Type | Default | Description |
|---|---|---|---|
space | string | required | Space id or name. |
Text: Unpinned <space> from your desktop.
invalid_argument, not_found, ambiguous_sandbox, host_capability_missing
Open the full Space viewer on the operator's desktop.
FOR THE HUMAN, NOT FOR YOU. Opens a live viewer window on the user's own desktop. Never call it to obtain a screenshot or to check on your own work; use the screenshot tool for that.
| Providers | all (cloud, local, direct, relay) |
| Platforms | macos (the operator's machine) |
| Metering | free |
| Approval | permission spaces:open_space_viewer; mutating, idempotent |
| Requires (spacesd) | desktop_stream |
| Requires (this machine) | operator_display |
| Swift SDK | space.operatorDisplay.openViewerOnOperatorDesktop() |
| Rust | OperatorDisplay::open_viewer |
| Parameter | Type | Default | Description |
|---|---|---|---|
space | string | required | Space id or name. |
Text: Opened the <space> viewer on your desktop.
invalid_argument, not_found, ambiguous_sandbox, spacesd_not_available, capability_missing, host_capability_missing