blitzbrowser/blitzbrowser: Deploy Headful Browser Fleets in Docker

blitzbrowser/blitzbrowser: Deploy Headful Browser Fleets in Docker^{↗ Bright Coding Blog}

Running browser automation at scale is a deceptively hard infrastructure problem. What starts as a simple puppeteer.launch() call quickly spirals into memory leaks, zombie Chrome processes, dependency management across environments, and the operational burden of keeping browsers alive under load. For teams doing web scraping, end-to-end testing, or any automation requiring realistic browser behavior, these issues aren't edge cases—they're daily realities.

blitzbrowser addresses this by packaging browser fleet management into a Docker container. Instead of embedding browser lifecycle logic in your application, you deploy blitzbrowser as a service and connect to it via the Chrome DevTools Protocol (CDP). Your code stays focused on automation logic; the container handles process cleanup, concurrency, queuing, and persistence.

This article walks through what blitzbrowser does, how it works, and whether it fits your stack. All details are sourced directly from the project's README and repository metadata.

What is blitzbrowser/blitzbrowser?

blitzbrowser is an open-source browser-as-a-service tool that deploys and manages headful browsers inside Docker containers. It exposes a WebSocket endpoint compatible with the Chrome DevTools Protocol, allowing any CDP-capable framework to connect and control browser instances remotely.

The project is hosted at https://github.com/blitzbrowser/blitzbrowser and is licensed under Apache License 2.0. As of its last commit on June 29, 2026, the repository has accumulated 262 stars and 14 forks, with Svelte identified as the primary language—likely for the management dashboard rather than the core container runtime.

The maintainer has posted an important notice: the project is no longer actively maintained. The README states that "web automation require too much time to maintain, it is a cat and mouse game." However, the repository will remain online because "some features are interesting to learn from." This status is critical context for teams evaluating blitzbrowser for production use. It may suit teams willing to fork and self-maintain, or those treating it as a reference architecture for their own browser infrastructure.

blitzbrowser sits in a category alongside commercial browser-grid services like Browserless, Scraping Browser, or self-managed solutions based on Selenium Grid. Its distinguishing claims: headful execution (not headless), direct CDP connectivity without proprietary SDKs, and built-in session persistence via S3-compatible storage.

Key Features

blitzbrowser's feature set targets the operational pain points of browser automation infrastructure:

Live View — Watch and interact with running browser instances through a visual interface. This is valuable for debugging failing automations or monitoring long-running sessions without attaching a separate VNC client.

Persistent Sessions — Browser user data (cookies, localStorage, IndexedDB, login state) can be persisted to S3-compatible storage. The README includes a Docker Compose example using RustFS, a self-hosted S3 alternative. This enables workflows where session state survives container restarts or gets shared across browser instances.

Proxy Support — HTTP proxy configuration at the browser level, allowing traffic routing through residential or datacenter proxies without modifying application code.

Security & Access Control — Authentication layer for both the browser connections and the management dashboard, configurable via environment variables.

Chrome DevTools Protocol (CDP) Native — No vendor-specific client libraries required. Connect directly from Puppeteer, Playwright, or any framework speaking CDP. This eliminates lock-in and reduces migration friction.

Version Flexibility — Run Google Chrome versions 116 through the latest release. This matters for testing against specific browser versions or avoiding regressions in newer Chrome releases.

Parallelism & Queueing — Launch multiple concurrent browser instances with automatic queueing for CDP connections while browsers initialize. The container manages resource allocation rather than pushing that complexity to client code.

Headful Execution — Browsers run with a real GUI inside a virtual display, not in headless mode. The README explicitly positions this as an anti-detection advantage versus headless automation.

Zero DevOps^{↗ Bright Coding Blog} Claim — The container bundles Chrome dependencies, process supervision, and cleanup logic. The maintainer's pitch: no custom scripts for zombie process reaping or Chrome dependency management.

Use Cases

blitzbrowser's architecture suits several concrete scenarios:

Web Scraping with Anti-Detection Requirements — Headless browsers carry detectable signals (user agent patterns, navigator.webdriver flags, missing plugins) that services like Cloudflare and Akamai use for blocking. Headful execution with a virtual display reduces these signals. Combined with HTTP proxy routing, this supports scraping workflows requiring higher success rates against protected sites. The README is explicit that this isn't a silver bullet—residential IPs, captcha solving, and human-like behavior patterns remain necessary.

End-to-End Testing at Scale — Teams running large Playwright or Puppeteer test suites can centralize browser infrastructure rather than launching browsers per-test or per-worker. The queueing and parallelism features align with CI/CD pipelines needing concurrent test execution without resource contention on individual runners.

