Browser Gateway

browser-gateway

The open router for cloud browsers.

One endpoint that routes across every browser provider you use: automatic failover, persistent profiles, session replay, REST API, MCP server, dashboard.

Works unchanged with Puppeteer, Playwright, Stagehand, browser-use, and any MCP client.

Website · Quick start · MCP · Profiles · Replays · REST API · Dashboard · Discord

---

Overview

One endpoint. Multiple providers. Automatic failover when one is saturated or 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.

---

Dashboard

A web dashboard ships with every install. Open http://localhost:9500/web after starting the gateway.

Overview. Active sessions, queue depth, provider health, connection endpoint, and a copy-paste quickstart for Puppeteer, Playwright, Stagehand, browser-use, and raw CDP.

REST API. Run screenshot, content extraction, and structured scraping endpoints from a form-driven UI, with profile selection and parameter reference inline.

Playground. Drive any provider live from the browser. Pick a provider and profile, type into the canvas as if it were a local browser, and watch the remote session in real time.

---

Features

Routing & reliability

• Automatic failover - the next provider takes over the instant one fails, no client changes
• Five load-balancing strategies - priority chain, round-robin, least-connections, latency-optimized, weighted
• Per-provider concurrency limits - the gateway enforces maxConcurrent on every backend
• Request queue - connections wait when every provider is saturated instead of failing immediately
• Cooldown - failing providers are skipped and recover automatically after a TTL
• Health checks - periodic connectivity probes mark providers unhealthy before clients hit them
• Graceful shutdown - active sessions drain cleanly on SIGTERM and SIGINT
• Session reconnect - a dropped client reconnects with ?sessionId= ; on a provider that issues a resume token (browserserve with its resume window on) it gets the same browser back with its pages, cookies and storage, otherwise a new browser on the same provider
• Webhooks - fire on provider down, recover, and queue-overflow events

REST API

• Screenshot - POST /v1/screenshot returns any URL as PNG or JPEG, full-page or scoped to a selector
• Content extraction - POST /v1/content returns markdown, plain text, HTML, or a cleaned article
• Scrape - POST /v1/scrape extracts structured data via CSS selectors or full-page formats
• Pooled sessions - browser connections are reused across requests, like a database pool
• Automatic retry - failed requests retry against a fresh page

Profiles — persistent browser state

• Survive across sessions - cookies and localStorage are captured as you leave each page and on disconnect, and replayed on the next connect with the same id (IndexedDB too on browserserve)
• Saved on any provider - every provider can load and save any profile; pin a provider to one profile only to route that profile's sessions there
• Profiles never mix - a browser that still holds a different profile is refused. Anything else already in a reused browser (from sessions without a profile) is saved with the profile
• 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, and a scrypt-derived KEK
• Provider-agnostic - state is captured at the CDP level, so it replays against any provider
• Per-profile locking - concurrent connects to the same id return HTTP 409 to prevent corruption
• Export and import - encrypted .bgp blobs are portable between gateway installs
• One-click enable - the dashboard wizard generates a strong key in your browser and writes it to config

See the Profiles docs for the full guide, security model, REST endpoints, and limitations.

Session replay — see what the agent saw

• Frame-accurate visual record of every routed session, captured via CDP Page.startScreencast
• Zero injection - no script runs inside the customer page, capture is fully out-of-band
• Provider-agnostic - works with any backend that supports page screencast
• Dashboard player - scrub through the recorded frames, switch between captured browser targets
• Retention controls - configurable horizon, per-session byte cap, daily cleanup

See the Replays docs for the storage layout, REST endpoints, and tuning knobs.

MCP server for AI agents

• One-call tools - fetch_page reads any url as markdown and screenshot_page captures it, each in a single call that opens and closes its own browser
• Session tools - browser_session, browser_navigate, browser_snapshot, browser_act, browser_extract, browser_screenshot, browser_wait, browser_tabs, browser_evaluate, browser_observe for logins, forms and multi-step work
• Fallback for coding agents - a Claude Code plugin sends Claude to fetch_page when its built-in web fetch is blocked, empty or needs JavaScript (/plugin marketplace add browser-gateway/browser-gateway); setup for Codex, Cursor and Gemini CLI in plugins/browser-gateway
• Zero config - auto-detects Chrome and launches it on first tool use
• Concurrent sessions - every agent gets its own browser, no shared state
• Raw CDP - no Playwright or Puppeteer dependency
• Compatible - Claude Code, Cursor, and any MCP-compatible client

Computer use for Claude and Gemini

• Any browser for the model's own browser tool - runs Claude's browser and computer use tools and Gemini computer use on any provider behind the gateway
• About ten lines - runClaudeLoop / runGeminiLoop take your own model call and handle actions, screenshots and results
• Safe defaults - http and https only, private networks blocked, optional site allowlist, Gemini's confirm step for risky actions
• No extra dependencies - browser-gateway/agent-tools/computer-use, tested on Node.js, Bun, Deno and the Cloudflare Workers runtime

Management

• Dashboard - manage providers, watch sessions, and edit config from the browser
• Provider CRUD - add, edit, delete, and test providers from the dashboard or API
• Config editor - edit gateway.yml in-browser with syntax highlighting and validation
• Auth - token-based, with a secure HttpOnly cookie for the dashboard
• Protocol-agnostic - works with Playwright, Puppeteer, and 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://loca