Lightpanda: Headless Browser for AI Agents and Automation

What Lightpanda is

Lightpanda is a headless web browser written from scratch in Zig and aimed squarely at machines rather than people: AI agents, crawlers, test runners and other automation that needs to load real web pages, execute their JavaScript and read the resulting DOM. The project is explicit about what it is not. It is not a Chromium fork and not a WebKit patch; it is a new browser engine that skips the parts a human-facing browser needs and keeps the parts an automation workload uses.

The problem it targets is familiar to anyone who has run headless Chrome at scale. Plain HTTP requests stopped being enough once most of the web moved to Ajax, single-page apps, infinite scrolling and client-side frameworks such as React, Vue and Angular. The usual answer is to run a full desktop browser on a server in headless mode, which works but scales poorly. The README lists the pain points directly: Chrome is heavy on RAM and CPU, hard to package, deploy and maintain at scale, and carries many features that are unnecessary in headless mode. Lightpanda's answer is to build a browser that still runs JavaScript properly but has no graphical rendering engine at all.

The audience is developers building scraping and data-extraction pipelines, teams running end-to-end automation in CI, and anyone wiring a browser into an LLM agent through the Model Context Protocol. Because Lightpanda speaks the Chrome DevTools Protocol (CDP), existing Puppeteer and Playwright scripts can connect to it by changing the endpoint they connect to, which makes it possible to trial it without rewriting automation code.

How it works

Under the hood Lightpanda assembles a browser from a small set of well-known components and its own Zig code. The README's status list names the pieces: an HTTP loader built on libcurl, an HTML parser from html5ever (the Servo project's parser), a DOM tree and DOM APIs implemented in the project, and JavaScript execution through V8. On top of that sit XHR and the Fetch API, cookies, custom HTTP headers, proxy support, network interception, CORS, an adblocker, and form input and click handling.

What is missing is the rendering pipeline. There is no compositor, no GPU path and no pixel painting of the kind a desktop browser does for a screen. That omission is the main source of the project's resource claims: a browser that never paints does not pay for painting. Lightpanda does still compute enough layout information for automation to behave sensibly. The 1.0 release notes describe work on the style cascade, resolving width and height from stylesheet rules, measuring wrapped text for an element's content height, and scroll-container handling, so scripts that depend on element sizes or scrolling are not left with zeroes everywhere.

The project uses V8 snapshots. By default a snapshot is created on startup, but the build can embed a pre-generated snapshot binary to avoid that step. Language selection comes from a --locale flag, and since 1.0 the old implicit English fallback has been removed.

Lightpanda exposes that engine through several front doors, all in one binary:

• fetch loads a single URL and dumps the result to stdout as HTML, Markdown, a PNG or PDF of a text-only rendering, or structured data (JSON-LD, OpenGraph, Twitter cards, meta and link tags as JSON).
• serve starts a long-running server that speaks CDP over WebSockets, WebDriver BiDi, or both, on a TCP port or a Unix-domain socket.
• mcp runs a Model Context Protocol server over stdio or HTTP so AI applications can call browser tools directly.
• agent starts an interactive agent that drives the browser from natural-language instructions or slash commands, optionally without any LLM.
• run executes a recorded PandaScript file, the deterministic output of an agent session.

Correctness is measured against the standard Web Platform Tests. The team runs a fork of WPT with a custom report harness and publishes the results daily, which is a more honest compatibility signal than a list of supported sites.

Key features

• Not based on Chromium, Blink or WebKit. The engine is new code in Zig, a low-level language with explicit memory control, combined with V8, libcurl and html5ever.
• CDP compatibility. Puppeteer connects through browserWSEndpoint, so existing scripts mostly keep working with a one-line change to how the browser is launched.
• WebDriver BiDi and classic WebDriver. --protocol webdriver enables BiDi, and CDP and BiDi can run together. The 1.0 release also built classic HTTP WebDriver into a usable driver with session management, navigation, element endpoints, input, cookies and viewport endpoints.
• Multiple dump formats. fetch --dump supports html, markdown, png, pdf and structured_data, with --wait-until, --wait-ms, --wait-selector and --wait-script to control when the dump happens.
• robots.txt support. The --obey-robots option makes the browser respect a site's robots.txt, and the README examples use it throughout.
• CORS enforced by default. Since 1.0, cross-origin fetch and XHR requests that fail a CORS check are blocked, matching what a normal browser does. It can be switched off with --disable-features cors.
• Native MCP server. Over HTTP, each client connection gets its own browsing session with its own page, cookies and memory, tracked through the Mcp-Session-Id header. Agents can share a session deliberately by sending the same id, and session_new, session_list and session_close tools manage sessions explicitly.
• Built-in agent. lightpanda agent runs the LLM-driven loop inside the browser process, so every tool call is a direct operation rather than a serialized CDP round trip.
• PandaScript. Agent sessions export to vanilla JavaScript with a few native browser primitives, which can be replayed with lightpanda run without a model at runtime.
• Broad LLM provider support. The agent supports Anthropic, OpenAI, Gemini, Google Vertex AI, Mistral, Hugging Face, Vercel AI Gateway, OpenRouter, any OpenAI-compatible endpoint via OPENAI_BASE_URL, and local models via Ollama, llama.cpp or LLMD.
• Network controls. Proxy support, custom headers, network interception and an adblocker are part of the core feature list.
• Shell completion. lightpanda completion prints completion scripts for bash, fish and zsh.

