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

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.co

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