$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.
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 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.
regionuses the same space, so a point in a cropped screenshot maps back by adding the region’sxandy; for scaled or fitted shots,coordinate_space="screenshot"on input calls does the mapping for you. wait_stablebeats 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.