Lightpanda: the Headless Browser for AI Agents

TL;DR

Lightpanda is a purpose-built headless browser for AI agents written in Zig. It runs 11× faster than Chrome, uses 9× less memory, and speaks Chrome DevTools Protocol (CDP) natively, so existing automation frameworks such as Puppeteer, Playwright, and chromedp can connect without changing their core CDP workflow.

Try Apidog today

Running hundreds of Chrome instances in production for AI agents can become an operational liability. Lightpanda is built from scratch in Zig for server-side automation, with reported 11× faster execution and 9× lower memory consumption than Chrome. If you build automated pipelines, LLM-driven scrapers, or end-to-end test suites, use Lightpanda as the browser layer and Apidog to design, mock, and validate the APIs those workflows depend on.

Before running Lightpanda in serve, fetch, or mcp mode, configure your API mocks and expected responses in Apidog. You can then intercept browser requests, route them to deterministic mock endpoints, and validate responses without relying on live backend services.

Why use a new headless browser for AI agents?

Chrome and Chromium are proven choices for browser automation, but their desktop-oriented architecture becomes costly at scale.

Common constraints include:

• Memory use: A single Chrome instance can consume 200–400 MB while idle.
• Cold-start time: Starting Chrome takes seconds, which is significant for short-lived jobs such as fetching a page or extracting structured data.
• Operational overhead: Server deployments often require flags such as --no-sandbox, --disable-dev-shm-usage, and GPU-related options.

This also affects API-driven frontend testing. Apidog can define, mock, and test an API contract precisely, but a JavaScript-rendered UI still needs a browser to exercise that contract. A lighter browser runtime can reduce the cost of running those integration checks in CI.

Lightpanda is not a fork of Chrome or WebKit. It is a clean-room headless browser implementation written in Zig, designed specifically for automated, server-side, AI-driven web interaction.

What makes Lightpanda different?

Performance characteristics

Lightpanda reports the following benchmark comparison from its project test suite:

Metric	Chrome	Lightpanda
Execution speed	1×	11× faster
Memory per instance	1×	9× less
Startup time	Seconds	Near-instant

For browser-based integration tests, lower per-worker memory use can let you run more parallel workers on the same CI hardware.

JavaScript and browser APIs

Lightpanda uses the V8 JavaScript engine through a native Zig bridge. Its supported browser capabilities include:

• ES2024 JavaScript execution
• fetch and XMLHttpRequest
• localStorage, sessionStorage, and partial IndexedDB support
• MutationObserver, IntersectionObserver, and requestAnimationFrame
• A DOM implementation with live NodeList and HTMLCollection
• Cookie persistence across navigations

That matters when a page calls a mocked API, follows authentication redirects, loads hydrated application state, or makes several XHR requests after the initial navigation.

Native Chrome DevTools Protocol support

Lightpanda implements 22 CDP domains, including:

• Page
• Runtime
• DOM
• Network
• Input
• Fetch
• CSS
• Accessibility
• Emulation

In practice, this means CDP clients can target Lightpanda at ws://127.0.0.1:9222 rather than a Chrome debugging endpoint.

How Lightpanda processes a page

Lightpanda runs a WebSocket server that speaks the Chrome DevTools Protocol. When an automation client sends Page.navigate, the browser:

1. Fetches the URL through its libcurl-based HTTP client, with HTTP/1.1, HTTP/2, and BoringSSL-backed TLS support.
2. Parses HTML with html5ever, an HTML5-compliant parser.
3. Constructs a DOM tree.
4. Executes page JavaScript in a V8 isolate.
5. Processes microtask and macrotask queues until the page settles.
6. Returns control to the client through CDP.

The process runs without a GPU or display server, which is useful for server-side automation and CI workloads.

Redirect browser requests to an Apidog mock server

Lightpanda's Network and Fetch CDP domains support request interception. Use interception to:

• Redirect calls to an Apidog mock server.
• Block analytics and tracking requests during tests.
• Assert on request headers and payloads.
• Keep browser tests isolated from live services.

The implementation pattern is:

1. Define the API contract and mock response in Apidog.
2. Start Lightpanda as a CDP server.
3. Intercept requests from the browser client.
4. Rewrite API requests to the mock server.
5. Assert on the rendered page state.

Choose a runtime mode

serve mode for CI and persistent automation

Start a CDP server:

