mathews-tom/lightpanda-browser

Lightpanda Browser — Fast Headless Automation

Headless browser automation using Lightpanda as the backend engine, controlled through the agent-browser CLI via CDP (Chrome DevTools Protocol).

When to use this over agent-browser:

| Use Lightpanda | Use agent-browser (Chromium) | | -------------------------------- | ---------------------------------- | | Web scraping / data extraction | Screenshots, PDFs, visual testing | | Form automation / submission | Video recording / visual debugging | | API response inspection | CSS layout verification | | DOM traversal / content parsing | Mobile device emulation (iOS) | | CI environments with limited RAM | Full browser extension support | | High-volume parallel sessions | Sites requiring full rendering |

Triggers:

• "lightpanda", "lightweight browser", "fast headless"
• "scrape with low memory", "headless scraping"
• "browser without rendering", "DOM-only browser"
• "fast browser automation", "efficient scraping"
• "is lightpanda faster than chromium?", "which headless browser uses less memory?"
• "how do I scrape without chromium?", "can I run a browser with less RAM?"
• Any browser task where visual output is not needed

---

Prerequisites

Install Lightpanda

# macOS (Apple Silicon)
curl -fsSL https://github.com/nichochar/install-lightpanda/raw/main/install.sh | bash

# Or build from source
git clone https://github.com/lightpanda-io/browser.git
cd browser && zig build -Doptimize=ReleaseSafe

Install agent-browser (if not already present)

brew install agent-browser

Verify installation

lightpanda --version
agent-browser --version

---

Core Workflow

Every session follows this lifecycle:

1. Start Lightpanda daemon (CDP server)
2. Connect agent-browser via --cdp
3. Navigate, snapshot, interact
4. Stop daemon when done

Step 1 — Start Lightpanda

# Start Lightpanda CDP server on port 9222 (background)
lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!

# Wait for CDP to be ready
sleep 1

Step 2 — Connect and Automate

# All agent-browser commands work via --cdp flag
agent-browser --cdp 9222 open https://example.com
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 fill @e1 "search query"
agent-browser --cdp 9222 click @e2
agent-browser --cdp 9222 snapshot -i  # Re-snapshot after navigation

Step 3 — Cleanup

agent-browser --cdp 9222 close
kill $LIGHTPANDA_PID 2>/dev/null

---

Supported Commands

All commands below are invoked as agent-browser --cdp <port> <command>.

Navigation

agent-browser --cdp 9222 open <url>
agent-browser --cdp 9222 back
agent-browser --cdp 9222 forward
agent-browser --cdp 9222 reload
agent-browser --cdp 9222 close

Snapshot (DOM Analysis)

agent-browser --cdp 9222 snapshot -i         # Interactive elements with refs
agent-browser --cdp 9222 snapshot -i -C      # Include cursor-interactive elements
agent-browser --cdp 9222 snapshot -s "#main"  # Scope to CSS selector
agent-browser --cdp 9222 snapshot -i --json   # JSON output for parsing

Interaction (use @refs from snapshot)

agent-browser --cdp 9222 click @e1
agent-browser --cdp 9222 dblclick @e1
agent-browser --cdp 9222 fill @e2 "text"
agent-browser --cdp 9222 type @e2 "text"
agent-browser --cdp 9222 press Enter
agent-browser --cdp 9222 select @e1 "option"
agent-browser --cdp 9222 check @e1
agent-browser --cdp 9222 hover @e1
agent-browser --cdp 9222 scroll down 500
agent-browser --cdp 9222 drag @e1 @e2
agent-browser --cdp 9222 upload @e1 file.pdf

Get Information

agent-browser --cdp 9222 get text @e1        # Element text
agent-browser --cdp 9222 get html @e1        # innerHTML
agent-browser --cdp 9222 get value @e1       # Input value
agent-browser --cdp 9222 get attr @e1 href   # Attribute
agent-browser --cdp 9222 get title           # Page title
agent-browser --cdp 9222 get url             # Current URL
agent-browser --cdp 9222 get count ".item"   # Count elements

Wait

agent-browser --cdp 9222 wait @e1                     # Wait for element
agent-browser --cdp 9222 wait 2000                    # Wait milliseconds
agent-browser --cdp 9222 wait --text "Success"        # Wait for text
agent-browser --cdp 9222 wait --url "**/dashboard"    # Wait for URL
agent-browser --cdp 9222 wait --load networkidle      # Wait for network idle
agent-browser --cdp 9222 wait --fn "window.ready"     # Wait for JS condition

Cookies and Storage

