Watch a computer and take control
How Watch and Take control reach a computer with nothing to set up (WebRTC straight to the daemon, even behind NAT), what the STUN server sees, when a TURN server is needed (yours or a managed one), the direct and snapshot fallbacks, the control lease, and how an agent asks for a person.
Watch and Take control (on the seat page, /computers/{id}) work with one click and nothing to set up: the daemon can be behind a home router, with no
public address and no tunnel. The picture and your clicks go from your browser to the daemon directly over WebRTC,
encrypted end to end. The cloud only passes the handshake and never carries a pixel or a key press. The console tries
three paths in this order and shows which one it is using, and why when it is not the first:
| The live view says | Path | What it needs |
|---|---|---|
| Live | a WebSocket straight to the daemon, if it advertises a public or tunnel https endpoint (direct); otherwise WebRTC, peer to peer | nothing for WebRTC |
| Live (relayed) | WebRTC through a TURN server, when the two sides cannot reach each other | your own TURN server, or a managed one (Cloudflare) |
| Snapshots every 2 s | a thumbnail through the cloud | nothing; input is not possible |
WebRTC (the default, nothing to set up)
When you open the live view the console builds a browser peer connection with two data channels and sends its offer to
the cloud. The cloud hands it to the seat's daemon on the channel the daemon already keeps open (a computer job with
op: "rtc"), the daemon answers, and the two connect:
GET /api/workspace/computers/{id}/rtc/ice the ICE servers to use
POST /api/workspace/computers/{id}/rtc/offer {"scope": "view" | "control", "offer": "<sdp>"} -> {"session", "ice_servers", ...}
GET /api/workspace/computers/{id}/rtc/{session}/answer long poll (up to 20 s): the daemon's SDP, or 202 pending
POST /api/workspace/computers/{id}/rtc/{session}/candidates {"candidates": [...]} your browser's ICE candidates
POST /api/workspace/computers/{id}/rtc/{session}/renew every 45 s
DELETE /api/workspace/computers/{id}/rtc/{session} when you leaveOn the daemon's side the session is one GET /api/mesh/v1/computers/rtc/{session}/signal long poll, which delivers your
candidates and tells it when the session is over. Signalling rows live in an unlogged table for two minutes after the
last renewal. On a normal home router the live view appears in about a second.
- The frames go on one data channel as the seat's screencast JPEGs, about 12 a second (about 60 KB each at quality 50, so roughly 6 Mbit/s while the page moves), chunked and reassembled. A frame goes out only while less than 128 KB is still on its way; otherwise it waits, and a newer frame replaces it. A slow link gets fewer frames, never older ones, so what you see (and the answer to your click) stays within about one frame's transfer time of the seat.
- When the screen stops changing for half a second the viewers get one sharp frame (a screenshot at quality 85, at most one every 3 seconds), so small text and a QR code are crisp once they hold still. A repaint that changed nothing is not sent again. A page that does not repaint is sent again every 2 seconds so a new viewer is never left with a blank screen (the console does not draw or count those repeats, so a still screen's rate reads no changes).
- Headless Chromium's screencast sends nothing for some changes (a navigation to a page that then holds still, a tab that was just shown), so while no frame comes the daemon looks at the screen once a second with a screenshot and sends it only when it differs from the last one. A viewer that connects gets a picture at once, also on a page that never moves.
- The console decodes frames off the main thread and draws only the newest one, on the next animation frame.
- Your input goes on a second, ordered data channel as the same
{"method": "Input.dispatch...", "params": {...}}messages the direct WebSocket takes. The daemon forwards it only on a control session, and the seat's own screen server refuses it again unless it was opened for control. - A seat serves at most 5 viewers at once; a sixth sees why and gets snapshots.
- A session ends, and the daemon closes the connection, when you leave, when it is not renewed for two minutes, when the seat is archived and, for control, when you no longer hold the lease (someone else took it, it ran out, or you pressed Release). The console reconnects by itself after a network blip.
- A sleeping seat is woken by Watch. One that is waiting for a slot says so and shows snapshots.
Which tab you see
A browser computer can have several tabs: the one it started with, the tabs an agent opens (an agent on a computer works in tabs of its own), and the pop-ups a page opens. The live view shows the tab the agent is acting on: the daemon watches the agent's browser commands, and when the agent opens or switches to a tab, navigates, clicks or types in one, the view moves there and sends a picture of it at once. When that tab closes, the view moves to another one.
Above the picture the view names the tab it shows (its title and site). With more than one tab it lists them all, the one
shown highlighted. While you hold control you can click another tab to see and use it; the agent's own actions then no
longer move the view until you release control. Someone only watching sees the list but cannot switch. The list carries
each tab's title and its address without the query string or fragment (a reset link's token never reaches a viewer), only
the scheme of a data: address, and at most 20 tabs. A tab of another computer is never listed: each computer has its own
browser.
This needs a daemon from the release after 0.2.17 (the computer image ships with it). With an older daemon the view stays on the tab it attached to first, which while an agent works in a tab of its own is the computer's untouched blank tab: a white screen that reads no changes. Update the daemon to fix it.
What the STUN server sees
To connect through a router, each side asks a STUN server for the address the internet sees it as. STUN sees IP
addresses and ports and nothing else: no frames, no input, no page, no account. The default is one public server,
stun:stun.cloudflare.com:3478, so there is one outbound call to a third party when a live view opens. Keep it, point it
at your own, or turn it off (below). With STUN off, two peers on the same network still connect; across the internet you
need your own STUN or TURN server.
When you need a TURN server
STUN is enough for most home and office networks. Some networks (a symmetric NAT, a strict corporate firewall that blocks
UDP) cannot be traversed that way; the live view then falls back to snapshots with the note "A direct connection to the
daemon could not be made". A TURN server relays the (still encrypted) packets and fixes that; the view then reads
Live (relayed). Mobile data is the common case: most carriers put phones behind a symmetric NAT. Two ways to get one:
run coturn with use-auth-secret and static-auth-secret=<secret> and give the cloud
the same secret, or use a managed TURN service (below), with nothing to run.
Managed TURN (Cloudflare Realtime TURN)
- In the Cloudflare dashboard, open Realtime → TURN Server and create a TURN key. Copy its id (Turn Token ID) and its API Token: the token is a long-term secret, so keep it out of chat and tickets.
- Set
VENOM_RTC_CF_TURN_KEY_IDto the token id andVENOM_RTC_CF_TURN_TOKENto the API token in the cloud's environment (Vercel → Project → Settings → Environment Variables, Production; or the self-hosted.env). - Redeploy, so the new variables are read.
- Check it from a phone on mobile data, with Wi-Fi off: open a running computer and press Watch. The view should read Live (relayed), not Snapshots every 2 s.
Each time the cloud hands out ICE servers (to your browser when a live view opens, and to the daemon with the offer), it
asks Cloudflare for a fresh credential (generate credentials),
good for VENOM_RTC_TURN_TTL_S. The API token stays in the cloud; the browser and the daemon only get the generated
username and credential. The cloud waits at most 2 seconds for Cloudflare and does not retry: if Cloudflare is slow or
refuses, the live view opens with the other servers and the cloud logs a warning without the token or the credential.
URLs on port 53, which browsers block, are dropped, and so is Cloudflare's own STUN entry (VENOM_RTC_ICE_SERVERS still
decides STUN).
What Cloudflare sees: the IP addresses and ports of your browser and of the daemon, when and for how long they talk, and the volume. The stream itself is DTLS-encrypted between the browser and the daemon, so the relay carries packets it cannot read: no frames, no input. Only relayed views use it (a direct or STUN path costs nothing), and Cloudflare bills the data it sends to TURN clients: as of November 2026, the first 1,000 GB a month free, then $0.05 per GB (pricing). A live view is 0.3 to 1.5 Mbit/s.
With both variables unset, nothing changes and the cloud never calls Cloudflare's API. A self-hosted cloud is not affected
unless you set them. With both coturn (VENOM_RTC_TURN_URLS + VENOM_RTC_TURN_SECRET) and Cloudflare configured, the
peers get both TURN servers: ICE tries each and keeps a pair that works, so either one being down leaves the other.
How long a TURN credential lasts
A TURN server checks the credential again each time the browser or the daemon refreshes its relay, every few minutes, and
drops the relay once the credential has expired. A live view has no time limit, so the default credential lasts 12 hours
(VENOM_RTC_TURN_TTL_S=43200; it was 10 minutes, which cut relayed views after about 10 minutes). A relayed view left open
longer reconnects by itself with a new credential. Set a lower value if you prefer shorter-lived credentials, and expect
that reconnect sooner.
Set your own ICE servers (cloud settings)
| Variable | Meaning |
|---|---|
VENOM_RTC_ICE_SERVERS |
Unset: stun:stun.cloudflare.com:3478. none: no STUN. A comma-separated list of stun:/turn: URLs, or a JSON array of {"urls": ..., "username": ..., "credential": ...} objects. A typo is an error (rtc_misconfigured), never a silent fallback to a server you did not choose. |
VENOM_RTC_TURN_URLS |
Comma-separated turn: or turns: URLs of your TURN server. |
VENOM_RTC_TURN_SECRET |
The TURN server's shared secret. The cloud never sends it: it makes a username <expiry>:<viewer> and the credential base64(HMAC-SHA1(secret, username)) (the TURN REST scheme) for each session, good for VENOM_RTC_TURN_TTL_S seconds. |
VENOM_RTC_TURN_TTL_S |
How long a TURN credential lasts, for coturn and Cloudflare alike: default 43200 (12 hours), 60 to 86400. |
VENOM_RTC_CF_TURN_KEY_ID |
Cloudflare Realtime TURN: the TURN key's id (managed TURN). Only with VENOM_RTC_CF_TURN_TOKEN. |
VENOM_RTC_CF_TURN_TOKEN |
Cloudflare Realtime TURN: the TURN key's API token. Never sent to a browser or a daemon. |
The same servers go to the browser and to the daemon. Nothing runs on the daemon's side to configure: it takes the list from the offer.
Direct (a public or tunnel endpoint)
A daemon that advertises a public or tunnel https endpoint (see below) also serves the live view itself, and the console
uses that first. It asks the cloud for a computer ticket:
POST /api/workspace/computers/{id}/screen {"scope": "view" | "control"}
-> {"mode": "direct", "endpoint": "https://...", "ticket": "vtk....", "expires_at": "..."}The ticket is the same Ed25519 ticket the mesh uses for inference, with mode: "computer", the seat and the scope. It
lives 60 seconds, only long enough for the WebSocket handshake. The browser then opens
wss://<endpoint>/computers/{seat}/screen?venom_ticket=... against your daemon, which checks the signature, the expiry,
that the ticket is for this daemon and this seat, and spends its id so a copied URL cannot be replayed. A computer ticket
never opens an inference route, and an inference ticket never opens a screen.
- view receives frames. Anything a viewer sends is dropped.
- control also sends clicks and keys, at most 60 events a second. The cloud mints it only for the person who holds the
seat's control lease; asking without it answers
409 control_required.
GET /computers/{seat}/thumbnail on the daemon takes the same ticket and returns one small JPEG. The fleet view uses it
for the cards on screen.
Snapshots (the last resort)
When neither of the others can be had (the browser has no WebRTC, the network blocks it and there is no TURN server, five people are already watching), the console shows the computer as a thumbnail that refreshes every couple of seconds, with the reason. Snapshots are a fallback, not a verdict: while they show, the live view tries the live paths again in the background (after 5, 10, 20 and 30 seconds, then every minute, and at once when the tab comes back or the network does) and switches to the live picture as soon as one connects. A live view that drops reconnects by itself and keeps the last picture on screen, marked as reconnecting, until the new one arrives. One open view keeps one session: a seat that reads as offline for a moment (a daemon heartbeat a little late) keeps its connection for 12 seconds before the view lets it go. When the snapshots show because a connection could not be made, the note's link explains the TURN server that fixes it.
- While someone is looking, the cloud marks the seat watched (a presence row, 30 seconds, renewed by each request).
- The daemon is told in every heartbeat answer which of its seats are watched and posts a JPEG of at most 40 KB, at most
one per 2 seconds per seat, to
POST /api/mesh/v1/computers/{seat}/frame: a 480-pixel-wide screenshot of a running seat, never of one that is stopped (a picture never wakes a computer). The cloud keeps frames for 60 seconds. The fleet's cards on the Computers page use the same frames. A watched computer does not hibernate for being idle; its ten minutes start when the watching ends. - The console long-polls
GET /api/workspace/computers/{id}/frame?after=<seq>(up to 20 seconds per request).GET /api/workspace/computers/{id}/thumbnailreturns the newest frame if it is at most 5 seconds old, otherwise waits a few seconds for the next one.
The cloud never relays input, so snapshots cannot be used to take control. For control with no reachable endpoint the
cloud answers POST .../screen with "mode": "rtc" and the console connects over WebRTC; a daemon that is offline
answers 409 daemon_offline.
Optional: give a daemon a reachable endpoint
You do not need this for the live view. It saves the WebRTC handshake and carries inference to clients too. Set one endpoint on the daemon with VENOM_MESH_ENDPOINTS, for example
tunnel=https://venom.example.com/v1 (a Cloudflare tunnel, a Tailscale funnel or a reverse proxy such as Caddy in front
of the daemon's port). The computers screen paths hang off the same origin, so the proxy must pass WebSocket upgrades.
See Connect a daemon for the variable and the endpoint kinds. Only public and tunnel
endpoints on https are used for the live view: a lan or tailnet endpoint serves inference to clients on those networks
but is not offered to a browser by the cloud.
The control lease
Take control takes an exclusive lease on the seat for 5 minutes; the live view renews it while it is open, and Release or the lease running out ends it. While a person holds it:
- the cloud tells the daemon (in the heartbeat answer, and a control session on WebRTC ends the moment the lease does), and the
agent's input tools (
Input.*over CDP: click, type, press, scroll) answercontrol_held_by_person, on every computer, dedicated or shared. The agent waits and may still read the page. The daemon takes the lease within one heartbeat (about 10 seconds) and gives it back when the cloud drops it or its end time passes, even if the cloud cannot be reached; - nobody else can take it (
409 control_held, with who holds it).
A browser computer has no address bar of its own, so while you hold control the view shows an address box above the
screen: type an address (example.com gets https://) and press Enter. Only http and https addresses are sent;
venom-seatd passes nothing but the URL to the browser and refuses any other scheme.
Runtime.evaluate that dispatches events from page scripts is not intercepted: the lease protects the agent from fighting a
person's mouse, it is not a security boundary against code the agent was already allowed to run.
An agent asks for a person
In a computer session the harness declares computer_request_takeover {reason}. The seat shows Needs you and its
owner is told. The tool waits until the person presses I'm done or Skip, releases control, or 30 minutes pass
(then the seat goes back to active and the tool says nobody answered), and the agent reads the page again. Keep the reason
to what the person must do: no passwords or codes, a secret in it is removed.
POST /api/workspace/computers/{id}/takeover/resolve {"outcome": "done" | "skip"}Agents outside a computer session use the computers_takeover_request MCP tool (see Computers for agents);
computers_thumbnail_get returns the relay thumbnail as base64.