Session-Based Automation — Workflows requiring maintained login state across runs benefit from S3-backed user data persistence. Examples include social media^{↗ Bright Coding Blog} automation, marketplace sellers managing multiple accounts, or any long-lived session where re-authentication is costly or triggers security challenges.

Browser Infrastructure Reference Architecture — Even with maintenance discontinued, the project's Docker packaging, process management approach, and CDP proxying implementation offer educational value for teams building similar systems. The S3 persistence and live view features demonstrate patterns applicable to custom solutions.

Cross-Language Automation Teams — Because blitzbrowser speaks CDP over WebSocket, it decouples browser infrastructure from client language. A single blitzbrowser deployment can serve Node.js, Python^{↗ Bright Coding Blog}, Java, Go, or Rust automation scripts without per-language Chrome installation.

Installation & Setup

blitzbrowser deploys as a single Docker container. The README provides exact commands—reproduced here without modification.

Basic Docker Run

docker run -p=9999:9999 --shm-size=2g ghcr.io/blitzbrowser/blitzbrowser:latest

The --shm-size=2g flag is critical: Chrome requires substantial shared memory for rendering, and Docker's default 64MB /dev/shm causes crashes or degraded performance. Port 9999 exposes the CDP WebSocket endpoint.

Docker Compose (Minimal)

services:
  blitzbrowser:
    image: ghcr.io/blitzbrowser/blitzbrowser:latest
    ports:
      - "9999:9999"
    shm_size: "2gb"
    restart: always

Docker Compose with S3 (RustFS) for User Data Persistence

The README includes a more complex setup using RustFS, a self-hosted S3-compatible object store. Before use, create a bucket named user-data through RustFS's console at http://localhost:9001.

services:
  blitzbrowser:
    image: ghcr.io/blitzbrowser/blitzbrowser:latest
    ports:
      - "9999:9999"
    environment:
      S3_ENDPOINT: http://s3:9000
      S3_ACCESS_KEY_ID: rustfsadmin
      S3_SECRET_ACCESS_KEY: rustfsadmin
      S3_USER_DATA_BUCKET: user-data
    shm_size: "2gb"
    restart: always
  s3:
    image: rustfs/rustfs
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      RUSTFS_VOLUMES: /data
      RUSTFS_ADDRESS: :9000
      RUSTFS_ACCESS_KEY: rustfsadmin
      RUSTFS_SECRET_KEY: rustfsadmin
      RUSTFS_CONSOLE_ENABLE: true
    restart: always
    volumes:
      - s3_data:/data
  # RustFS volume permissions fixer service
  volume-permission-helper:
    image: alpine
    volumes:
      - s3_data:/data
    command: >
      sh -c "
        chown -R 10001:10001 /data &&
        echo 'Volume Permissions fixed' &&
        exit 0
      "
    restart: "no"
volumes:
  s3_data:

Note the volume-permission-helper service—this addresses RustFS's UID/GID requirements by pre-setting ownership on the Docker volume before the main s3 service starts.

Real Code Examples

blitzbrowser requires minimal code changes to adopt. The README provides connection examples for major frameworks—reproduced below with context.

Puppeteer (Node.js)

The only change from standard Puppeteer usage: replace puppeteer.launch() with puppeteer.connect() pointing to the blitzbrowser WebSocket endpoint.

import puppeteer from 'puppeteer';

const browser = await puppeteer.connect({
    browserWSEndpoint: `ws://localhost:9999`
});

const context = await browser.createBrowserContext();
const page = await context.newPage();

// Your automation logic here

await browser.close();

browserWSEndpoint is the standard Puppeteer mechanism for connecting to remote or existing browser instances. blitzbrowser exposes this at the container's port 9999. Using createBrowserContext() rather than default contexts provides isolation between sessions.

Playwright + Node.js

Playwright's CDP connection uses connectOverCDP for Chromium-based browsers:

import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP(`ws://localhost:9999`);

const context = await browser.newContext();
const page = await context.newPage();

// Your automation logic here

await browser.close();

This mirrors Playwright's pattern for connecting to Chrome DevTools or existing Chrome instances. The ws:// scheme indicates WebSocket transport; for production deployments, TLS termination would upgrade this to wss://.

Playwright + Python

The README includes a Python async example, demonstrating blitzbrowser's language-agnostic design:

import asyncio
import os

from playwright.async_api import async_playwright

async def main():
    playwright = await async_playwright().start()

    browser = await playwright.chromium.connect_over_cdp("ws://localhost:9999")
    context = await browser.new_context()
    page = await context.new_page()

    # Your automation logic here

    await browser.close()
    await playwright.stop()

if __name__ == "__main__":
    asyncio.run(main())

