Screenpool

Why?

Spawning and killing Chromium processes on every render job creates high CPU overhead and memory leaks. Screenpool launches Chromium once and allocates concurrent jobs to a fixed pool of isolated context tabs, recycling contexts on crash/timeout and blanking pages after runs to guarantee bounded resource usage.

Features

• Fixed tab budget — Launches a single browser process and keeps context tabs open. No per-job process creation.
• Model Context Protocol (MCP) Server — Built-in stdio MCP server for AI coding assistants (Claude Code, Cursor, VS Code, Antigravity, etc.) with 6 tools.
• Cross-Platform Auto-Discovery & Auto-Install — Automatically detects system Chrome/Chromium on macOS, Linux, Windows, and PATH, with zero-config auto-download fallback.
• Reset after jobs — Clears cookies, local headers, viewport overrides, custom styles, and navigates to about:blank to free up DOM nodes.
• Remote Debugging & Connection — Connects to existing Chrome/Chromium instances via WebSocket (browserWSEndpoint), HTTP URL (browserURL), or passes an existing Puppeteer Browser directly.
• Data Extraction — Supports structured data extraction using Pipsel DSL rules.
• SSRF Guard — Disallows local networks, loopbacks, and metadata IPs by default.
• V8 Heap & RSS limit — Monitors worker RSS memory and rejects jobs or recycles workers when limits are exceeded.
• HTTP Daemon & CLI UI — Includes a Hono-powered HTTP server, daemon management (unitup), and an admin panel GUI.

Installation

Requires Node.js 20+.

npm install screenpool

Note: Screenpool automatically discovers installed Chrome/Chromium on macOS, Linux, Windows, or PATH. If no browser is found, it automatically downloads chrome@stable into ~/.screenpool/browser on first run.

Quick start

import { ScreenPool } from 'screenpool';

// Create a pool
const pool = new ScreenPool({
  browser: 'chrome@stable',
  poolSize: 4,
  memory: { limitMb: 512 }
});

await pool.start();

// Take a screenshot
const result = await pool.screenshot({
  url: 'https://example.com',
  viewport: { width: 1200, height: 630 },
  format: 'webp',
  quality: 80
});

// Do something with the buffer
console.log(result.buffer); // => 
console.log(result.contentType); // => 'image/webp'

// Stop the pool gracefully
await pool.stop();

Browser Connection Options

Screenpool supports several ways to resolve or connect to a browser. Define these in the top-level configuration options:

API Reference

new ScreenPool(config)

Methods

• async pool.start()

  Launches/connects the browser process and initializes the fixed worker page pool.

• async pool.stop()

  Closes all worker contexts and gracefully terminates the browser process (if started locally) or disconnects (if connected remotely).

• async pool.screenshot(options)

  Captures a screenshot of the specified URL or raw HTML template content. Returns RenderResult.

  const res = await pool.screenshot({
    url: 'https://example.com',
    format: 'png',      // 'png' | 'jpeg' | 'webp'
    quality: 90,        // for jpeg/webp
    fullPage: true,     // captures entire scrollable page height
    darkMode: true,     // injects color preference
    userAgent: 'my-custom-ua',
    headers: { 'Authorization': 'Bearer ...' },
    cookies: [{ name: 'session', value: '...' }]
  });

• async pool.pdf(options)

  Generates a PDF from a URL or raw HTML content. Returns RenderResult.

  const res = await pool.pdf({
    url: 'https://example.com',
    pdf: {
      format: 'A4',
      landscape: false,
      printBackground: true,
      margin: { top: '1cm', bottom: '1cm' }
    }
  });

• async pool.extract(options)

  Extracts structured data from HTML pages rendered in the browser using Pipsel DSL.

  const result = await pool.extract({
    url: 'https://news.ycombinator.com',
    rules: `
      stories[]: "tr.athing" {
        id: self | attr("id") | int
        title: "span.titleline > a" | text
      }
    `
  });
  console.log(result.data.stories); // => [{ id: 40912, title: "..." }]

• pool.stats()

  Returns statistics regarding completed jobs, active queues, browser restarts, and memory utilization.

• async pool.getPageStats()

  Count of total open tabs and contexts across default context vs. worker contexts (primarily used for memory leak analysis).

Browser Action Architecture & Record API

Screenpool provides a strict, observation-based browser action engine and session recorder for interactive multi-step flows, popup windows, OAuth logins, and web recording.

Session API Example

import { ScreenPool } from 'screenpool';

const pool = new ScreenPool({ poolSize: 2 });
await pool.start();

