Use Playwright in your app. Run browsers elsewhere.

BrowserThing is a self-hosted browser pool for Playwright applications. It keeps browsers running between short tasks, cleans up each session, and replaces each browser after a set number of sessions.

Your applications connect to one endpoint. Each worker keeps one browser running and gives every session its own context. After 50 sessions, a worker drains and starts a new browser.

Why a browser pool

Applications that run many short browser tasks, such as screenshots, PDFs, or checks, usually start with one of the first two approaches.

A new browser for each task

Every task waits for a browser to start and pays for the start in CPU time.

One browser that never stops

Memory use can grow over time. If the browser gets into a bad state, it stays there until someone restarts it.

A pool that recycles

Tasks use browsers that are already running. Each browser is replaced after a set number of sessions.

Keep your Playwright code

Change launch() to connect() with the BrowserThing URL. The browser steps stay in your application. BrowserThing selects a worker for the browser type and Playwright version, and relays the session.

  • Node.js, Python, Java, and .NET clients
  • Chromium, Firefox, and WebKit workers
  • Clients use Playwright 1.65, the same major and minor version as the workers
Connection examples
import { chromium } from 'playwright';

const browser = await chromium.connect('ws://localhost:8080', {
  headers: { Authorization: `Bearer ${process.env.BROWSERTHING_API_KEY}` },
});
try {
  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'preview.png' });
} finally {
  await browser.close();
}

Run the pool on your own machines

Start it locally

You need Docker with the Compose plugin and Node.js 20 or later.

  1. Download the Compose file

    curl -fsSLO https://mbroton.github.io/browserthing/downloads/docker-compose.yaml
    curl -fsSL --create-dirs -o worker/seccomp_profile.json \
      https://raw.githubusercontent.com/mbroton/browserthing/v0.10.0/worker/seccomp_profile.json
  2. Start the server, PostgreSQL, and a Chromium worker

    docker compose up -d --wait server
    export BROWSERTHING_API_KEY=$(docker compose exec -T server server apikey create --name quickstart)
    echo "WORKER_API_KEY=$BROWSERTHING_API_KEY" >> .env
    docker compose up -d
  3. Install the matching Playwright client

    npm install playwright@1.65.0
Read the quick start