Skip to main content
Start the runtime’s screen, capture it, resize it, and publish a link to watch it live. Use the screen for windows, dialogs, and anything a page’s elements cannot describe. CLI and cURL examples use $RT for a desktop-small runtime (Overview).

Start the display

enable starts the display server and returns its status; calling it again returns the running display’s status unchanged, so it is safe to call first in every script. Enable the display before browser.open to get a headed browser window. The sections below assume the display is enabled.
Enable parameters resize accepts the same dpi field: 0 (default) preserves the current density, a positive value re-pins it alongside the new geometry.

Capture the screen

screenshot returns the frame as base64 PNG, JPEG, or WebP — crop with region, shrink with scale_pct/max_width/max_height, or pass wait_stable_ms to capture only after the screen stops changing. wait_stable is the standalone version: block until the screen has been pixel-quiet for stable_ms.
Screenshot parameters Screenshot returns {data, format, width, height, scale, rev, unchanged} with data base64. Feed rev back as if_rev on the next call to skip unchanged frames; use coordinate_space="screenshot" on input calls to address fitted coordinates. wait_stable returns {settled, waited_ms, rev} (waitedMs in TypeScript) — rev is the frame revision at settle.

Resize the display

resize changes the framebuffer geometry live — no disable/enable cycle. Returns the new live geometry; info reports it too.

Watch the screen live

view publishes a private watch URL for the screen. Open browser_url — it carries a fresh auth token that signs the browser in. Every view call mints a new token, so repeat calls always return a working link; each mint invalidates the previous token (viewers already connected keep their live session). rotate_token/rotateToken/--rotate-token is accepted but no longer needed. URLs expire after an hour. stop_view tears the view server down and frees its port.
fps defaults to 15 and caps at 30; quality is JPEG quality 1–100. window_id streams only that window’s pixels. The call returns 201 with the web-service record — browser_url, url, port, expires_at, and token (fresh on every call). See Web Services for how private URLs authenticate. Watch-only links. role="watch" (role: 'watch', --role watch) mints a view-only view_token — a connection holding it sees frames but can never inject input. The SDKs compose it into watch_url/watchUrl (browser_url + &vt=<view_token>); cURL appends &vt= itself. Hand the watch URL to a human observer and keep the control URL for the agent. The view server enforces vt= on the websocket upgrade — a missing or bad token is refused.

Stop the display

disable stops the display server; headed browser windows go with it. enable starts it again.

Click the right pixel

  • Display coordinates are absolute screen pixels. region uses the same space, so a point in a cropped screenshot maps back by adding the region’s x and y; for scaled or fitted shots, coordinate_space="screenshot" on input calls does the mapping for you.
  • wait_stable beats a fixed sleep: it returns as soon as the screen stops moving instead of waiting out the worst case.
  • Prefer browser actions over desktop input for web work — refs survive layout shifts where coordinates do not. Reach for the desktop when the target is outside the DOM.

Endpoints