Web Dashboard

browser-gateway includes a built-in web dashboard for monitoring and managing your gateway. No extra tools needed, it's served from the same port as the gateway itself.

http://localhost:9500/web

What You Can Do From the Dashboard

• See which providers are healthy and which are down
• Monitor active browser sessions in real time
• Add, edit, delete, and test providers without touching config files
• Manage saved profiles
• Try the REST API and watch a live browser view from the browser
• Add, edit, and test webhooks
• Follow the gateway's logs without terminal access
• Edit your gateway.yml with syntax highlighting and validation
• Copy the WebSocket connection URL for your code

Pages with live data refresh on their own, every 3 to 10 seconds.

Pages

The dashboard has 9 pages, accessible from the sidebar: Overview, Providers, Sessions, API, Playground, Profiles, Logs, Webhooks, and Config. Session recordings have no dashboard page; read them through the Replays REST API.

Overview

The first thing you see. Shows the current state of your gateway at a glance.

What's on this page:

• Stats Cards. Four cards showing:

  • Active sessions (how many browser connections are open right now)
  • Queued (how many requests are waiting for a free provider slot)
  • Providers (how many are healthy out of total, e.g., "2/3")
  • Strategy (which load balancing strategy is active)

• Connection Endpoint. The WebSocket URL your code should connect to (e.g., ws://localhost:9500/v1/connect), with a copy button. When BG_TOKEN is set, the token is shown masked and the copy button writes the real value.

• Quick Start. Copy-paste snippets for Puppeteer, Playwright, Stagehand, browser-use, and raw CDP, each already pointed at this gateway.

Per-provider health lives on the Providers page.

If you have no providers yet, the overview shows a "Get started" card linking to the Providers page.

Providers

Where you manage your browser providers. Uses dedicated pages, not a modal.

Adding a provider: click New Provider in the header to open /web/providers/new. Fill in:

Under Advanced, an editor for custom headers (Bearer tokens, API keys, custom handshake headers) with an eye-toggle to mask sensitive values. See Configuration → Custom headers.

Test the connection from the form before saving. Reports reachability + latency, or the failure reason.

Editing an existing provider opens /web/providers/edit?slug=<name> with the same form pre-filled.

Per-provider card on the list page shows:

• Health status: a dot plus a label (Ready, Paused, Not reachable, Disabled, or Checking). The dot pulses red when the provider is paused or not reachable
• Priority and weight lines, each with the plain-English effect below
• Active connections vs. max, average latency, total connections routed
• An on/off switch. Off takes the provider out of routing without deleting it; the card shows Disabled until it is switched back on
• Test / Edit / Delete actions

Changes save to gateway.yml atomically.

Sessions

A live table of every active browser connection going through the gateway.

This page is read-only, you're observing active connections, not managing them. It refreshes every 3 seconds.

When no sessions are active, it shows "No active sessions."

API

The REST API reference and try-it surface. Each one-shot REST endpoint (screenshot, page content, and scrape) is listed with its parameters and a request you can run against your own providers from the browser. See REST API for the full reference.

Playground

An in-browser CDP viewer that streams a live browser session to the dashboard. Click into the page, exercise it, and optionally save the resulting state to a profile via the Save changes to profile checkbox. See Live Playground for the full page.

Profiles

Manage saved browser profiles: a logged-in session captured once and replayed into later sessions. Copy a profile's connect URL (including a read-only variant), see what each profile stores, and delete profiles you no longer need. See Profiles.

Config

A full YAML editor for your gateway.yml file.

What you can do:

• Edit the YAML directly in the browser (syntax highlighting, monospace font)
• Click Validate to check if your YAML is valid without saving
• Click Save to write changes back to disk (a backup is created automatically before each save)
• Click Discard to throw away unsaved changes

The editor shows the file path where the config is stored. Validation feedback appears below the editor: a confirmation with the provider count when the YAML is valid, or the specific errors when it is not.

Tip: Provider changes made here require a gateway restart to take effect. For live provider changes, use the Providers page instead.

Logs

A live view of the gateway's structured logs, streamed into the dashboard so you do not need terminal access. Follow events as they happen: session starts and ends, provider health changes, and failovers.

Webhooks

Add, edit, test, and delete webhooks, and choose which events each one receives: a provider paused after repeated failures, a queued request timing out, or the gateway shutting down. See Webhooks.

Authentication

If you've set BG_TOKEN (via environment variable or .env file), the dashboard requires authentication.

How it works:

1. Open the dashboard, you see a login form
2. Enter your gateway token (the value of BG_TOKEN)
3. The dashboard sets a secure HttpOnly cookie in your browser
4. You stay logged in for up to 30 days

You are logged out when any of these happen:

• 30 days pass since you logged in
• The gateway restarts. Each gateway process signs cookies with its own session key, so log in again after a restart or redeploy
• Anyone logs out. Logging out rotates the session key, which ends every dashboard session, not only yours
• BG_TOKEN changes

If BG_TOKEN is not set, there's no login form, the dashboard is open to anyone who can reach it. Only do this on private networks or localhost.

Accessing the Dashboard

Local development

http://localhost:9500/web

Docker

Map port 9500 and open in your browser:

docker run -d -p 9500:9500 ghcr.io/browser-gateway/server:latest
# Open http://localhost:9500/web

Remote server

If running on a remote server, access via the server's IP or domain:

http://your-server:9500/web

Important: If the dashboard is exposed to the internet, always set BG_TOKEN to require authentication. Without it, anyone can view your providers, sessions, and config.

For HTTPS, put the gateway behind a reverse proxy (nginx, Caddy, Traefik) that handles TLS. The dashboard automatically detects HTTPS and shows wss:// in the connection URL.

Disabling the Dashboard

If you don't need the web UI (e.g., API-only usage):

dashboard:
  enabled: false

The gateway still works normally, you won't have the /web route.

Tips

• The overview page is your health check. Glance at it to see how many providers are healthy, how many sessions are active, and whether anything is queued.
• Test before you save. When adding a provider, always use the test button to verify connectivity before saving. Saves you from debugging typos in URLs.
• Use the config page for advanced settings. Things like cooldown thresholds, queue size, and webhook URLs are easier to set in YAML than through individual forms.
• Sessions page helps debug "where did my connection go?" If a client connects and you're not sure which provider it landed on, check the sessions table.