Performance claims

The headline numbers on the README are the project's own: "16x lighter and 9x faster than Chromium." The benchmark behind them requests 933 real web pages over the network from an AWS EC2 m5.large instance, and the methodology is published in the lightpanda-io/demo repository. For 100 pages the README reports peak memory of 123MB for Lightpanda against 2GB for headless Chrome, and execution time of 5 seconds against 46 seconds.

These figures are worth treating as a starting hypothesis rather than a guarantee. They come from one workload, one instance type and the vendor's own harness. A page that leans heavily on APIs Lightpanda implements partially, or a pipeline whose time is dominated by network latency rather than browser overhead, will see different results. The sensible approach is to run the same job against both browsers with the target site list and compare memory per worker and pages per minute directly.

Getting started

Lightpanda ships nightly builds for Linux and macOS on both x86_64 and aarch64, plus Homebrew, AUR, Nix and Docker options. On macOS or Linux with Homebrew:

brew install lightpanda-io/browser/lightpanda

Or download the Linux binary directly and verify it:

curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && \
chmod a+x ./lightpanda

./lightpanda version

With Nix, the flake can be run without downloading a binary:

nix run github:lightpanda-io/browser -- --help

The official Docker image starts a container that exposes the CDP server on port 9222, bound to localhost:

docker run -d --name lightpanda -p 127.0.0.1:9222:9222 lightpanda/browser:latest

To dump a page, run fetch. This example from the README obeys robots.txt and prints the rendered HTML:

./lightpanda fetch --obey-robots --dump html --log-format pretty  --log-level info https://demo-browser.lightpanda.io/campfire-commerce/

To use Lightpanda from Puppeteer or Playwright, start the CDP server:

./lightpanda serve --obey-robots --log-format pretty  --log-level info --host 127.0.0.1 --port 9222

A Puppeteer script then connects with puppeteer.connect({ browserWSEndpoint: "ws://127.0.0.1:9222" }) and the rest of the script stays the same. For AI tooling, the MCP server is added to an MCP configuration with the binary path as the command and mcp as the argument, or started over HTTP for several agents at once:

lightpanda mcp --port 9223

The agent can be started interactively, given a one-shot task, or run without an LLM:

./lightpanda agent --task "top story on news.ycombinator.com?"

./lightpanda agent --no-llm

Without an explicit choice, the agent picks a provider in a fixed order: the provider last selected with /provider (remembered per directory in .lp-agent.zon, as long as its key is still set), then the first API key found in the environment, then a running local Ollama or llama.cpp server. The --effort flag sets the per-turn reasoning budget for thinking models; the docs note the REPL defaults to low while --task defaults to medium.

Agent mode and PandaScript

The agent is the most distinctive part of recent releases. The documentation describes three layers: the browser itself, a runtime of native tools (goto, click, fill, extract, evaluate, search and more, each also available as a slash command), and an optional LLM that interprets natural-language requests and decides which tools to call. The docs frame it as directing a robot to use the web rather than chatting with a bot.

Data extraction goes through /extract, which takes a JSON schema describing which selectors map to which fields. The output of a session can be saved with /save as a PandaScript and replayed later with lightpanda run. That is the practical point: an engineer can prototype a flow with an LLM in the loop, then ship the recorded script to production where it runs deterministically and costs no tokens.

PandaScript has a deliberately narrow runtime. Scripts run in their own V8 context that is separate from the page's JavaScript context. There is no window, document or localStorage in the script, and it is not Node.js either: no require, process, fs or npm packages. Page data is read with page.extract(...), which returns a normal JavaScript value shaped like the schema, or with page.evaluate(...) when page-side JavaScript is genuinely needed. goto is the one asynchronous primitive; everything else is synchronous and blocking, and tool failures throw ordinary JavaScript errors. The script's output is whatever it returns from the top level.

