Lightpanda Browser

What It Keeps

• HTML parsing (html5ever from Servo)
• JavaScript execution (V8)
• DOM tree + Web APIs
• HTTP networking (libcurl)
• Cookie / session management
• CDP server for tool compatibility

What It Throws Away

• CSS layout engine
• Visual rendering / compositing
• Image decoding
• Font shaping and rasterization
• GPU acceleration layer
• Media playback / WebRTC
• Extension system

Zig's Advantages for a Browser

• No hidden allocations — every byte of memory is explicit
• No garbage collector — deterministic, predictable performance
• Comptime — compile-time code execution for zero-cost abstractions
• C ABI compatible — direct FFI to libcurl, V8, html5ever
• Cross-compilation — build for Linux/macOS/ARM from any host

vs. C++ (Chrome/Firefox)

• No undefined behavior footguns
• No header file soup
• Explicit error handling (no exceptions)
• Built-in test runner
• Compiles 10-100x faster than C++

Lightpanda uses Servo's html5ever — the same spec-compliant HTML parser that powers Firefox's experimental engine.

• Written in Rust, called from Zig via C ABI
• Full HTML5 spec compliance
• Handles malformed HTML gracefully
• Builds a DOM tree that Zig code owns and manages

The Pipeline

// Simplified flow
Raw HTML bytes
    ↓
html5ever tokenizer
    ↓
html5ever tree builder
    ↓
Zig DOM tree
    ↓
Web API bindings
    ↓
V8 JavaScript context

What Works

• Full ES2024+ JavaScript execution
• DOM manipulation (createElement, querySelector, etc.)
• fetch() and XMLHttpRequest
• Promises, async/await
• setTimeout / setInterval
• Event listeners and dispatch

The Binding Challenge

V8's C++ API must be bridged to Zig. Lightpanda uses Zig's C ABI interop to create bindings that expose DOM objects as V8 JavaScript objects.

// Zig exposes DOM nodes to V8
// so JS like:
document.getElementById('app')
// resolves to a Zig-managed
// DOM node, not a C++ object

Rather than implementing HTTP/1.1, HTTP/2, TLS, and connection pooling from scratch, Lightpanda delegates to libcurl — the battle-tested C library powering billions of HTTP requests daily.

• HTTP/1.1 and HTTP/2 support
• TLS via OpenSSL/LibreSSL
• Cookie jar management
• Proxy support (HTTP, SOCKS5)
• Custom header injection
• Request interception — block, modify, or mock

Request Interception

One of Lightpanda's most useful features for automation:

// Via CDP, you can intercept
// any network request:

// Block images (save bandwidth)
page.setRequestInterception(true)
page.on('request', req => {
  if (req.resourceType() === 'image')
    req.abort()
  else
    req.continue()
})

How It Works

// Connect Puppeteer to Lightpanda
const browser = await puppeteer.connect({
  browserWSEndpoint:
    'ws://127.0.0.1:9222'
});

const page = await browser.newPage();
await page.goto('https://example.com');
const title = await page.title();

CDP Domains Supported

• Page — navigation, lifecycle events
• Runtime — JS evaluation
• DOM — tree inspection, manipulation
• Network — request interception
• Target — page/context management
• Input — keyboard/mouse events

Multiple concurrent CDP connections are supported within a single Lightpanda process.

Puppeteer (Full Support)

const puppeteer = require(
  'puppeteer-core'
);

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

// Use exactly like Chrome
const page = await browser.newPage();
await page.goto('https://...');
await page.click('#submit');

Playwright (Growing Support)

const { chromium } = require(
  'playwright'
);

const browser = await
  chromium.connectOverCDP(
    'http://127.0.0.1:9222'
  );

// Works, but Playwright may
// use different code paths as
// new APIs become available

Zig gives Lightpanda explicit control over every allocation. There is no hidden memory overhead from a garbage collector or runtime.

Allocator Strategy

• Arena allocators for per-page DOM trees — allocate fast, free all at once
• General purpose allocator for long-lived objects
• No GC pauses — deterministic latency
• Memory is freed the moment a page context closes

// Zig allocator pattern
const allocator = std.heap
    .page_allocator;

// Arena for a page session
var arena = std.heap
    .ArenaAllocator
    .init(allocator);
defer arena.deinit();

