Session browser preview

A session can expose one HTTP server it runs inside its container to the owner's browser, for example a development server or a generated report. The preview is off by default and is enabled per session.

For agents

Every session has one stable preview port in the environment variable $DEVCTL_PREVIEW_PORT of its shell. The live DEVCTRL.AGENTS.MD explains how to read it; it is shared by the container's sessions and so cannot name one port. When devctrl writes session-private rules for a managed agent configuration ($HOME/agent-config/<hash>/DEVCTL.RULES.md, passed to the agent as its system prompt), they name the port too. Bind a user-facing server to 0.0.0.0:$DEVCTL_PREVIEW_PORT. No other container port is reachable through the preview. The preview has its own origin, so the app needs no base path. Requests arrive with Host: localhost; the browser's host is in X-Forwarded-Host.

The port is derived from the session's runtime key (range 41000–48999), so the runtime, the Host and Core agree without passing it through launch commands. Two sessions in one container can in rare cases derive the same port; the second server then fails to bind and the agent sees the error.

For people

In Projects or Sessions, select an agent session and press w. The preview panel turns the preview on if needed, requests a one-use link and shows it as plain, copyable text together with the port the session's server must listen on. It never opens a browser by itself, because opening spends the link: press o to open it. In the terminal console o asks ./devctl on your machine to open the link, but only after checking that the preview listener (for example 127.0.0.1:8789) answers there. When it does not, the link stays unused and the panel says to run ./devctl web open (see web console); press o again once the forward runs. A link handed to the system opener counts as used, whether or not a browser confirmed it, and so does a link whose opener never reported back. In the panel, o opens the link and c copies it; both request a fresh link first when the current one is used or within 5 seconds of its expiry. The panel says whether the browser opened the link, and otherwise why not: the listener does not answer here, the opener failed (with its exit status), or the opener did not report back within 15 seconds. The helper logs each outcome, without the link, to .devctl/preview-open.log. x turns the preview off and ends its open connections, and Esc closes the panel. Shift+W stays Workflows. An enabled session shows "Browser preview on" under it. The w binding can be changed in Settings → Hotkeys.

API: GET/PUT /v1/sessions/:id/preview ({ "enabled": true }) and POST /v1/sessions/:id/preview/link, which returns { url, expiresAt, port }. Only the session's owner (or the operator) can use them.

How a request travels

  1. Core issues a one-use link for the owner. It expires after 60 seconds.
  2. The browser opens http://<slug>.localhost:8789/__devctl_preview/session?ticket=… on the web gateway's preview listener. The gateway redeems the ticket with Core once and stores the returned grant in an HttpOnly, SameSite=Lax, host-only cookie (__Host- prefixed on HTTPS). The grant lasts 12 hours. Any redemption attempt spends the ticket. A refused link tells the browser why: already used, expired, issued for another session's preview address, or preview turned off for the session ("Preview is turned off"). Core keeps a spent or revoked ticket for 15 minutes only to name that reason.
  3. For each connection the gateway opens a stream to Core with the grant. Core checks the grant, the user's current access to the session, that the preview is still enabled and that the session is running. It then asks the session's Host to connect.
  4. The Host opens the stream to the session's derived port from inside the session's Project container and only then connects back to Core. Project containers sit only on an internal Docker network whose bridge has no Host gateway address (gateway_mode_ipv4=isolated), so the Host cannot route to them, so the Host runs a small helper with docker exec in that container, the way its other container probes run: the container's own /usr/local/bin/node, as user nobody (65534), with NODE_OPTIONS and loader variables cleared. The helper connects to 127.0.0.1 (then ::1) on that one port, reports whether it connected within 3 seconds, and then relays bytes over the exec's stdin and stdout. Each browser connection uses one helper process (about 45 MB resident) that exits when the connection closes or after 10 minutes without traffic.
  5. Core tells the gateway that the stream is attached only after the Host has connected. When the Host could not connect it says why, and the gateway answers at once: 502 "Nothing is listening on the session's preview port N" when the port refuses, 502 "Can't reach the session container's preview port N" for other failures, and 503 when the session's container is not running. A Host that does not answer within 10 seconds gives 504.

Isolation

Reaching the preview listener

The gateway serves previews on a separate listener, port 8789 by default (DEVCTL_PREVIEW_PORT), on the same bind address as the console. The default origin is http://{slug}.localhost:8789; browsers resolve *.localhost to the local machine. When the gateway runs on a server, forward the port, for example ssh -L 8789:127.0.0.1:8789 server. devctrl does not publish the preview listener through a public tunnel.

One port per session (no wildcard DNS)

Tailnets, LANs and plain domains usually have no wildcard DNS. Set a per-port origin on Core and the web gateway instead:

DEVCTL_PREVIEW_ORIGIN='https://devbox.tail1234.ts.net:{port}'
DEVCTL_PREVIEW_PORTS=8790-8829

The gateway then listens on every port of the range. Core assigns the first free port to a session when its owner opens a preview and keeps it while the preview stays on; turning the preview off frees the port. Each port is a separate browser origin, so isolation is the same as with host labels: a listener refuses a Host that names another port or another host, and links and grants are bound to that one port. When every port is in use, opening one more preview fails with a clear message. Make the range reachable the same way as the console (a tailnet ACL, firewall rule or reverse proxy per port).

To serve previews on your own domain, set the same DEVCTL_PREVIEW_ORIGIN on Core and the web gateway, for example https://{slug}.preview.example.com, and provide a wildcard DNS record, a wildcard certificate and a reverse proxy to the preview listener that forwards WebSocket upgrades and the original Host.

End-to-end encryption

Previews are separate browser origins and do not use the end-to-end encrypted channel. When an administrator makes encryption mandatory, the preview listener refuses remote (tunneled) requests; open previews locally, over an SSH forward or a tailnet instead.