Viewer UI
How L4 apps embed desktop streams — mode adapters for pods, VMs, and Mac.
Sandboxes returns a viewer descriptor; rendering belongs to an external
viewer_ui library in your application (L4). The platform does not ship the
product UI — only the signed URL, proxy, and evidence routes.
Mode adapters
viewer.mode | Adapter | Upstream protocol | Typical profile |
|---|---|---|---|
novnc | noVNC lite | RFB over WebSocket | desktop-ubuntu (pod) |
guacamole | Guacamole HTML client | Guacamole tunnel WebSocket | desktop-windows (VM) |
provider | Vendor stream adapter | Provider-specific WS/RFB | desktop-macos (external) |
Embed flow
- Create with a
desktop-*profile; poll untilstatus=running. - Read
viewer.mode,viewer.url,viewer.input_enabled,viewer.resolution. viewer_uiopens the URL (iframe or window) with the matching mode adapter.- Optionally wire evidence buttons to
/viewer/recordings,/viewer/screenshots, … (see Viewer API).
Input gating
input_enabled is false until the sandbox is running. Disable pointer and
keyboard in the UI until it flips to true.
Resolution
Use viewer.resolution to size the canvas container. Actual desktop resolution is
set by the substrate image (pod or VM).
Non-goals
- Sandboxes command-center shell (
viewer_shell) is interim/dev-only — not the product UI path. - No OSWorld-specific widgets inside the L3 service.
- No provider credentials in the browser — only the signed viewer token.