browserless

Browserless deploys headless browsers (Chromium, Chrome, Firefox, WebKit, Edge) as a containerized service you can run locally or in the cloud. Rather than managing browser binaries, dependency conflicts, or system configuration per host, you point your existing Puppeteer or Playwright scripts at a WebSocket endpoint and Browserless handles the rest — concurrency queuing, session lifecycle, crash recovery, and resource isolation.

The open-source edition ships as a Docker image with core browser automation: parallel session management, a real-time debug viewer, built-in font and emoji support, configurable timeouts, and ARM64 architecture support including Apple Silicon. It is fully compatible with unmodified Puppeteer and Playwright — no forked SDKs or custom clients required.

Beyond the free tier, Browserless offers commercial cloud and enterprise Docker editions with advanced capabilities: BrowserQL for CAPTCHA solving and bot-detection evasion, persistent browser sessions with up to 90-day cookie and localStorage retention, session replay with video playback, REST APIs for PDF and screenshot generation, residential proxy rotation, and a Model Context Protocol server for connecting AI assistants like Claude Desktop or Cursor directly to browser automation.

Built on TypeScript and Node.js with a modular, dependency-injected architecture, Browserless supports simultaneous Playwright CDP and WebSocket connections on the same server. It provides extensible lifecycle hooks, webhook alerting, Lighthouse performance auditing, and a dynamic OpenAPI schema generated at build time — making it suitable for both individual developers running quick automation tasks and enterprises operating high-throughput scraping or testing pipelines.

What You Get

• Parallel session management — Configurable concurrency limits and a built-in queue ensure multiple browser sessions run simultaneously without overwhelming host resources, with overflow requests held and retried automatically.
• Real-time debug viewer — A built-in web interface lets you inspect active browser sessions live, watching DOM state, network requests, and console output during script execution without modifying your automation code.
• Drop-in Puppeteer and Playwright compatibility — Connect any unmodified Puppeteer or Playwright script by changing only the browserWSEndpoint — no custom SDK, no code rewrites, no forked libraries.
• ARM64 architecture support — Native Docker images built for ARM64 platforms including Apple Silicon and AWS Graviton, with intelligent runtime detection that disables incompatible browser routes automatically.
• Crash-tolerant session handling — If a browser process crashes mid-session, Browserless recovers and continues without terminating client connections or requiring script restarts.
• Configurable timeouts and health checks — Per-session connection timeouts, idle timers, and health-check endpoints keep long-running automation tasks stable and observable.
• Webhook alerting — HTTP webhooks fire on queue saturation, session timeouts, errors, and health failures, enabling integration with monitoring systems and alerting pipelines.
• Lighthouse performance auditing — Run Google Lighthouse accessibility, performance, and SEO audits through the same Browserless endpoint used for automation, with no separate infrastructure.
• Chrome Extensions support — Load custom browser extensions — including ad blockers and CAPTCHA solvers — directly into managed browser instances for enhanced scraping and testing.
• BrowserQL anti-detection engine — A cloud and enterprise feature that randomizes browser fingerprints, routes through residential proxies, and solves CAPTCHAs to bypass bot detection without manual intervention.
• Persistent browser sessions — Retain cookies, localStorage, and browser cache across separate sessions for up to 90 days, reducing repeated authentication and bot-check overhead.
• REST APIs for common tasks — Dedicated HTTP endpoints for screenshot generation, PDF rendering, HTML extraction, and structured data scraping require no browser automation code at all.

Common Use Cases

• Automated screenshot and PDF generation — A SaaS invoicing platform uses the Browserless /pdf REST endpoint to render HTML templates into branded PDF invoices, passing dynamic data via POST body and receiving binary output without managing a Chrome binary.
• UI test execution in CI/CD pipelines — A DevOps team runs Playwright integration tests against a Browserless container in GitHub Actions, eliminating browser dependency installation from CI runners and ensuring consistent cross-browser environments.
• High-volume web scraping at scale — A price intelligence startup routes hundreds of concurrent Puppeteer scrapers through Browserless, using the built-in concurrency queue to pace requests and the residential proxy integration to rotate IPs and avoid bans.
• Dynamic content scraping for LLM pipelines — A data engineering team uses the /crawl REST API to asynchronously spider competitor documentation sites, receiving structured JSON output that feeds directly into a retrieval-augmented generation system.
• Headless browser automation for enterprise workflows — A financial services firm deploys the Browserless Enterprise Docker image on-premise, automating report extraction from internal portals that require full JavaScript rendering, while keeping all browser traffic within their private network.
• AI assistant browser control via MCP — A developer connects Claude Desktop to the Browserless MCP server, allowing the AI to navigate web pages, fill forms, and extract content as part of multi-step agentic workflows without writing automation scripts manually.

Under The Hood

