Live Playground

An in-browser CDP viewer at /web/playground. Click into a live browser session from the dashboard, exercise a page, and optionally save the resulting state to a profile.

What It Is

A dashboard page that streams live pixels from a routed browser session and forwards clicks, typing, and scrolls back to the browser. Useful for:

• Debugging what an agent actually saw before it failed.
• Building a profile interactively (log into a site once, save the resulting cookies + storage to a profile you can then reuse from code).
• Sanity-checking a new provider without writing any client code.

How To Open It

1. Start the gateway: browser-gateway serve
2. Open the dashboard at http://localhost:9500/web
3. Click Playground in the sidebar
4. Pick a provider, optionally pick a profile, click Start

The playground opens a fresh browser session on the selected provider, streams its viewport to the page, and captures your input events.

Save Changes To Profile

When a profile is selected, a Save changes to profile checkbox appears next to the profile picker. Checked by default (matching the product default of write-back). Uncheck it to run the session read-only, changes are discarded on disconnect.

See Profiles → Read-only vs write-back for the underlying semantics.

Keep-Alive Duration

A playground session has a fixed length, 5 minutes by default. The duration selector next to the Start button sets it anywhere from 1 to 20 minutes, which is useful for long interactive work such as log-in flows with 2FA or checkout tests. About 30 seconds before the end the page warns you, and when the time is up the session closes.

Under The Hood

The playground uses the /v1/live WebSocket endpoint. Auth uses the standard BG_TOKEN. The client runs in the browser and is exposed as a package subpath, so you can embed the same viewer in your own UI:

import { LiveClient } from "browser-gateway/live-client";

const client = new LiveClient({
  onOpen: () => console.log("connected"),
  onFrame: (bitmap, meta) => {
    // draw the frame, e.g. canvas.getContext("2d").drawImage(bitmap, 0, 0)
  },
  onUrl: (url) => console.log("page url", url),
  onError: (code, message) => console.error(code, message),
  onClose: ({ code, reason }) => console.log("closed", code, reason),
  onExpiring: (secondsLeft) => console.log(`closing in ${secondsLeft}s`),
});

client.connect({
  wsBase: "ws://localhost:9500",   // defaults to the current page's host
  token: "YOUR_BG_TOKEN",
  provider: "runtime",
  profile: "acme-prod",
  readOnly: false,                 // true = load the profile but do not save changes
  keepAliveSeconds: 15 * 60,       // 60 to 1200 seconds; omit for no time limit
});

client.navigate("https://en.wikipedia.org/wiki/Web_browser");

The constructor takes your event handlers. connect() opens the socket and returns immediately; onOpen fires once it is connected. The client also has navigate(), navAction("back" | "forward" | "reload"), setViewport(), sendPaste() and close(). It does not reconnect on its own; if the connection drops, onClose fires and you call connect() on a new client.

The same LiveClient powers the dashboard's playground page.

When To Use Which Recording Tool