站内导读
定位:Lightpanda 是用 Zig 从零编写的无头浏览器,面向 AI Agent 与自动化场景,不是 Chromium 或 WebKit 的分支,主打低内存与快执行。
核心能力
- 基于 CDP 协议提供 serve 模式,Puppeteer 通过 browserWSEndpoint 直接连接,脚本基本无需改动。
- fetch 支持 dump html、markdown、png、pdf 与 structured_data,可输出 JSON-LD、OpenGraph 等元数据。
- 支持 --obey-robots 与 --wait-until、--wait-selector 等参数,控制抓取合规与渲染等待时机。
- 官方基准显示 100 页峰值内存 123MB、耗时 5s,对比无头 Chrome 约省 16 倍内存、快 9 倍。
适用人群:适合做爬虫、网页数据抽取与 Agent 工具链的开发者,需熟悉 Puppeteer 或 CDP,运行环境为 Linux、macOS 或 WSL2。
注意:Linux 二进制依赖 glibc 2.35/2.38,无原生 Windows 与 Android 构建。
位置づけ:Lightpanda は AI Agent と自動化向けに Zig で一から書かれたヘッドレスブラウザです。Chromium や WebKit のフォークではなく、低メモリと高速実行を狙っています。
主な機能
- CDP サーバーモードを備え、Puppeteer は browserWSEndpoint で接続でき、既存スクリプトをほぼそのまま使えます。
- fetch は html、markdown、png、pdf、structured_data の出力に対応し、JSON-LD や OpenGraph を JSON で取得できます。
- --obey-robots による robots 遵守や、--wait-until、--wait-selector など描画待機の調整が可能です。
- 公式ベンチマークでは 100 ページでピークメモリ 123MB、実行 5 秒。ヘッドレス Chrome 比で約 16 倍省メモリ、9 倍高速です。
対象となる利用者:クローラーや Web データ抽出、Agent ツールチェーンを構築する開発者向け。Puppeteer か CDP の知識が必要で、Linux、macOS、WSL2 で動作します。
注意:Linux バイナリは glibc 2.35/2.38 に依存し、Windows と Android のネイティブビルドはありません。
정체:Lightpanda는 AI Agent와 자동화를 위해 Zig로 처음부터 작성한 헤드리스 브라우저입니다. Chromium이나 WebKit 포크가 아니며 낮은 메모리 사용과 빠른 실행을 목표로 합니다.
핵심 기능
- CDP 서버 모드를 제공하며 Puppeteer는 browserWSEndpoint로 연결해 기존 스크립트를 거의 그대로 사용할 수 있습니다.
- fetch는 html, markdown, png, pdf, structured_data 출력을 지원하고 JSON-LD와 OpenGraph를 JSON으로 뽑을 수 있습니다.
- --obey-robots로 robots 규칙을 따르고 --wait-until, --wait-selector 등으로 렌더링 대기 시점을 조정합니다.
- 공식 벤치마크에서 100페이지 기준 피크 메모리 123MB, 실행 5초로 헤드리스 Chrome보다 메모리 약 16배, 속도 9배 우수합니다.
사용 대상:크롤러, 웹 데이터 추출, Agent 도구 체인을 만드는 개발자에게 적합합니다. Puppeteer 또는 CDP 지식이 필요하고 Linux, macOS, WSL2에서 실행됩니다.
주의:Linux 바이너리는 glibc 2.35/2.38에 의존하며 Windows와 Android 네이티브 빌드는 없습니다.
What it is: Lightpanda is a headless browser written from scratch in Zig for AI agents and automation. It is not a Chromium or WebKit fork, and it targets low memory use and fast execution.
Key capabilities
- Ships a CDP server mode; Puppeteer connects via browserWSEndpoint and existing scripts mostly work unchanged.
- fetch can dump html, markdown, png, pdf or structured_data, including JSON-LD, OpenGraph and meta tags as JSON.
- Supports --obey-robots plus --wait-until, --wait-selector and --wait-script to control render timing.
- Official benchmarks: 100 pages peak at 123MB and 5s, about 16x less memory and 9x faster than headless Chrome.
Who it is for: Developers building crawlers, web data extraction or Agent toolchains. Familiarity with Puppeteer or CDP helps; it runs on Linux, macOS and WSL2.
Caveats: Linux binaries need glibc 2.35/2.38; there is no native Windows or Android build.
README · 详细文档
来源 · 查看原文
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.
Benchmarks
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 |
Quick start
Install
Package Managers
Latest nightly from Homebrew:
brew install lightpanda-io/browser/lightpanda
Latest nightly from Arch Linux User Repository:
yay -S lightpanda-nightly-bin
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
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && \
chmod a+x ./lightpanda
Verify the binary before running anything:
./lightpanda version
Linux aarch64 is also available
If you use **Nix**, you can run Lightpanda directly from the flake without downloading a binary:
nix run github:lightpanda-io/browser -- --help
Or pin it as an input in your own flake:
{
inputs.lightpanda.url = "github:lightpanda-io/browser";
}
Note: The Linux release binaries are linked against glibc. On musl-based Linux distributions (Alpine, etc.) the binary fails withcannot 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
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos && \
chmod a+x ./lightpanda
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.
docker run -d --name lightpanda -p 127.0.0.1:9222:9222 lightpanda/browser:latest
Dump a URL
./lightpanda fetch --obey-robots --dump html --log-format pretty --log-level info https://demo-browser.lightpanda.io/campfire-commerce/
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.
Start a CDP server
./lightpanda serve --obey-robots --log-format pretty --log-level info --host 127.0.0.1 --port 9222
To listen on a Unix-domain socket (owner-only, mode 0600) instead of TCP:
./lightpanda serve --unix-socket /run/user/1000/lightpanda.sock
Once the CDP server started, you can run a Puppeteer script by configuring the browserWSEndpoint.
Example Puppeteer script
import puppeteer from 'puppeteer-core';
// use browserWSEndpoint to pass the Lightpanda's CDP server address.
const browser = await puppeteer.connect({
browserWSEndpoint: "ws://127.0.0.1:9222",
});
// The rest of your script remains the same.
const context = await browser.createBrowserContext();
const frame = await context.newPage();
// Dump all the links from the frame.
await frame.goto('https://demo-browser.lightpanda.io/amiibo/', {waitUntil: "networkidle0"});
const links = await frame.evaluate(() => {
return Array.from(document.querySelectorAll('a')).map(row => {
return row.getAttribute('href');
});
});
console.log(links);
await frame.close();
await context.close();
await browser.disconnect();
Start a webdriver Bidi server
Use --protocol webdriver to enable Bidi support. You can start both, CDP and Bidi, with --protocol webdriver --protocol cdp
./lightpanda serve --obey-robots --log-format pretty --log-level info --host 127.0.0.1 --port 9222 --protocol webdriver
Agent mode
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.
./lightpanda agent # auto-detects API key from env
./lightpanda agent --task "top story on news.ycombinator.com?"
./lightpanda agent --no-llm # basic REPL, no LLM
./lightpanda run session.js # run a recorded script
cat session.js | ./lightpanda run - # ...or pipe one in via stdin
./lightpanda agent --provider gemini --task "..." # force a specific provider
./lightpanda agent --list-models # models available for the detected provider
VERTEX_API_KEY=... ./lightpanda agent --provider vertex # Vertex AI, express mode
GOOGLE_CLOUD_PROJECT=my-proj ./lightpanda agent --provider vertex # Vertex AI, token via gcloud auth
AI_GATEWAY_API_KEY=... ./lightpanda agent --provider vercel --model moonshotai/kimi-k2 # any model behind Vercel AI Gateway
OPENROUTER_API_KEY=... ./lightpanda agent --provider openrouter --model anthropic/claude-sonnet-5 # any model behind OpenRouter
OPENAI_BASE_URL=https://my-gateway/v1 OPENAI_API_KEY=... ./lightpanda agent # any OpenAI-compatible server
Native MCP and skill
The MCP server communicates via MCP JSON-RPC 2.0 over stdio.
Add to your MCP configuration:
{
"mcpServers": {
"lightpanda": {
"command": "/path/to/lightpanda",
"args": ["mcp"]
}
}
}
HTTP transport and independent sessions
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):
lightpanda mcp --port 9223
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:
- A client that
initializes without anMcp-Session-Idheader 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).
- Two agents that send the same
Mcp-Session-Idshare one browsing context
(sharing — e.g. a workflow where several agents work the same page).
- The
session_new,session_listandsession_closetools 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:
curl -s http://127.0.0.1:9223/mcp -H 'Content-Type: application/json' -d '{
"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "name": "run", "arguments": { "script":
"const page = new Page();\nawait page.goto(\"https://example.com\");\nreturn page.extract({ title: \"title\", links: [\"a\"] });" } }
}'
A skill is available in lightpanda-io/agent-skill.
Shell completion
lightpanda completion <bash | fish | zsh> prints a completion script for commands, flags and their values:
lightpanda completion fish > ~/.config/fish/completions/lightpanda.fish
lightpanda completion bash > ~/.local/share/bash-completion/completions/lightpanda
lightpanda completion zsh > ~/.zfunc/_lightpanda # with fpath=(~/.zfunc $fpath) before compinit
Telemetry
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.
Core dumps
Set LIGHTPANDA_DISABLE_CORE_DUMP (to any value) to suppress crash core dumps by zeroing the soft RLIMIT_CORE at startup.
Status
Here are the key features we have implemented. For full details, see our Web Platform Tests results.
- [x] CORS
- [x] HTTP loader (Libcurl)
- [x] HTML parser (html5ever)
- [x] DOM tree
- [x] Javascript support (v8)
- [x] DOM APIs
- [x] Ajax
- [x] XHR API - [x] Fetch API
- [x] DOM and Markdown dump
- [x] CDP/websockets server
- [x] Click
- [x] Input form
- [x] Cookies
- [x] Custom HTTP headers
- [x] Proxy support
- [x] Network interception
- [x] Respect
robots.txtwith option--obey-robots - [x] CDP and Webdriver Bidi
- [x] Adblocker
Build from sources
Prerequisites
Lightpanda 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:
sudo apt install xz-utils ca-certificates \
pkg-config libglib2.0-dev \
clang make curl git
You also need to install Rust.
For systems with **Nix**, you can use the devShell.
nix develop
For MacOS, you need cmake and Rust.
brew install cmake
Build and run
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.
Embed v8 snapshot
Lighpanda uses v8 snapshot. By default, it is created on startup but you can embed it by using the following commands:
Generate the snapshot.
zig build snapshot_creator -- src/snapshot.bin
Build using the snapshot binary.
zig build -Dsnapshot_path=../../snapshot.bin
See #1279 for more details.
Test
Unit Tests
You can test Lightpanda by running make test.
make test # Run all tests
make test F="server" # Filter by substring
TEST_FILTER="WebApi: #selector_all" make test # Filter main + subtest (separator: #)
TEST_VERBOSE=true make test
TEST_FAIL_FIRST=true make test
METRICS=true make test # Capture allocation/duration metrics as JSON
TEST_JOBS=1 make test # Run in one process (default: up to 4, or 1 when filtered)
End to end tests
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.
make end2end
Web Platform Tests
Lightpanda is tested against the standardized Web Platform Tests.
We use a fork including a custom 0. Results are published daily.
For reference, you can execute a WPT test case with your browser via wpt.live.
Configure WPT HTTP server
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.
git clone -b fork --depth=1 git@github.com:lightpanda-io/wpt.git
Enter into the wpt/ dir.
Install custom domains in your /etc/hosts
./wpt make-hosts-file | sudo tee -a /etc/hosts
Generate MANIFEST.json
./wpt manifest
Use the WPT's setup guide for details.
Run WPT test suite
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.
./wpt serve
Run a Lightpanda browser
zig build -Dwpt_extensions run -- serve \
--ws-max-concurrent 64 \
--insecure-disable-tls-host-verification \
--load-resources iframe \
--load-resources image \
--load-resources worker \
--load-resources stylesheet
Then you can start the wptrunner from the demo's clone dir:
cd wptrunner && go run .
Or one specific test:
cd wptrunner && go run . Node-childNodes.html
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.
zig build -Dwpt_extensions run -- fetch \
--insecure-disable-tls-host-verification \
--load-resources worker \
--load-resources iframe \
--dump wpt \
--wait-script "window.report && report.complete" \
"http://web-platform.test:8000/dom/nodes/Node-childNodes.html"
: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.
zig build -Dwpt_extensions -Doptimize=fast run -- serve ...
Contributing
See CONTRIBUTING.md for guidelines. You must sign our CLA during the pull request process.
Why Lightpanda?
Javascript execution is mandatory for the modern web
Simple HTTP requests used to be enough for web automation. That's no longer the case. Javascript now drives most of the web:
- Ajax, Single Page Apps, infinite loading, instant search
- JS frameworks: React, Vue, Angular, and others
Chrome is not the right tool
Running a full desktop browser on a server works, but it does not scale well. Chrome at hundreds or thousands of instances is expensive:
- Heavy on RAM and CPU
- Hard to package, deploy, and maintain at scale
- Many features are not necessary in headless made
Lightpanda is built for performance
Supporting Javascript with real performance meant building from scratch rather than forking Chromium:
- Not based on Chromium, Blink, or WebKit
- Written in Zig, a low-level language with explicit memory control
- No graphical rendering engine