agent-browser --cdp 9222 cookies
agent-browser --cdp 9222 cookies set name value
agent-browser --cdp 9222 cookies clear
agent-browser --cdp 9222 storage local
agent-browser --cdp 9222 storage local set key value

Network Interception

agent-browser --cdp 9222 network route <url>              # Intercept
agent-browser --cdp 9222 network route <url> --abort      # Block
agent-browser --cdp 9222 network route <url> --body '{}'  # Mock response
agent-browser --cdp 9222 network requests                 # View tracked
agent-browser --cdp 9222 network requests --filter api    # Filter

JavaScript Execution

agent-browser --cdp 9222 eval "document.title"
agent-browser --cdp 9222 eval -b "<base64>"
cat script.js | agent-browser --cdp 9222 eval --stdin

Semantic Locators

agent-browser --cdp 9222 find text "Sign In" click
agent-browser --cdp 9222 find label "Email" fill "[email protected]"
agent-browser --cdp 9222 find role button click --name "Submit"
agent-browser --cdp 9222 find testid "submit-btn" click

Tabs

agent-browser --cdp 9222 tab                 # List tabs
agent-browser --cdp 9222 tab new [url]       # New tab
agent-browser --cdp 9222 tab 2               # Switch tab
agent-browser --cdp 9222 tab close           # Close tab

Frames

agent-browser --cdp 9222 frame "#iframe"     # Enter iframe
agent-browser --cdp 9222 frame main          # Back to main

State Management

agent-browser --cdp 9222 state save auth.json    # Save session state
agent-browser --cdp 9222 state load auth.json    # Restore session state

---

Unsupported Commands

Lightpanda does not have a rendering engine. These commands will fail or produce empty output:

| Command | Reason | Alternative | | ------------------- | -------------------------- | --------------------------------------- | | screenshot | No visual rendering | Use get text / get html for content | | pdf | No CSS layout engine | Use get html and convert externally | | record start/stop | No visual output to record | Use network request logs | | highlight | No visual rendering | Use snapshot -i to identify elements | | set device | No viewport emulation | Set user-agent via set headers | | set media | No CSS media query support | N/A | | get styles | No computed styles | Parse raw HTML/CSS | | get box | No layout computation | N/A | | is visible | No visibility computation | Check DOM presence instead |

---

Common Patterns

High-Volume Scraping

# Start Lightpanda — uses ~60MB vs ~550MB for Chromium
lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

URLS=("https://site.com/page/1" "https://site.com/page/2" "https://site.com/page/3")
for url in "${URLS[@]}"; do
  agent-browser --cdp 9222 open "$url"
  agent-browser --cdp 9222 wait --load networkidle
  agent-browser --cdp 9222 get text body >> output.txt
  echo "---" >> output.txt
done

kill $LIGHTPANDA_PID 2>/dev/null

Form Automation

lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

agent-browser --cdp 9222 open https://example.com/form
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 fill @e1 "Jane Doe"
agent-browser --cdp 9222 fill @e2 "[email protected]"
agent-browser --cdp 9222 select @e3 "California"
agent-browser --cdp 9222 check @e4
agent-browser --cdp 9222 click @e5
agent-browser --cdp 9222 wait --load networkidle
agent-browser --cdp 9222 snapshot -i  # Verify result

kill $LIGHTPANDA_PID 2>/dev/null

Authenticated Session

lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

# Login and save state
agent-browser --cdp 9222 open https://app.example.com/login
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 fill @e1 "$USERNAME"
agent-browser --cdp 9222 fill @e2 "$PASSWORD"
agent-browser --cdp 9222 click @e3
agent-browser --cdp 9222 wait --url "**/dashboard"
agent-browser --cdp 9222 state save auth.json

# Reuse state later (new session)
agent-browser --cdp 9222 state load auth.json
agent-browser --cdp 9222 open https://app.example.com/dashboard
agent-browser --cdp 9222 snapshot -i

kill $LIGHTPANDA_PID 2>/dev/null

API Response Inspection

lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

# Intercept API calls
agent-browser --cdp 9222 open https://app.example.com
agent-browser --cdp 9222 network requests --filter "/api/"

# Or mock API responses for testing
agent-browser --cdp 9222 network route "**/api/users" --body '{"users": []}'
agent-browser --cdp 9222 open https://app.example.com/users
agent-browser --cdp 9222 snapshot -i

kill $LIGHTPANDA_PID 2>/dev/null

Parallel Sessions on Different Ports

# Launch multiple Lightpanda instances for true parallelism
lightpanda serve --host 127.0.0.1 --port 9222 &
PID1=$!
lightpanda serve --host 127.0.0.1 --port 9223 &
PID2=$!
sleep 1

