Browser pane — the usage contract

Two different things can show a web app running inside a Workspace, and picking the wrong one wastes a round trip. This is the contract for both.

The two routes

Term	Contract
Browser pane (the button says “open in pane”)	Chromium inside the Workspace opens http://127.0.0.1:{port}{path} directly and relays rendering and input to a Console pane. Use it for HMR, WebSocket, SSE, cookies, redirects, absolute asset paths, and anything the person needs to operate.
Lightweight preview	A low-cost HTTP proxy opened in a new tab. Only for looking at JSON, a health endpoint or a simple static page once. No HMR, no WebSocket, no SSE; apps that depend on the root path, absolute assets, redirects or cookie paths are not guaranteed to work.
Page	The temporary Chromium Page and its own browser context that the pane owns. How many may exist per Workspace is in limits; they share no cookies or storage.

When in doubt, use the browser pane. The lightweight preview is the cheap exception for “I just need to see one HTTP response”.

How to open either one (the port and path fields, which button is the default where) is a member procedure: See a web app you started. The port 7700 cannot be opened, because the Agent itself uses it.

Which route, by example

The setup-by-setup table (Node / Vite, Spring Boot, API only, frontend + API) is in See a web app you started — examples by setup. The rule behind it: anything that needs HMR, WebSocket, SSE, cookies, redirects or absolute asset paths goes to the browser pane; a single look at one HTTP response goes to the lightweight preview.

States and recovery

The three states the pane can show (target-unreachable, disconnected, crashed), what each means and what to do are in See a web app you started — when it goes wrong. The contract behind them: every recovery action (Reconnect, a Console reload, a Workspace stop/start) creates a new Page at the current port and path, so cookies, storage and half-typed input are not restored.

Lifecycle and resource limits

• A visible browser connection keeps the Workspace warm.
• When the pane is hidden or the Console’s browser tab goes to the background, rendering stops. The Page is held for a grace period (see limits) and then released. On return you get the same Page if it was held, or a new one built from the saved port and path.
• Removing the pane’s identity from the layout releases the Page. Where the identity survives (closing the last pane back to an empty view), the grace period applies instead, and the Page still counts against the limit during that grace period.
• A Workspace stop discards the temporary Page but keeps the port and path in the layout; after start, a visible pane rebuilds itself from the same target.
• Ceilings (Chromium processes, concurrent Pages, viewport, frame rate) are in limits. It is not built for video or high-frame-rate checking.

Scope and known limits

• This is not a general browser. Top-level navigation is restricted to loopback HTTP(S) and redirects to the outside are stopped.
• The Console drawer keeps a bounded number of console messages and uncaught errors (limits) for the connected Page, surfacing error and warn first. It is not a persistent log and not a substitute for DevTools: there is no DOM, Network, Sources or Storage.
• Upload and download, clipboard, drag and drop, audio, video, WebRTC, permission prompts and multiple tabs are all out of scope.
• On a smartphone the entry point moves into ⋯. At phone widths the workspace action bar has no Preview button; ⋯ at its right end opens a popover that holds the same port / path fields and “Open in pane”. From there it is the same as on a desktop: the toolbar, tapping the canvas, Japanese input, the Console drawer.

Where there is no browser pane

A deployment that runs workspaces on the kubernetes runtime (a preview, see deployment targets) or on ecs (Fargate) offers no browser features at all: no browser pane, no Chromium attachments for agents, no headless Chromium. A workspace pod on kubernetes runs under the Pod Security restricted level, which sets NoNewPrivs (the setuid chrome-sandbox cannot elevate) and the runtime’s default seccomp profile (no user namespaces). A Fargate task cannot be given SYS_ADMIN, so the same default seccomp profile refuses the namespaces the setuid helper would create. Either way Chromium’s sandbox cannot start; running Chromium without its sandbox was decided against (ADR 0106, addendum 2026-10-04). ecs-ec2, docker and native are not affected.

What you see instead:

• In Preview, “open in pane” is greyed out; its tooltip and the hint under it name the reason. The lightweight preview works as everywhere else.
• A port in a session row opens in the lightweight preview (a new tab), not in a pane.
• A browser pane restored from a saved layout shows the reason in place of the page, with a button that opens the same port and path in the lightweight preview. A Chromium attachment pane restored the same way shows the reason only, since it has no local port to open.
• Agents are not offered the browser tools at all; one that calls them by name anyway gets browser_unavailable with the same explanation.

The decision comes from the deployment’s runtime, so it is the same for every member of it and shows even while the workspace is stopped.

For agents working inside a Workspace

You have no tool that opens, drives or sees this pane; it belongs to the person. Tell them the exact port and path and point them at Preview → open in pane. Never claim a UI “looks right” on the basis of a pane you cannot see; if you need to verify something yourself, drive your own headless Chromium and say that is what you did. Where AF_BROWSER_UNAVAILABLE is set in your environment there is neither a pane nor a headless Chromium (above): verify with tests and HTTP checks, offer the person the lightweight preview, and say plainly that nothing was checked visually.