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

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');

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": ["brows

... [View full README on GitHub](https://github.com/browser-gateway/browser-gateway#readme)