Architecture Browserless employs a layered, dependency-injected architecture centred on a single Browserless class that coordinates independently scoped components — BrowserManager, Limiter, Router, Metrics, Monitoring, WebHooks, and Hooks — each constructed once and wired together at startup. Routes are class instances extending abstract HTTPRoute or WebSocketRoute base classes, discovered dynamically from the filesystem rather than registered imperatively, which means new browser types and endpoints can be introduced without modifying core server logic. HTTP and WebSocket handling paths are cleanly separated, with a shim layer handling backward-compatible request preprocessing before routes execute. Browser drivers (ChromiumCDP, ChromiumPlaywright, FirefoxPlaywright, WebKitPlaywright) are abstracted behind common interfaces, letting the router dispatch to the correct browser type based on the request path without coupling to any single protocol. ARM64 architecture detection runs at boot, automatically disabling browser routes whose executables are unavailable on the current platform — a rare example of capability-driven route registration.

Tech Stack The server is written in TypeScript targeting ES2022 modules, compiled with tsc and post-processed by a custom esbuild pipeline that handles browser-specific polyfilling and bundle generation. It integrates puppeteer-core with the puppeteer-extra-plugin-stealth extension and multiple pinned versions of playwright-core (1.57 through 1.61) via npm aliases, supporting simultaneous Chromium, Firefox, and WebKit targets from a single process. Request validation uses JSON Schema definitions generated by typescript-json-schema at build time, producing OpenAPI and Chrome DevTools Protocol spec documents automatically. WebSocket proxying relies on http-proxy, concurrency queuing on the queue library, system health monitoring on systeminformation, and webhook delivery on the native fetch API. ESLint with TypeScript rules, Prettier, Mocha, Chai, Sinon, and c8 coverage form the development and quality toolchain.

Code Quality The codebase maintains extensive test coverage across core modules — limiter, router, metrics, monitoring, network security, and shim — with integration-style tests that exercise HTTP response codes, header validation, AbortController lifecycle, and token authentication end-to-end. Dependency injection throughout makes individual components independently testable without running a live browser. Error handling uses typed custom error classes (ServerError, BadRequest, TooManyRequests) and structured debug logging via the debug library, ensuring client-facing messages are meaningful and internal failures are diagnosable. TypeScript strict mode and interface contracts enforce API boundaries between components at compile time. A handful of @ts-ignore annotations exist at the external hook import boundary, but these are isolated and documented as intentional backward-compatibility shims rather than systemic type evasion.

What Makes It Unique Browserless bridges the CDP and Playwright WebSocket protocols on the same server, allowing legacy DevTools clients and modern Playwright browser instances to coexist on a single endpoint without separate deployments. The dynamic route registration system means cloud and enterprise editions extend the open-source base by adding route files — the BrowserQL engine, persistent sessions, and REST scraping APIs are additive layers, not forks. The lifecycle hooks system (before, after, page, browser) loaded from external files enables downstream Docker images to inject custom authentication, request filtering, and telemetry without modifying core source, a pattern that powers Browserless’s own enterprise edition. Supporting five simultaneously pinned Playwright versions via npm aliases is an unusual dependency strategy that lets enterprise customers pin to a specific Playwright version for reproducible automation without upgrading the server.

Self-Hosting

Browserless is dual-licensed under the MongoDB Server Side Public License (SSPL-1.0) and a commercial Browserless license. The SSPL is a copyleft license with a specific network-service provision: if you use Browserless to offer a service to third parties (a scraping API, a testing platform, a browser-as-a-service product), the SSPL requires you to open-source the entire software stack used to deliver that service — not just your modifications to Browserless itself. For internal use — running Browserless to automate your own workflows, generate your own reports, or run your own tests — the SSPL is effectively permissive. For any commercial product or closed-source CI system built on top of it, a commercial license from browserless.io is required.

Self-hosting the open-source edition requires Docker and a machine with sufficient RAM to run concurrent browser instances — Chrome is memory-intensive, and high concurrency multiplies that cost quickly. You are responsible for maintaining the Docker image versions, applying security patches, managing persistent storage for session state if needed, and monitoring browser process health. The built-in health check endpoints and webhook alerting give you hooks into the system, but operational observability beyond that — log aggregation, metrics dashboards, alerting thresholds — must be assembled yourself. Scaling across multiple hosts requires an external load balancer and session affinity or stateless automation patterns, as the open-source edition does not include distributed coordination.

The managed cloud and enterprise Docker editions add capabilities that are non-trivial to replicate in self-hosted deployments: BrowserQL’s fingerprint randomization and CAPTCHA solving pipeline, residential proxy networks with automatic IP rotation, persistent session storage across request boundaries, session video replay, and the MCP server for AI integrations. The cloud edition removes operational burden entirely — no Docker management, automatic scaling, SLA-backed uptime, and built-in proxy infrastructure. The enterprise Docker edition provides the same premium feature set in a self-hosted container suitable for data-sovereign environments, with priority support and the ability to modify and fork the source under commercial terms. For teams whose primary constraint is compliance or network isolation rather than operational capacity, the enterprise Docker image is the practical middle path.