Browser Gateway

browser-gateway

Reliable, scalable browser infrastructure for AI agents and automation.

Route, pool, and failover across any browser provider. Built-in MCP server for AI agents.

---

What It Does

                         ┌─────────────────────┐
                         │   browser-gateway    │
                         │                      │
                         │  routing / failover  │
                         │  load balancing      │
                         │  health monitoring   │
                         │  request queuing     │
                         └──────────┬───────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                   │
          ┌──────┴──────┐   ┌──────┴──────┐   ┌───────┴──────┐
          │ Provider A  │   │ Provider B  │   │ Provider C   │
          │ Cloud CDP   │   │ Playwright  │   │ Local Chrome │
          │ priority: 1 │   │ Docker :4000│   │ Docker :9222 │
          └─────────────┘   └─────────────┘   └──────────────┘

One endpoint. Multiple providers. Automatic failover if one goes down.

Your app connects to ws://gateway:9500/v1/connect. The gateway picks the best available provider based on health, capacity, and your routing strategy. Providers can be cloud CDP services, Docker containers, or local Chrome instances.

---

Core Features

Routing & Reliability

• Automatic Failover - Provider down? Next one picks up instantly. Zero client changes.
• 5 Load Balancing Strategies - Priority chain, round-robin, least-connections, latency-optimized, weighted
• Per-Provider Concurrency Limits - Set maxConcurrent per provider, gateway enforces it
• Request Queue - All providers busy? Connections wait instead of failing
• Cooldown System - Skip failing providers automatically, recover after TTL
• Health Checks - Periodic connectivity probes detect unhealthy providers
• Graceful Shutdown - Active sessions drain cleanly on SIGTERM/SIGINT
• Session Reconnect - If a client drops, reconnect with the same session ID and the gateway routes you back to the same provider. The browser there is still alive (as long as the provider keeps it running), so cookies, localStorage, and page state are intact. Works best with raw Chrome and providers that don't kill the browser on disconnect.
• Webhooks - Get notified when providers go down, recover, or queue overflows

REST API

• Screenshot - POST /v1/screenshot — capture any page as PNG or JPEG
• Content Extraction - POST /v1/content — get page content as markdown, text, HTML, or cleaned article
• Scrape - POST /v1/scrape — extract data with CSS selectors or get full-page content
• Session Pool - Browser connections are reused across requests (like a database connection pool)
• Auto-Retry - Failed requests automatically retry with a fresh browser page

Profiles — Persistent Browser State

• Survive Across Sessions - Cookies, localStorage, sessionStorage, IndexedDB saved on disconnect, replayed on the next connect with the same id
• One-Line Opt-In - Add ?profile=acme to the WebSocket URL — the rest is automatic
• Encrypted At Rest - AES-256-GCM with envelope encryption, anti-swap binding, scrypt-derived KEK
• Provider-Agnostic - Works across any CDP provider (raw Chrome, Browserless, Steel, Browserbase, etc.) since state is captured at the protocol level
• Per-Profile Locking - Concurrent connects to the same id are rejected cleanly with HTTP 409 to prevent corruption
• Export / Import - Encrypted .bgp blobs are portable between gateway installs
• One-Click Enable - Dashboard wizard generates a strong key in your browser and writes the config for you

See docs/profiles.md for the full guide, security model, REST endpoints, and limitations.

MCP Server for AI Agents

• 8 Browser Tools - navigate, snapshot, screenshot, viewport, interact, evaluate, close, status
• Zero Config - Auto-detects Chrome, launches on first tool use
• Concurrent Sessions - Multiple agents get separate browsers, no conflicts
• Raw CDP - Lightweight, no Playwright or Puppeteer dependency
• Works with Claude Code, Cursor, and any MCP-compatible client

Management

• Web Dashboard - Manage providers, view sessions, edit config from the browser
• Provider CRUD - Add, edit, delete, and test providers from the dashboard or API
• Config Editor - Edit gateway.yml with syntax highlighting and validation
• Auth - Token-based with secure HttpOnly cookie for the dashboard
• Protocol Agnostic - Works with Playwright, Puppeteer, any WebSocket protocol

---

Quick Start

As a WebSocket Proxy (for applications)

npm install -g browser-gateway

Create gateway.yml:

version: 1

providers:
  primary:
    url: wss://provider.example.com?token=${PROVIDER_TOKEN}
    limits:
      maxConcurrent: 5
    priority: 1

  fallback:
    url: ws://my-playwright-server:4000
    limits:
      maxConcurrent: 10
    priority: 2

browser-gateway serve

Connect from your app:

// For CDP providers
const browser = await chromium.connectOverCDP('ws://localhost:9500/v1/connect');

// For Playwright run-server providers
const browser = await chromium.connect('ws://localhost:9500/v1/connect');

Or use the REST API — no WebSocket management needed:

# Screenshot
curl -X POST http://localhost:9500/v1/screenshot \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}' --output screenshot.png

# Extract content as markdown
curl -X POST http://localhost:9500/v1/content \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}'

