Quickstart

1. Install

npm install -g browser-gateway

Or run without installing:

npx browser-gateway serve

Or via Docker:

docker run -d -p 9500:9500 ghcr.io/browser-gateway/server:latest

2. Point at a browser

Save this as gateway.yml:

version: 1
gateway:
  port: 9500
providers:
  my-chrome:
    url: http://localhost:9222       # a Chrome running with --remote-debugging-port

Start Chrome for a moment to have something to route to:

docker run -d -p 9222:9222 --shm-size=2g chromedp/headless-shell:latest \
  --no-sandbox --disable-dev-shm-usage

With a Bearer-auth provider

For providers that require a custom Authorization header instead of a URL query token, use the headers field:

version: 1
gateway:
  port: 9500
providers:
  cloud-bearer:
    url: wss://provider.example.com/cdp
    headers:
      Authorization: Bearer ${API_KEY}

${API_KEY} is resolved from the environment (or a .env file) at startup. See Configuration → Custom headers for header merge order and limits.

3. Start the gateway

browser-gateway serve --config gateway.yml

You should see:

▲ browser-gateway vX.Y.Z  ready in 2ms

  ➜  Gateway:         http://localhost:9500
  ➜  Dashboard:       http://localhost:9500/web
  ➜  WS endpoint:     ws://localhost:9500/v1/connect

4. Connect a client

Any CDP or Playwright client talks to the gateway the same way it talks to a browser directly.

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: "ws://localhost:9500/v1/connect",
});
const page = await browser.newPage();
await page.goto("https://example.com/");
console.log(await page.title());
await browser.disconnect();

5. Open the dashboard

Visit http://localhost:9500/web, providers, sessions, profiles, replays, live view, config editor all live there.

Verify

curl http://localhost:9500/health        # gateway is up (always public)
curl http://localhost:9500/v1/status     # provider health and active sessions
browser-gateway check                    # test provider connectivity

Add authentication

Set BG_TOKEN (an environment variable, or a .env file that is auto-loaded on startup) to require a token on every connection:

BG_TOKEN=my-secret-token browser-gateway serve

WebSocket clients then pass ?token=my-secret-token, REST clients send an Authorization: Bearer my-secret-token header, and the dashboard shows a login form. /health stays public.

Add more providers: Browserless, Steel, Cloudflare Browser Rendering, custom CDP
Enable profiles: reuse browser state across sessions
Turn on replay: record every session for later playback
REST API: screenshots, PDF, content extraction with no client code
Configuration reference: every option explained
Failover and load balancing: routing across providers