Playwright + Java

For JVM-based stacks:

package com.example.demo;

import com.microsoft.playwright.Browser;
import com.microsoft.playwright.BrowserContext;
import com.microsoft.playwright.Page;
import com.microsoft.playwright.Playwright;

public class PlaywrightJavaExample {

    public static void main(String[] args) {
        try (Playwright playwright = Playwright.create();
             Browser browser = playwright.chromium().connectOverCDP("ws://localhost:9999")
        ) {
            BrowserContext context = browser.newContext();
            Page page = context.newPage();

            // Your automation logic here
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

These four examples represent the complete set provided in the README. No additional connection patterns are documented.

Advanced Usage & Best Practices

Based on the documented configuration options and architecture, several practices emerge:

Shared Memory Sizing — The 2GB --shm-size recommendation in the README is a minimum, not an optimum. Heavy pages with video, WebGL, or large DOM trees may require 4GB or more. Monitor container OOM kills as your primary scaling signal.

S3 Endpoint Security — The Docker Compose example uses plaintext HTTP for the internal S3 endpoint. For production, terminate TLS at a reverse proxy or use VPC-internal networking. The S3_ENDPOINT variable accepts any S3-compatible API, including AWS^{↗ Bright Coding Blog} S3, MinIO, or Ceph.

Authentication Configuration — Version 1.3.0 added authentication support; version 1.6.0 relaxed the HTTPS requirement for dashboard auth via HTTPS_DISABLED=true. The README notes this is environment-variable driven, suggesting review of the full security documentation for token or credential schemes.

Chrome Version Pinning — With support for versions 116+, teams can pin to a specific Chrome release for reproducibility. This trades security updates for stability—document your version policy and upgrade cadence.

Queue Behavior Under Load — The README mentions automatic queueing for CDP connections during browser startup. For high-concurrency workloads, monitor queue depth and browser pool warm-up time. The documentation does not specify queue limits or timeout behavior, so empirical testing is advised.

Maintenance Status Implications — With active maintenance discontinued, security patches for the base image, Chrome updates, and dependency vulnerabilities will not arrive automatically. Teams adopting blitzbrowser should plan for either forking and self-maintaining or treating it as a time-bounded solution.

Comparison with Alternatives

blitzbrowser's closest conceptual match is Browserless's self-hosted option, though Browserless adds API layers and management UI beyond raw CDP. Selenium Grid offers broader browser support (Firefox, Safari, Edge) but requires more infrastructure components. Playwright's official Docker images are simpler but lack blitzbrowser's persistence and proxy features out-of-box.

For teams already committed to CDP-native tooling and willing to accept maintenance responsibility, blitzbrowser's feature set remains competitive. For teams prioritizing vendor support and ongoing security patches, actively maintained alternatives warrant consideration.

FAQ

Is blitzbrowser actively maintained? No. The maintainer discontinued active development as of the README's important notice, citing the time burden of web automation's "cat and mouse game."

What license covers blitzbrowser? Apache License 2.0, permitting commercial use, modification, and distribution with attribution.

Does it work with frameworks other than Puppeteer and Playwright? Yes. Any framework using the Chrome DevTools Protocol can connect to blitzbrowser's WebSocket endpoint.

Can I run headless browsers instead? The README emphasizes headful execution as a design choice. Headless mode is not documented as a configuration option.

How does session persistence work? Browser user data is serialized to an S3-compatible bucket. The README provides a RustFS example; any S3 API should work.

What Chrome versions are supported? Versions 116 through the latest stable release, per version 1.5.0's changelog entry.

Is there a cloud-hosted version? The README mentions BlitzBrowser.com as a now-closed cloud offering. Only the self-hosted open-source version remains available.

Conclusion

blitzbrowser/blitzbrowser packages a specific, well-defined solution: headful browser fleets in Docker, accessible via standard CDP connections, with session persistence and proxy support. For teams struggling with browser process management in their automation infrastructure, it offers a credible architectural pattern—even if the implementation requires future self-maintenance.

The project's 262 stars and 14 forks suggest niche rather than mainstream adoption, which aligns with its specialized use case and now-unmaintained status. It suits teams with DevOps capacity to fork and evolve the codebase, or those seeking a reference implementation for their own browser-as-a-service layer.

If your stack relies on Puppeteer, Playwright, or any CDP framework, and you're evaluating whether to build or buy browser infrastructure, blitzbrowser merits review. Examine the source at https://github.com/blitzbrowser/blitzbrowser, test the Docker deployment against your workload, and assess whether the maintenance trade-offs fit your team's capacity. For related approaches to containerized browser infrastructure, see [INTERNAL_LINK: browser-automation-infrastructure].