browserless/browserless

Overview

Browserless is a Node.js server that runs real browsers in Docker and rents them out over the network. A client connects with stock Puppeteer or Playwright to a WebSocket URL such as ws://host/chromium?token=…, and Browserless launches a fresh browser, pipes the DevTools or Playwright protocol through, and kills the browser when the client disconnects. For callers who do not want a browser library, it also exposes REST endpoints (/content, /scrape, /screenshot, /pdf, /function, /download, /performance) that open a page, run a fixed recipe, and return HTML, JSON or binary.

The value is operational: a concurrency limiter with a queue, per-request timeouts, CPU and memory health gates, token auth, metrics, webhooks for queue, reject and timeout events, OpenAPI docs, a live debugger, and tidy cleanup of profiles and temp directories. It supports Chromium, Chrome, Edge (CDP and Playwright), Firefox and WebKit (Playwright only).

There is no AI in this repository. No LLM calls, no Markdown conversion, no crawler. The README’s LLM-ready crawl, BrowserQL, CAPTCHA solving and residential proxies belong to the hosted product. In an AI scraping stack, Browserless is the browser tier that an agent or extraction library drives. Licensing matters here: the code is SSPL-1.0 or a commercial licence, so closed-source commercial use needs a paid licence.

Architecture

flowchart LR
  C["Puppeteer, Playwright or HTTP client"] --> S["HTTPServer (server.ts)"]
  S --> T["Token auth + AJV schema check"]
  T --> R["Router: route match"]
  R --> L["Limiter: concurrency + queue + timeout"]
  L --> BM["BrowserManager.getBrowserForRequest"]
  BM --> B["ChromiumCDP / *Playwright launch"]
  R --> H["Route handler"]
  H -->|"WebSocket"| P["http-proxy ws pipe"]
  H -->|"REST"| PG["browser.newPage recipe"]
  P --> BR["Browser process"]
  PG --> BR
  BM --> CL["complete(): close + cleanup"]