// 1. Create an isolated session
const session = await pool.sessions.create({
  pages: { maxPages: 5, onPopup: 'register', onActivePageClosed: 'activate-opener' },
});

// 2. Start recording
const recording = await session.record.start({ preset: 'debug', screenshots: 'each-action' });

// 3. Navigate and Observe
await session.goto('https://example.com');
const obs = await session.observe({ screenshot: true, elements: true });

// 4. Execute Action Sequence
const actResult = await session.act({
  observationId: obs.id,
  actions: [
    {
      type: 'click',
      target: { by: 'role', role: 'button', name: 'Open Auth' },
      expect: { page: { event: 'popup', alias: 'oauth-login', activate: true } }
    }
  ]
});

// 5. Stop Recording & Close
const manifest = await recording.stop();
await session.close();
await pool.stop();

Security (SSRF Protection)

Chromium renders page links on your server. To prevent users from requesting internal resources, Screenpool includes built-in SSRF checks blocking loopback interfaces (localhost, 127.0.0.1), private IPs (10.0.0.0/8, 192.168.0.0/16), link-local subnets, and AWS/cloud metadata services (169.254.169.254).

To allow local testing or developer instances, enable access explicitly during initialization:

const pool = new ScreenPool({
  allowLocalhost: true,        // Allow localhost and loopback resolving
  allowPrivateNetworks: true,  // Allow access to standard private ranges (192.168.X.X, etc.)
  allowFileProtocol: true      // Allow opening file:// paths on the host system
});

HTTP Server

Screenpool packages a Hono-based HTTP server to daemonize screenshotting and rendering services.

import { ScreenPool } from 'screenpool';
import { createScreenPoolServer } from 'screenpool/http';

const pool = new ScreenPool({ browser: 'chrome@stable' });
await pool.start();

const server = createScreenPoolServer(pool, { port: 3000, host: '0.0.0.0' });
await server.listen();

API Endpoints

Model Context Protocol (MCP) Server

Screenpool includes built-in Model Context Protocol (MCP) server capabilities over stdio. This enables AI coding assistants (Claude Code, Cursor, VS Code MCP clients, Antigravity, etc.) to perform web rendering, screenshot capture, PDF generation, HTML extraction, and health monitoring.

Quick Run

# Run MCP server via npx
npx screenpool mcp

# Run using installed binary
screenpool mcp

# Standalone binary
screenpool-mcp

MCP Tools

Client Configuration Example

{
  "mcpServers": {
    "screenpool": {
      "command": "npx",
      "args": [
        "-y",
        "screenpool",
        "mcp",
        "--pool-size",
        "3",
        "--timeout",
        "30000"
      ]
    }
  }
}

CLI Reference

Command line interface tools for quick scripts, daemons, and MCP server:

# Start MCP Server for AI tools over stdio
screenpool mcp --pool-size 3 --timeout 30000

# Take a screenshot and write to out.png
screenpool screenshot https://example.com --out out.png --width 1280 --height 720

# Connect to an existing browser via remote debugging and take a screenshot
screenpool screenshot https://example.com --browser-url http://localhost:9222 --out out.png

# Render a PDF using a custom Chromium binary path
screenpool pdf https://example.com --executable-path /usr/bin/chromium --out page.pdf

# Start HTTP Server daemon on port 3000
screenpool server --port 3000 --pool-size 4

# Start server daemon with interactive web UI panel
screenpool ui --port 3000

Architecture

┌────────────────────────────────────────────────────────────────┐
│                          ScreenPool                            │
├────────────────────┬────────────────────┬──────────────────────┤
│    JobQueue        │   HealthMonitor    │    WorkerPool        │
│                    │                    │  ┌────────────────┐  │
│  [Job1, Job2...]   │  (Memory / RSS)    │  │ ScreenWorker 0 │  │
│                    │                    │  │ ScreenWorker 1 │  │
│                    │                    │  │ ScreenWorker 2 │  │
│                    │                    │  │ ScreenWorker 3 │  │
│                    │                    │  └────────────────┘  │
├────────────────────┴────────────────────┴──────────────────────┤
│                        BrowserManager                          │
├────────────────────────────────────────────────────────────────┤
│            Puppeteer (Connect/Launch Contexts)                 │
├────────────────────────────────────────────────────────────────┤
│                    Chromium Browser Process                    │
└────────────────────────────────────────────────────────────────┘

Development & testing

The codebase uses Vitest for integration and unit testing.

npm run test
npm run test:watch

Build output files using tsup before distributing: npm run build.