Skip to main content
A live view is a shared session, not a private feed. Every connected client — agent and humans — appears in a presence roster with a labeled cursor, a control mode decides whose input lands, and a takeover is one call away on both the desktop and the browser. CLI and cURL examples use $RT for a desktop-small runtime and $BID for a browser ID (Screen, Browser).

Who is watching

A view connection’s identity comes from its token and its URL parameters:
  • Role — the browser_url control token connects as control; a watch-role token (vt=, minted by view/view_url with role="watch") connects as watch and can never inject input.
  • name= — the label rendered next to the cursor (form-urlencoded, 32 chars max).
  • color= — the cursor’s CSS color, e.g. %23ff0055 for #ff0055 (form-urlencoded, 16 chars max).
  • agent=1 — marks the entry as an agent-side cursor.
Appended to a watch URL: &vt=<view_token>&name=Ope&color=%23ff0055. The platform agent holds the reserved entry _agent — name Agent, color #008145 — and its cursor tracks real dispatched input, not a viewer’s guess, so every watcher sees what the agent is actually pointing at.

What the socket sends

Video frames are binary; presence and control travel as JSON text frames on the same socket:
A new client gets hello first — its id, its role, and the full roster — then the replayed control mode, then live join/cursor/leave traffic. Its own input doubles as its cursor report, so watch-role cursors broadcast too.

Take over, hand back

view_control sets who may inject input. The status calls report the mode and the connected roster (control_mode, viewers) so an orchestrator can tell a human is watching without being a viewer. Take over with human, hand back with shared (or agent to lock viewers out). A rejected agent call fails immediately — it does not queue — so an agent should catch the error and retry once the mode changes back.

Same contract on the browser

The browser plane is identical: view mints a live URL for a browser’s tab, presence and takeover work the same way, and browser.status exposes control_mode/viewers. Under human, agent actions (click, type, navigate…) reject while reads (evaluate, screenshots, DOM queries) still return — a human can drive while the agent keeps observing.

Endpoints