lightpanda-io/browser
Lightpanda Browser
The headless browser built from scratch for AI agents and automation.
Not a Chromium fork. Not a WebKit patch. A new browser, written in Zig.
16x lighter and 9x faster than Chromium.
The headless browser built from scratch for AI agents and automation.
Not a Chromium fork. Not a WebKit patch. A new browser, written in Zig.
16x lighter and 9x faster than Chromium.
Requesting 933 real web pages over the network on a AWS EC2 m5.large instance. See benchmark details.
| Metric | Lightpanda | Headless Chrome | Difference |
|---|---|---|---|
| Memory (peak, 100 pages) | 123MB | 2GB | ~16x less |
| Execution time (100 pages) | 5s | 46s | ~9x faster |
Package Managers
Latest nightly from Homebrew:
|
|
Latest nightly from Arch Linux User Repository:
|
|
Download from the nightly builds
You can download the last binary from the nightly builds for Linux and MacOS for both x86_64 and aarch64.
For Linux
|
|
Verify the binary before running anything:
|
|
Linux aarch64 is also available
If you use Nix, you can run Lightpanda directly from the flake without downloading a binary:
|
|
Or pin it as an input in your own flake:
|
|
Note: The Linux release binaries are linked against glibc. On musl-based Linux distributions (Alpine, etc.) the binary fails with
cannot execute: required file not foundbecause the glibc dynamic linker is missing. Use a glibc-based base image: the current release binaries need glibc 2.35 (x86_64) or 2.38 (arm64), sodebian:bookworm-slim(2.36) is fine onx86_64but too old forarm64— useFROM ubuntu:24.04,FROM debian:trixie-slim, orFROM debian:forky-slimthere — or build from sources.Android / Termux: there is no native Android build. The Linux aarch64 binary needs the glibc loader (
/lib/ld-linux-aarch64.so.1), which Android’s Bionic libc does not provide, so it fails with the samecannot execute: required file not founderror.
For MacOS
|
|
MacOS x86_64 is also available
For Windows + WSL2
Lightpanda has no native Windows binary. Install it inside WSL following the Linux steps above.
WSL not installed? Run wsl --install from an administrator shell, restart, then open wsl.
See Microsoft’s WSL install guide for details.
Your automation client (Puppeteer, Playwright, etc.) can run either inside WSL or on the Windows host. WSL forwards localhost:9222 automatically.
Install from Docker
Lightpanda provides official Docker
images for both Linux amd64 and
arm64 architectures.
The following command fetches the Docker image and starts a new container exposing Lightpanda’s CDP server on port 9222.
|
|
|
|
You can use --dump markdown to convert directly into markdown, or
--dump png > page.png or --dump pdf > page.pdf for a text-only rendering
of the page. --dump structured_data prints the page’s JSON-LD, OpenGraph,
Twitter card, meta and link tags as JSON, like the MCP structuredData tool.
--wait-until, --wait-ms, --wait-selector and --wait-script are
available to adjust waiting time before dump.
|
|
To listen on a Unix-domain socket (owner-only, mode 0600) instead of TCP:
|
|
Once the CDP server started, you can run a Puppeteer script by configuring the
browserWSEndpoint.
|
|
Use --protocol webdriver to enable Bidi support.
You can start both, CDP and Bidi, with --protocol webdriver --protocol cdp
|
|
lightpanda agent lets you drive the browser with a native agent. Describe what
you want in plain English or with slash commands, and it controls the browser:
navigating pages, clicking through flows, filling forms, extracting structured
data. Think of it as a robot you’re directing to use the web, more than a
chatbot you’re having a conversation with.
Because the agent runs inside the same process as the browser, every tool call is a direct operation and you retain Lightpanda’s speed and memory advantage.
The output of an agent session is a
PandaScript: vanilla JavaScript
with a small set of native browser primitives built directly into Lightpanda.
Run /save to export one from your current session, then replay it with
lightpanda run <script>.js. Scripts are deterministic and token-free, so
you can prototype with the LLM and ship the output to production without a
model at runtime.
It supports Anthropic, OpenAI, Gemini, Google Vertex AI, Mistral, Hugging
Face, the multi-lab gateways Vercel AI Gateway
and OpenRouter (one key for hundreds of models), any OpenAI-compatible endpoint via
OPENAI_BASE_URL, and local models via Ollama, llama.cpp or LLMD. You can also run
without an LLM using --no-llm, which drops you into the REPL. See the
agent documentation for the full
reference.
|
|
The MCP server communicates via MCP JSON-RPC 2.0 over stdio.
Add to your MCP configuration:
|
|
For serving several agents from one process, start the MCP server over HTTP
instead of stdio by giving it a port (add --host x.x.x.x to specify the
interface to listen on):
|
|
Clients POST JSON-RPC to http://host:9223/mcp. Each connection is routed to
its own browsing session — its own page, cookies and memory — so agents no
longer clobber each other’s page:
initializes without an Mcp-Session-Id header is assigned a
fresh session; the id comes back in the response’s Mcp-Session-Id header.
Send it on subsequent requests to stay on that session (isolation).Mcp-Session-Id share one browsing context
(sharing — e.g. a workflow where several agents work the same page).session_new, session_list and session_close tools manage sessions
explicitly. Sending DELETE /mcp with an Mcp-Session-Id closes that session.The run tool runs a PandaScript
in the caller’s session, as lightpanda run does, and returns its console
output and the value it returns. It takes the source as script, or the path
of a file that save wrote. Pages the script opens are closed when it ends;
cookies and storage stay, so a login carries over to the next run. An optional
timeout in milliseconds (default 60000) stops a stuck script. A backend can
drive Lightpanda with one POST:
|
|
A skill is available in lightpanda-io/agent-skill.
lightpanda completion <bash | fish | zsh> prints a completion script for commands, flags and their values:
|
|
By default, Lightpanda collects and sends usage telemetry. This can be disabled by setting an environment variable LIGHTPANDA_DISABLE_TELEMETRY=true. You can read Lightpanda’s privacy policy at: https://lightpanda.io/privacy-policy.
Set LIGHTPANDA_DISABLE_CORE_DUMP (to any value) to suppress crash core dumps by zeroing the soft RLIMIT_CORE at startup.
Here are the key features we have implemented. For full details, see our Web Platform Tests results.
robots.txt with option --obey-robotsLightpanda is written with Zig 0.17.0. You have to
install it with the right version in order to build the project.
Lightpanda also depends on v8, Libcurl and html5ever.
To be able to build the v8 engine, you have to install some libs:
For Debian/Ubuntu based Linux:
|
|
You also need to install Rust.
For systems with Nix, you can use the devShell.
|
|
For MacOS, you need cmake and Rust.
|
|
You can build the entire browser with make build or make build-dev for debug
env.
But you can directly use the zig command: zig build run.
Lighpanda uses v8 snapshot. By default, it is created on startup but you can embed it by using the following commands:
Generate the snapshot.
|
|
Build using the snapshot binary.
|
|
See #1279 for more details.
You can test Lightpanda by running make test.
|
|
To run end to end tests, you need to clone the demo
repository into ../demo dir.
You have to install the demo’s node requirements
You also need to install Go > v1.24.
|
|
Lightpanda is tested against the standardized Web Platform Tests.
We use a fork including a custom
testharnessreport.js. Results are published daily.
For reference, you can execute a WPT test case with your browser via wpt.live.
To run the test, you must clone the repository, configure the custom hosts and generate the
MANIFEST.json file.
Clone the repository with the fork branch.
|
|
Enter into the wpt/ dir.
Install custom domains in your /etc/hosts
|
|
Generate MANIFEST.json
|
|
Use the WPT’s setup guide for details.
An external Go runner is provided by
github.com/lightpanda-io/demo/
repository, located into wptrunner/ dir.
You need to clone the project first.
First start the WPT’s HTTP server from your wpt/ clone dir.
|
|
Run a Lightpanda browser
|
|
Then you can start the wptrunner from the demo’s clone dir:
|
|
Or one specific test:
|
|
wptrunner command accepts --summary and --json options modifying output.
Also --concurrency define the concurrency limit.
To check a single test case without the runner, fetch --dump wpt prints its
results as JSON: the harness status, a pass/fail summary and the cases that
did not pass. It relies on the fork’s testharnessreport.js.
|
|
:warning: Running the whole test suite will take a long time. In this case,
it’s useful to build in releaseFast mode to make tests faster.
|
|
See CONTRIBUTING.md for guidelines. You must sign our CLA during the pull request process.
Simple HTTP requests used to be enough for web automation. That’s no longer the case. Javascript now drives most of the web:
Running a full desktop browser on a server works, but it does not scale well. Chrome at hundreds or thousands of instances is expensive:
Supporting Javascript with real performance meant building from scratch rather than forking Chromium: