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
- Core issues a one-use link for the owner. It expires after 60 seconds.
- 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 anHttpOnly,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. - 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.
- 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 withdocker execin that container, the way its other container probes run: the container's own/usr/local/bin/node, as usernobody(65534), withNODE_OPTIONSand loader variables cleared. The helper connects to127.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. - 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
- Own origin per session. Each session's preview is served on
<slug>.<preview host>, never on the console origin. A preview's scripts can read neither the console nor another session's preview, and the console cookie is never sent to a preview. - Core picks the target. The gateway only relays bytes and never connects to an address or port taken from a request. The Host accepts only the port derived from the session name and dials only from inside its own workspace's Project container (the one running container with that workspace label that is not a nested Docker engine, gateway, sibling or worker), to its loopback. No other service, container or Host port is reachable.
- Requests. The gateway removes its own cookie and any client
X-Forwarded-*headers before forwarding, and dropsDomainfrom cookies the app sets, so one preview cannot plant cookies for another. Paths under/__devctl_preview/are never forwarded. A request whoseHostis not a preview origin is refused, which also stops DNS rebinding. - Bounds. 32 concurrent streams per session and 128 per Host; 32 KiB of request headers; a stream closes after 10 minutes without traffic or when 4 MiB is buffered toward a slow reader. Turning the preview off, losing access to the session, or the session stopping ends access.
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.