agent-browser --cdp 9222 open https://site-a.com &
agent-browser --cdp 9223 open https://site-b.com &
wait

agent-browser --cdp 9222 get text body > site-a.txt
agent-browser --cdp 9223 get text body > site-b.txt

kill $PID1 $PID2 2>/dev/null

---

Environment Variables

LIGHTPANDA_HOST="127.0.0.1"    # Bind address (default: 127.0.0.1)
LIGHTPANDA_PORT="9222"          # CDP port (default: 9222)

---

Troubleshooting

Lightpanda won't start

# Check if port is in use
lsof -i :9222
# Kill existing process
kill $(lsof -t -i :9222) 2>/dev/null

CDP connection refused

# Verify Lightpanda is listening
curl -s http://127.0.0.1:9222/json/version
# Expected: JSON with browser info

Command fails with "not supported"

Lightpanda is in beta. If a CDP method is not yet implemented:

1. Check the Lightpanda status page for supported APIs
2. Fall back to agent-browser (Chromium) for that specific operation
3. File an issue at https://github.com/lightpanda-io/browser/issues

JavaScript execution errors

Lightpanda uses V8 but not all Web APIs are implemented. If eval fails:

1. Check if the API is listed in Lightpanda's supported features
2. Use simpler DOM operations (get text, get html) instead of complex JS

---

Performance Benchmarks

Reference numbers for choosing between Lightpanda and Chromium. Measured on typical scraping workloads.

| Metric | Lightpanda | Chromium (Playwright) | When It Matters | | ------------------ | ---------- | --------------------- | ----------------------------------------------------------- | | Memory per page | ~60MB | ~550MB | Parallel sessions, CI runners, constrained environments | | Cold start | <100ms | ~2s | Short-lived scripts, serverless, high-frequency invocations | | DOM-only page load | ~50ms | ~300ms | Bulk scraping (difference compounds over hundreds of pages) | | Binary size | ~15MB | ~300MB | Docker images, CI caching, disk-constrained hosts | | JS execution (V8) | Equivalent | Equivalent | No difference — same engine | | Full page render | N/A | ~500ms | Lightpanda cannot render — use Chromium |

Decision Thresholds

| Scenario | Recommendation | | ------------------------------------- | ---------------------------------------------- | | < 10 pages, need screenshots | Chromium — overhead is negligible | | 10-100 pages, text extraction only | Lightpanda — saves 5-50GB RAM | | 100+ pages, parallel sessions | Lightpanda — Chromium hits memory limits | | CI with 2GB RAM limit | Lightpanda — fits 30+ pages vs 3 with Chromium | | Visual regression testing | Chromium — Lightpanda cannot produce images | | Form submission + response validation | Either — Lightpanda is faster but both work |

---

Calibration Rules

1. Always start Lightpanda before agent-browser commands. CDP connection fails silently if the daemon is not running — verify with curl -sf http://127.0.0.1:9222/json/version before proceeding.
2. Re-snapshot after every navigation. Refs (@e1, @e2) are invalidated when the page changes — this is inherited from agent-browser, not Lightpanda-specific.
3. Prefer get text over eval for content extraction. Lightpanda's Web API surface is incomplete — document.querySelector works but complex APIs (IntersectionObserver, getComputedStyle) do not.
4. Use separate ports for parallel sessions, not --session. Lightpanda instances are single-threaded — multiple ports give true parallelism, --session multiplexes on one instance.
5. Fall back to Chromium explicitly, not silently. If a command fails with "not supported", switch to agent-browser (no --cdp flag) for that operation. Do not retry or suppress the error.
6. Kill the daemon on exit. Use trap cleanup EXIT in scripts to prevent orphaned Lightpanda processes consuming port 9222.
7. Check Lightpanda release notes before upgrading. Beta software — CDP method coverage changes between versions. Run agent-browser --cdp 9222 snapshot -i on a known page as a smoke test after updates.

---

Deep-Dive Documentation

| Reference | When to Use | | ---------------------------------------------------------------- | ------------------------------------------------- | | references/commands.md | Full command reference with CDP flag usage | | references/lightpanda-setup.md | Installation, configuration, build from source | | references/compatibility.md | Supported vs unsupported CDP methods and Web APIs |

Ready-to-Use Templates

| Template | Description | | -------------------------------------------------------------- | -------------------------------------- | | templates/scrape-session.sh | Start daemon, scrape pages, cleanup | | templates/form-submit.sh | Form fill + submission with validation | | templates/parallel-extract.sh | Multi-port parallel data extraction |