Component	Path	Role
Entry and composition	src/index.ts, src/browserless.ts	Builds config, limiter, router, browser manager; dynamically imports route files; starts the server
HTTP server	src/server.ts	Request and upgrade handling, CORS, token check, body and query validation
Router	src/router.ts	Path matching, wraps handlers with the limiter and browser acquisition
Limiter	src/limiter.ts	queue-based admission control, health checks, timeouts, metrics and webhooks
Browser manager	src/browsers/index.ts	Launch options parsing, session registry, reconnects, close and cleanup
Browser classes	src/browsers/browsers.cdp.ts, browsers.playwright.ts	Launch Chromium-family over CDP (optionally with stealth) or Playwright browser servers; proxy WebSockets
Shared routes	src/shared/*.ts	WebSocket and REST handlers reused by each browser’s src/routes/<browser>/ stubs
Network guard	src/network-security.ts	Blocks file://, private ranges and cloud metadata hosts
Docker	docker/	Base image plus one image per browser, a multi-browser image and an SDK image

How a request flows

Take puppeteer.connect({ browserWSEndpoint: "ws://host:3000/chromium?token=T&launch={\"stealth\":true}" }):

1. Upgrade. The server sees Upgrade: websocket, moves the token from the query to a header, runs the before hook, parses the URL and finds the WebSocket route (server.ts).
2. Auth and validate. If the route has auth (or STRICT_TOKEN_USE is on), Token.isAuthorized runs, then query parameters are validated against the JSON schema generated from the route’s TypeScript QuerySchema (server.ts).
3. Admit. Routes with concurrency = true are wrapped by Limiter.limit, which rejects with 429 when health checks fail or CONCURRENT + QUEUED is exceeded, and otherwise runs or queues the job under the global timeout (router.ts, limiter.ts).
4. Launch. getBrowserForRequest decodes launch (JSON or base64), merges route defaults, folds --proxy-server into args (or into Playwright’s proxy option), creates a user-data dir and a per-session TMPDIR, and calls browser.launch (browsers/index.ts). ChromiumCDP.launch picks a free port, adds --remote-debugging-port, --no-sandbox and the uBlock extension when blockAds is set, and uses puppeteer-extra with the stealth plugin when stealth is true (browsers.cdp.ts).
5. Pipe. The route handler is one line, browser.proxyWebSocket(req, socket, head) (chromium.ws.ts), which uses http-proxy to splice the client socket onto the browser’s own DevTools endpoint and resolves when either side closes (browsers.cdp.ts).
6. Clean up. When the handler resolves, the router calls browserManager.complete, which decrements connected clients and closes the browser unless another client is attached or a keep-until timer is set (router.ts, browsers/index.ts).

A REST call follows steps 2 to 4 and 6, but the handler opens a page itself. /content applies cookies, viewport, user agent, headers and request interception, navigates (or setContent for raw HTML), runs the optional waits, sets X-Response-* headers from the navigation response, and returns page.content() (content.http.ts).

Key components

Route system

Every endpoint is a class with path, method, auth, concurrency, an optional browser, and a handler. At startup Browserless.start imports every compiled route file plus any the SDK user added, loads sibling *.body.json and *.query.json schemas generated from the TypeScript types, skips routes whose browser cannot run on arm64 Linux, refuses to start if a route needs a browser binary that is not installed, and registers the rest (browserless.ts). Per-browser folders under src/routes/ mostly re-export the shared handlers in src/shared/.

Validation

Bodies and query strings are validated with AJV in allErrors mode with no type coercion and no removal of extra properties, after a MAX_PAYLOAD_SIZE cap (10 MB by default) (schema-validator.ts, server.ts). Unknown or mistyped fields fail with a 400 that lists every error.

Limiter

Limiter extends the queue package with concurrency = CONCURRENT (default 10), an extra QUEUED allowance (default 10) and a TIMEOUT (default 30 s) (config.ts, limiter.ts). Success, timeout and error events feed metrics, after hooks and optional alert webhooks. A route can override the timeout with ?timeout= or bypass limits through a bypassLimits predicate.

REST recipes

/scrape waits for each selector (polling every 100 ms) and returns, for every match, innerText, innerHTML, attributes and geometry (scrape.http.ts). /function runs a user-supplied Puppeteer function against a blank page and infers the response content type from the returned value or its file signature (function.http.ts). These are thin, predictable wrappers, not extractors.

Stealth and network policy

The only anti-detection in the open-source code is @zorilla/puppeteer-extra-plugin-stealth, enabled per session with launch.stealth on CDP routes (browsers.cdp.ts). Proxies are plain Chrome flags you supply. In the other direction, every CDP page gets a Network.setBlockedURLs guard built from blocked URL patterns and private network ranges, so a client cannot steer the browser at the host’s internal network (browsers.cdp.ts).

Extending it

• SDK mode. The npm package exports Browserless and its parts. Pass your own Config, Hooks, Limiter, Router, Token or BrowserManager to the constructor, and add routes with addHTTPRoute or addWebSocketRoute (browserless.ts). A docker/sdk image builds such a project.
• New endpoint. Write a BrowserHTTPRoute subclass with exported BodySchema/QuerySchema types; the build turns them into JSON schemas and OpenAPI entries automatically.
• Hooks. before, after, browser and page hooks let you add auth, logging, billing or page setup without forking.
• Disable features. disableRoutes(...names) removes built-in routes, for example /function on a multi-tenant deployment.

Running it

• Docker. Pick an image per browser (chromium, chrome, edge, firefox, webkit) or multi. The base image is Ubuntu 26.04 and listens on PORT=3000. Typical settings are TOKEN, CONCURRENT, QUEUED, TIMEOUT, HEALTH=true, CORS, and STRICT_TOKEN_USE.
• From source. Node with npm install, npm run install:browsers (Playwright downloads), npm run build, then npm start. Docs are served at /docs; the debugger at /debugger when installed.
• Clients. Puppeteer connects to / or /chromium; Playwright connects to /<browser>/playwright. The Playwright client version is read from the User-Agent header to choose a matching Playwright server build.

Strengths and caveats

• Strength: drop-in for existing scripts. Change launch() to connect() and a Puppeteer or Playwright script runs remotely with queueing and limits.
• Strength: production hygiene. Strict schemas, health-gated admission, per-session temp dirs, orphan-browser cleanup, SSRF-style network blocking and metrics are already done.
• Strength: many engines. CDP and Playwright protocols across five browser families from one server.
• Caveat: one browser per connection. Every new session launches a fresh browser process. That is clean and isolated, but cold-start costs are paid each time; the keep-until timer exists but nothing in this repo sets it.
• Caveat: no data layer. No Markdown, no readability, no LLM extraction, no crawler, no proxy rotation and no CAPTCHA solving. Those are cloud features or your job.
• Caveat: small REST quirks. /content applies setJavaScriptEnabled only when it is truthy, so passing false does not disable JavaScript (content.http.ts).
• Caveat: licence. SSPL-1.0 or a commercial licence. Check whether SSPL’s terms fit your use before embedding it in a product or a hosted service.

Sources: code at f7edf0f, deepwiki-open wiki (10 pages), verified Q&A.