// All DOM nodes allocated here
// When page closes: one free()
const node = try arena
    .allocator()
    .create(DomNode);

Supported Web APIs

• document.querySelector() / querySelectorAll()
• document.getElementById()
• document.createElement()
• element.innerHTML / textContent
• element.getAttribute() / setAttribute()
• element.click()
• addEventListener() / dispatchEvent()
• window.location, window.history

The Coverage Challenge

The full Web API surface has hundreds of interfaces with thousands of methods. Lightpanda's approach:

• Implement the most-used APIs first
• Validate against Web Platform Tests (WPT)
• Prioritize APIs that AI agents and scrapers actually call
• Accept that full coverage is a multi-year journey

Unlike Chrome, which has no concept of robots.txt, Lightpanda has native support for respecting crawl directives.

# Start with robots.txt compliance
lightpanda --obey_robots

# Lightpanda will:
# 1. Fetch /robots.txt first
# 2. Parse Allow/Disallow rules
# 3. Block navigation to
#    disallowed paths
# 4. Respect Crawl-delay

Why This Matters

• AI agents scraping at scale must respect site policies
• Built-in is better than bolted-on — no chance of forgetting
• Avoids IP bans and legal issues
• Sets a precedent for responsible AI browsing

The Agent Loop

• LLM decides what action to take (click, type, navigate)
• Framework translates to Puppeteer commands
• Puppeteer sends CDP messages to Lightpanda
• Lightpanda executes and returns DOM state
• Framework extracts page content for the LLM
• LLM decides next action — repeat

Why Lightpanda Wins Here

• Instant startup — no Chrome boot overhead
• Low memory — run hundreds of agents on one box
• Embeddable — single binary, no Chrome install
• Deterministic — no rendering jitter or timing issues

Self-Hosted

# Docker (amd64 + arm64)
docker run -p 9222:9222 \
  ghcr.io/lightpanda-io/browser

# Binary (Linux x86_64, macOS arm64)
curl -L https://github.com/
  lightpanda-io/browser/
  releases/latest \
  -o lightpanda
chmod +x lightpanda
./lightpanda --host 0.0.0.0 \
  --port 9222

Lightpanda Cloud

Managed infrastructure — no servers to run:

const browser = await
  puppeteer.connect({
    browserWSEndpoint:
      'wss://cloud.lightpanda.io'
      + '?token=YOUR_TOKEN'
  });

// Supports both Lightpanda
// and Chrome backends
// for maximum compatibility

The cloud option gives you both engines — use Lightpanda for speed, fall back to Chrome for full rendering when needed.

Chrome spawns separate OS processes for each tab (renderer, GPU, utility). Lightpanda runs everything in a single process with multiple CDP connections.

Chrome's Model

Chrome (1 page = ~4 processes)
browser   PID 1001  120 MB
renderer  PID 1002   45 MB
gpu       PID 1003   30 MB
utility   PID 1004   12 MB
Total: ~207 MB for one page

Lightpanda's Model

Lightpanda (N pages = 1 process)
lightpanda PID 2001 24 MB
  - CDP session 1 (page A)
  - CDP session 2 (page B)
  - CDP session 3 (page C)
  ...
Total: ~24 MB for 100 pages

Lightpanda validates its implementation against the Web Platform Tests — the same test suite used by Chrome, Firefox, and Safari to ensure interoperability.

• Forked WPT repo with custom test harness
• Tests run against DOM, Fetch, Events, HTML parsing
• Incremental coverage — passing percentage grows with each release
• Ensures spec compliance, not just "it works for one site"

Requirements

• Zig 0.15.2 — the compiler
• Rust toolchain — for html5ever
• libcurl-dev — HTTP networking
• V8 build deps — JavaScript engine

# Clone and build
git clone https://github.com/
  lightpanda-io/browser.git
cd browser
zig build -Doptimize=ReleaseSafe

Multi-Language Build

The build system is notable for orchestrating three languages:

build.zig         // Zig build script
  → compiles Zig source
  → calls cargo for html5ever
  → links V8 static lib
  → links libcurl
  → single binary output

The License Choice

AGPL-3.0 is a strong copyleft license. If you modify Lightpanda and offer it as a service, you must open-source your changes.

• Free for self-hosted use
• Modifications must be shared if offered as a service
• Protects the project from closed-source forks
• Drives users toward Lightpanda Cloud for hassle-free use

Project Health