browser-gateway
Advanced tools
Reliable, scalable browser infrastructure for AI agents and automation.
Route, pool, and failover across any browser provider. Built-in MCP server for AI agents.
┌─────────────────────┐
│ 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.
maxConcurrent per provider, gateway enforces itPOST /v1/screenshot — capture any page as PNG or JPEGPOST /v1/content — get page content as markdown, text, HTML, or cleaned articlePOST /v1/scrape — extract data with CSS selectors or get full-page contentnpm 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.
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.
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.
Set BG_TOKEN to require a token (or put it in a .env file):
BG_TOKEN=my-secret-token browser-gateway serve
?token= query paramAuthorization: Bearer <token> header/health) is always public# 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
| 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 run -d \
-p 9500:9500 \
-v ./gateway.yml:/app/gateway.yml:ro \
-e PROVIDER_TOKEN=xxx \
ghcr.io/browser-gateway/server:latest
ws://gateway:9500/v1/connect101 Switching Protocolsclient <-> gateway <-> providerbrowser-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" });
Contributions welcome. See CONTRIBUTING.md for guidelines.
MIT - see LICENSE.
FAQs
Reliable, scalable browser infrastructure for AI agents.
We found that browser-gateway demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A critical vm2 sandbox escape can allow untrusted JavaScript to break isolation and execute commands on the host Node.js process.
Research
Five malicious NuGet packages impersonate Chinese .NET libraries to deploy a stealer targeting browser credentials, crypto wallets, SSH keys, and local files.
Security News
pnpm 11 turns on a 1-day Minimum Release Age and blocks exotic subdeps by default, adding safeguards against fast-moving supply chain attacks.