Dashboard at http://localhost:9500/web.

As an MCP Server (for AI agents)

Add to your Claude Code or Cursor config:

{
  "mcpServers": {
    "browser-gateway": {
      "command": "npx",
      "args": ["browser-gateway", "mcp"]
    }
  }
}

No config files needed. The agent can now browse websites, take screenshots, fill forms, and extract data.

See the MCP documentation for all options.

---

Dashboard

Built-in web dashboard at http://localhost:9500/web. Served from the same port as the gateway.

Page	What You Can Do
Overview	Gateway health at a glance: active sessions, provider status, connection endpoint
Providers	Add, edit, delete, and test browser providers. Changes write to gateway.yml
Sessions	Live table of every active connection: provider, duration, message count
Config	Edit gateway.yml in the browser with validation and automatic backups

If BG_TOKEN is set, the dashboard requires authentication via a secure HttpOnly cookie.

See Dashboard Guide for details.

---

Authentication

Set BG_TOKEN to require a token (or put it in a .env file):

BG_TOKEN=my-secret-token browser-gateway serve

• WebSocket clients pass the token as ?token= query param
• API clients use Authorization: Bearer <token> header
• Dashboard shows a login form, sets a secure HttpOnly cookie
• Health endpoint (/health) is always public

---

CLI

# Proxy server
browser-gateway serve                    # Start the gateway + dashboard
browser-gateway serve --port 8080        # Custom port
browser-gateway serve --config path.yml  # Custom config

# MCP server for AI agents
browser-gateway mcp                      # Auto-detect Chrome, zero config
browser-gateway mcp --headless           # Headless mode (for CI/Docker)
browser-gateway mcp --cdp-endpoint ws:// # Connect to existing browser
browser-gateway mcp --config gateway.yml # Multi-provider with failover

# Utilities
browser-gateway check                    # Test provider connectivity
browser-gateway version                  # Print version
browser-gateway help                     # Show help

---

API

Endpoint	Method	Description
/v1/connect	WebSocket	Connect to a browser (the core feature)
/v1/screenshot	POST	Take a screenshot of any URL (docs)
/v1/content	POST	Extract page content as markdown, text, or HTML (docs)
/v1/scrape	POST	Extract data via CSS selectors or full-page formats (docs)
/v1/status	GET	Gateway health + provider status + pool status
/v1/sessions	GET	Active sessions
/v1/providers	GET/POST	List or add providers
/v1/providers/:id	PUT/DELETE	Update or remove a provider
/v1/providers/:id/test	POST	Test provider connectivity
/v1/config	GET/PUT	Read or save config
/v1/config/validate	POST	Validate YAML without saving
/mcp	POST	MCP Streamable HTTP endpoint
/json/version	GET	CDP discovery (for browser-use, Playwright, Stagehand)
/health	GET	Health check

---

Docker

docker run -d \
  -p 9500:9500 \
  -v ./gateway.yml:/app/gateway.yml:ro \
  -e PROVIDER_TOKEN=xxx \
  ghcr.io/browser-gateway/server:latest

---

How It Works

1. Client connects to ws://gateway:9500/v1/connect
2. Gateway selects a provider using your routing strategy
3. Gateway opens a raw TCP connection to the provider
4. HTTP upgrade forwarded, provider responds with 101 Switching Protocols
5. Bidirectional TCP pipe: client <-> gateway <-> provider
6. All WebSocket messages forwarded transparently (never parsed or modified)
7. On disconnect: session cleaned up, slot released, metrics updated
8. If all providers full: connection waits in a queue until a slot opens

---

Works With

browser-gateway is compatible with existing browser tools. Just pass the gateway URL — it auto-resolves via /json/version.

AI Agent Frameworks:

# browser-use (Python) — HTTP URL auto-resolves
BrowserSession(cdp_url="http://localhost:9500")

// Stagehand (TypeScript)
new Stagehand({ env: "LOCAL", localBrowserLaunchOptions: { cdpUrl: "http://localhost:9500" } })

Playwright MCP (all 70 Playwright tools through gateway routing):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--cdp-endpoint", "http://localhost:9500"]
    }
  }
}

Puppeteer / Playwright:

// Playwright — HTTP or WebSocket
const browser = await chromium.connectOverCDP("http://localhost:9500");

// Puppeteer — WebSocket
const browser = await puppeteer.connect({ browserWSEndpoint: "ws://localhost:9500/v1/connect" });

---

Documentation

• MCP Server for AI Agents - Setup, tools, options
• Integrations - Playwright, Puppeteer, browser-use, Stagehand, Playwright MCP
• Profiles — Persistent Browser State - Save and replay cookies + storage across sessions
• Getting Started
• Configuration Reference
• How Failover Works
• Load Balancing Strategies
• Request Queue
• Webhooks
• Web Dashboard
• Supported Providers
• Session Lifecycle
• CLI Reference
• Docker Deployment

---

Contributing

Contributions welcome. See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE.

Links

• browsergateway.com
• GitHub
• npm