Use cases

• Agent web access. Giving an LLM agent a browser through MCP with per-client session isolation, so several agents can browse in parallel from one process without clobbering each other's page.
• Content extraction for RAG. Using fetch --dump markdown to turn JavaScript-rendered pages into Markdown for indexing, or --dump structured_data to pull JSON-LD and OpenGraph metadata.
• High-volume crawling. Replacing headless Chrome workers in a crawler where memory per worker is the main cost driver, with --obey-robots to respect site rules.
• CI automation. Running Puppeteer or WebDriver-based checks against a lighter browser where the tests only need DOM and JavaScript behaviour, not pixel-accurate rendering.
• Recorded workflows. Prototyping a multi-step web flow interactively with the agent, saving it as PandaScript and running it on a schedule with no model dependency.
• SEO and metadata checks. Dumping a page's structured data and meta tags as JSON after JavaScript execution to verify what crawlers actually see.

How it compares

The comparison the README makes is with headless Chrome, and the trade-off is clear. Chrome renders everything a user would see and implements the full web platform; Lightpanda implements the parts automation needs, measured against Web Platform Tests, and drops rendering to cut memory and startup cost. Sites that depend on rendering-specific behaviour, canvas output or APIs Lightpanda does not yet implement will work better in Chrome. Sites where the job is "run the JavaScript and read the DOM" are where Lightpanda is designed to win.

Puppeteer and Playwright are not competitors in this picture; they are clients. Lightpanda's CDP server lets them drive it in place of Chrome, and WebDriver BiDi support opens the same door for WebDriver-based tooling. For simple static pages, a plain HTTP client remains cheaper than any browser, and Lightpanda's own README acknowledges that this approach stopped being enough once JavaScript started driving most of the web.

Things to know before adopting

• AGPL-3.0 licence. The repository is licensed under the GNU Affero General Public License v3. Running it internally is straightforward, but modifying Lightpanda and offering it to others over a network brings the AGPL's source-sharing obligations into play. Contributors must also sign a CLA during the pull request process.
• Telemetry is on by default. Lightpanda collects and sends usage telemetry unless LIGHTPANDA_DISABLE_TELEMETRY=true is set. Set it in containers and CI images if outbound telemetry is not acceptable.
• Platform limits. Linux release binaries link against glibc, so they fail on musl-based distributions such as Alpine with cannot execute: required file not found; the README recommends a glibc base image such as Debian or Ubuntu. There is no native Windows binary (use WSL2) and no Android build.
• Web platform coverage is partial. The engine is young compared with Blink or WebKit. Some APIs are explicitly stubs (the 1.0 notes describe element.requestFullscreen as "mostly a stub") and ServiceWorker support is experimental behind --experimental-features serviceworker. Check the published WPT results for the APIs a target site relies on.
• Nightly-first distribution. Homebrew, AUR and the direct-download instructions in the README point at nightly builds. Tagged releases exist (1.0.0 on 2 October 2026, 1.0.2 on 23 October 2026), so production deployments can pin a release instead.
• Behaviour changes in 1.0. CORS is now enforced by default, getComputedStyle results are read-only, and redirects that switch to GET drop body headers. Scripts written against earlier builds may need adjustment.
• Bot challenges. The 1.0 notes say Lightpanda now generates an error when it hits a bot challenge. It is not a tool for evading site protections, and pipelines should handle that error rather than retry blindly.
• Cloud offering is separate and unfinished. Lightpanda Cloud exposes an MCP server over SSE with an API token; the docs describe it as a work in progress that does not support all tools. The open-source binary is the self-hosted path.
• Binding addresses. The examples bind CDP to 127.0.0.1. Passing --host 0.0.0.0 to the MCP server accepts connections from outside the machine, so put authentication or network controls in front before exposing it.
• Building from source needs a pinned toolchain. The project requires Zig 0.17.0 exactly, plus Rust and the libraries needed to build V8.

Project activity

As of October 2026 the repository has about 37,900 stars on GitHub and roughly 1,800 forks. It was created in February 2023, is written primarily in Zig and is licensed under AGPL-3.0. The 1.0.0 release shipped on 2 October 2026, followed by 1.0.1 and 1.0.2 within the same month, and commits land daily. Web Platform Tests results are published daily at the project's performance site, and the team runs a Discord for support.

Source code, issues and releases live at github.com/lightpanda-io/browser, documentation at lightpanda.io/docs, the benchmark harness at github.com/lightpanda-io/demo, and an agent skill at github.com/lightpanda-io/agent-skill.