Lightpanda: Zig-Based Headless Browser for AI Automation

Installation via Homebrew, Arch Linux AUR, nightly binaries, or Docker

Lightpanda provides multiple installation paths with exact commands from the README. For macOS, Homebrew installs the nightly:

brew install lightpanda-io/browser/lightpanda

For Arch Linux, the AUR package:

yay -S lightpanda-nightly-bin

For Linux x86_64, download and make executable:

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

For macOS aarch64:

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

Verify the binary before running:

./lightpanda version

Docker pulls the nightly image:

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

Windows users must install WSL2:

wsl --install

Then follow Linux steps inside WSL. Linux binaries require glibc and fail on musl-based distributions like Alpine. Android/Termux is not supported due to Bionic libc incompatibility. MacOS x86_64 and Linux aarch64 binaries are also available from the nightly releases.

Fetch command dumps pages as HTML, Markdown, PNG, or PDF

The `lightpanda fetch` command retrieves and dumps web pages. The example uses the exact command from the README:

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

The `--dump` flag accepts html, markdown, png, or pdf output. Use `--dump markdown` for markdown conversion, `--dump png > page.png` for screenshot, `--dump pdf > page.pdf` for text-only PDF rendering. Waiting options include `--wait-until`, `--wait-ms`, `--wait-selector`, and `--wait-script` to adjust timing before dump. The `--obey-robots` flag respects robots.txt. The `--log-format pretty` and `--log-level info` control logging output. The dump command provides a CLI alternative to the CDP server for simple scraping tasks.

Serve command starts CDP server for Puppeteer and Playwright integration

The `lightpanda serve` command starts a Chrome DevTools Protocol server. The example runs the exact command from the README:

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

Once running, Puppeteer connects via `browserWSEndpoint` set to `ws://127.0.0.1:9222`. The example Puppeteer script imports puppeteer-core, connects to the endpoint, creates a browser context and page, navigates to a URL with `waitUntil: networkidle0`, and extracts links via `frame.evaluate()`. WebDriver BiDi support is enabled with `--protocol webdriver` or both protocols with `--protocol webdriver --protocol cdp`. The server exposes the standard CDP endpoint at the configured host and port. The `--obey-robots` flag applies to served sessions as well. The `--host` and `--port` flags configure the bind address and port. The `--log-format pretty` and `--log-level info` control logging. The `--obey-robots` flag applies to served sessions.

Agent mode drives browser with natural language and exports PandaScript

The `lightpanda agent` command runs an interactive AI agent that controls the browser. The agent accepts plain English or slash commands to navigate, click, fill forms, and extract structured data. It runs inside the browser process for direct tool calls without token overhead. The `lightpanda agent` auto-detects API keys from environment. The exact commands from the README include:

./lightpanda agent

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

./lightpanda agent --no-llm

./lightpanda run ses

The `--task` flag provides an initial goal. The `--no-llm` flag drops into a basic REPL without an LLM. The output is a PandaScript: vanilla JavaScript with native browser primitives. Run `/save` to export a session, then replay with `lightpanda run <script>.js`. Scripts are deterministic and token-free for production deployment without runtime LLM costs. Supported LLM providers include 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 or llama.cpp. The agent documentation at lightpanda.io/docs/usage/agent provides the full reference. The agent runs inside the same process as the browser, so every tool call is a direct operation retaining Lightpanda's speed and memory advantage.

Benchmark claims 16x memory reduction and 9x speed improvement over Chromium

The README publishes benchmark results from requesting 933 real web pages on an AWS EC2 m5.large instance. The benchmark details are in the demo repository at github.com/lightpanda-io/demo/blob/main/BENCHMARKS.md#crawler-benchmark. The table shows peak memory for 100 pages at 123MB for Lightpanda versus 2GB for Headless Chrome, a 16x reduction. Execution time for 100 pages is 5 seconds for Lightpanda versus 46 seconds for Headless Chrome, a 9x improvement. The benchmark uses network requests to real pages, not synthetic tests. The demo repository contains the full methodology. These claims are from the project's own benchmarks and have not been independently verified in this material. The benchmark table in the README shows three columns: Metric, Lightpanda, Headless Chrome, and Difference. The memory row shows 123MB versus 2GB. The execution time row shows 5s versus 46s. The test instance is an AWS EC2 m5.large which provides 2 vCPUs and 8 GB of RAM.

Platform limitations: no native Windows, no Android, glibc required on Linux

Lightpanda has significant platform limitations. No native Windows binary exists; users must install WSL2 and follow Linux steps. WSL forwards localhost:9222 automatically so automation clients on the Windows host can connect. The Linux release binaries are linked against glibc. On musl-based distributions like Alpine, the binary fails with `cannot execute: required file not found` because the glibc dynamic linker is missing. The workaround is using a glibc-based base image like `FROM debian:bookworm-slim` or `FROM ubuntu:24.04`, or building from sources. Android and Termux are not supported; the Linux aarch64 binary needs `/lib/ld-linux-aarch64.so.1` which Android's Bionic libc does not provide. MacOS supports both aarch64 and x86_64. Linux x86_64 and aarch64 are available.

Build system uses Zig, prebuilt V8, and Rust with Makefile orchestration

The build system centers on a Makefile that detects OS and architecture (Darwin arm64, Darwin x86_64, Linux aarch64, Linux x86_64). The Zig compiler is invoked via `ZIG := zig`. The build downloads prebuilt V8 archives from zig-v8-fork releases to avoid 10+ minute V8 source builds. The V8 version is read from the GitHub Actions install action to prevent drift. The cache path is keyed on ZIG_V8_TAG and archive filename. The `make download-v8` target fetches the matching prebuilt archive. The Dockerfile uses debian:stable-slim, installs Rust via rustup, installs minisign for verification, clones the repository, downloads and verifies Zig with minisign, and builds with Zig. The build.zig.zon specifies the minimum Zig version. The build requires clang, make, curl, git, pkg-config, and libglib2.0-dev. The V8 version is 15.5.35.13 and Zig V8 tag is v0.5.8.

AGPL-3.0 license requires source disclosure for network deployments

Lightpanda is licensed under AGPL-3.0, which requires source code disclosure when the software is used over a network. This is stricter than GPL-3.0 because it applies to SaaS and network services. The LICENSING.md file likely contains details. The Dockerfile and binary distributions are subject to this license. Commercial users deploying Lightpanda as a service must provide source code to users. The AGPL-3.0 may be a barrier for proprietary applications. The license file is at the repository root. The README links to the license badge. The license choice reflects the project's open-source orientation for AI and automation tooling.

Editorial conclusion

Teams building AI-driven browser automation will value Lightpanda's memory efficiency and agent mode. Projects needing native Windows, Android, or musl Linux support must use WSL, Docker, or build from source.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes