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 and browse session replays
• 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

Everything updates automatically every 3-5 seconds.

Pages

The dashboard has 10 pages, accessible from the sidebar: Overview, Providers, Sessions, API, Playground, Profiles, Replays, Logs, Webhooks, and Config.

Overview

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

What's on this page:

• Connection Endpoint. The WebSocket URL your code should connect to (e.g., ws://localhost:9500/v1/connect). Includes copy-paste code snippets for both Playwright and Puppeteer. The URL automatically adjusts based on how you're accessing the dashboard, if you're on HTTPS, it shows wss://, otherwise ws://.

• Stats Cards. Three cards showing:

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

• Provider List. A card for each provider showing:

  • Health status (green dot = healthy, red pulsing dot = down or in cooldown)
  • Active connections vs. maximum (e.g., "3/10")
  • Average connection latency
  • Total connections routed (lifetime)
  • Cooldown status (if the provider is temporarily skipped due to failures)

If you have no providers yet, the overview shows a friendly "Get Started" card explaining what providers are and 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 (green dot = healthy, red pulsing dot = down or in cooldown)
• Priority and weight lines, each with the plain-English effect below
• Active connections vs. max, average latency, total connections routed
• 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. Every REST endpoint (screenshot, PDF, page content, and the rest) 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.

Replays

Browse and play back recorded sessions frame by frame. Retention and a per-session size cap are configurable. See Replays.

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, green for valid, red with specific error messages for invalid YAML.

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 (session started and ended, provider up and down, and more). 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 until you log out or the cookie expires

The cookie is tied to your BG_TOKEN value, so it survives gateway restarts. If you change BG_TOKEN, everyone gets logged out.

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 if all providers are green and how many sessions are active.
• 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.