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 Persistence - Disconnect and reconnect to the same browser. Cookies, localStorage, page state preserved.
• 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

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
• 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.io
• GitHub
• npm