./lightpanda serve --host 127.0.0.1 --port 9222

Use this mode for long-running test suites or services that create multiple browser sessions.

fetch mode for one-shot rendering

Fetch a page and print its rendered HTML:

./lightpanda fetch --url https://example.com

This is useful for pipelines that need JavaScript-rendered HTML without maintaining a persistent browser process.

mcp mode for LLM tool use

Start the Model Context Protocol server:

./lightpanda mcp

mcp mode exposes browser actions such as navigation, clicking, typing, and querying as structured tool calls. This avoids writing CDP boilerplate when an LLM agent needs browser access.

Connect Puppeteer to Lightpanda

Start Lightpanda first:

./lightpanda serve --host 127.0.0.1 --port 9222

Then connect puppeteer-core to its CDP endpoint:

import puppeteer from "puppeteer-core";

// Connect to Lightpanda's CDP server instead of Chrome.
const browser = await puppeteer.connect({
  browserWSEndpoint: "ws://127.0.0.1:9222",
});

const page = await browser.newPage();

// Redirect application API calls to an Apidog mock server.
await page.setRequestInterception(true);

page.on("request", (request) => {
  if (request.url().includes("api.yourapp.com")) {
    request.continue({
      url: request.url().replace("api.yourapp.com", "localhost:4523"),
    });
    return;
  }

  request.continue();
});

await page.goto("https://your-app.com/dashboard");

// Extract page state for validation or downstream processing.
const data = await page.evaluate(() => ({
  title: document.title,
  apiResponse: window.__INITIAL_STATE__,
}));

console.log(data);

await browser.close();

The Puppeteer API usage stays the same; the main change is the CDP endpoint. The interception handler makes the Apidog mock server the deterministic source of API responses for the browser test.

Test Lightpanda and your integration pipeline

Lightpanda includes unit-test support through its Zig build system:

# Run all unit tests.
make test

# Run a filtered subset.
make test F="dom"

# Filter with an environment variable.
TEST_FILTER=network make test

A practical integration-test flow looks like this:

1. Define and mock the API contract in Apidog.
2. Start Lightpanda in serve mode.
3. Connect a Puppeteer or Playwright CDP client.
4. Redirect frontend API calls to the mock server.
5. Navigate to the UI state under test.
6. Assert that the DOM reflects the expected mocked response.

This separates API contract validation, browser execution, and UI assertions while keeping the test environment deterministic.

Conclusion

Lightpanda is a Zig-based headless browser for AI agents that reports 11× faster execution and 9× lower memory use than Chrome, while exposing a native CDP interface for existing automation tooling.

For teams using Apidog to design, mock, and validate APIs, Lightpanda can provide a lighter browser layer for exercising JavaScript-rendered frontends against mocked API contracts.

To get started:

• Install Lightpanda from lightpanda.io for Linux x86_64 or macOS aarch64.
• Start a CDP server on ws://127.0.0.1:9222.
• Connect Puppeteer or Playwright through CDP.
• Redirect intercepted application requests to your Apidog mock server.
• Run ./lightpanda mcp when an LLM agent needs structured browser tools.

FAQ

Is Lightpanda a fork of Chrome or Chromium?

No. Lightpanda is an independent headless browser written in Zig. It uses V8 for JavaScript execution and html5ever for HTML parsing, while its DOM, networking, event system, and layout logic are clean-room implementations.

Does Lightpanda work with Apidog mock servers?

Yes. Use the CDP Network and Fetch domains to intercept outbound requests and redirect them to an Apidog mock endpoint.

Can I use Playwright instead of Puppeteer?

Playwright supports CDP-based connections, so it can use Lightpanda as a CDP target. Check the Lightpanda README for compatibility details and known caveats related to Playwright-specific protocol extensions.

What does mcp mode do?

mcp mode starts a Model Context Protocol server that exposes browser actions—including navigation, clicking, typing, and querying—as structured tool calls for LLMs.

How do I run tests for a specific Lightpanda module?

Use a filter:

make test F="module-name"

Or set TEST_FILTER before running the suite:

TEST_FILTER=network make test

Is Lightpanda production-ready?

Lightpanda is under active development, licensed under AGPL-3.0, and maintained by Selecy SAS. It passes a substantial portion of the Web Platform Tests and is used in production scraping and AI automation workloads. Review the project's WPT dashboard for current specification compliance before using it in critical workflows.