Skip to content

feat(browser): add Lightpanda headless browser backend with fallback chain#10871

Closed
thapecroth wants to merge 1 commit into
NousResearch:mainfrom
thapecroth:feat/lightpanda-browser-backend
Closed

feat(browser): add Lightpanda headless browser backend with fallback chain#10871
thapecroth wants to merge 1 commit into
NousResearch:mainfrom
thapecroth:feat/lightpanda-browser-backend

Conversation

@thapecroth

@thapecroth thapecroth commented Apr 16, 2026

Copy link
Copy Markdown

Summary

  • Lightpanda browser provider — lightweight, self-hosted headless browser (Zig-based) as an alternative to Chromium/Browserbase. Spawns a lightpanda serve process per session, connects via CDP. Ideal for resource-constrained hosts like Raspberry Pi.
  • Adapter daemon (lightpanda_adapter.js) — playwright-core bridge with daemon+socket pattern matching agent-browser's architecture. Handles Lightpanda's newContext→newPage init sequence and auto-reconnects on CDP disconnect.
  • Provider fallback chain — when Lightpanda crashes (e.g. SIGSEGV on bot-protected sites like Amazon), the browser tool automatically advances through: Lightpanda → Camofox → local Chromium → Browserbase. No user intervention needed.
  • Binary discovery fix — checks ~/.cache/lightpanda-node/lightpanda (native binary from npm postinstall) before PATH search, avoiding Node.js wrapper incompatibility on Node 18.
  • Vision model per-provider override — adds _PROVIDER_VISION_MODELS mapping so providers with dedicated vision models (e.g. zai → glm-4.6v-flash) use the right model.

Config

browser:
  cloud_provider: lightpanda  # or: local, browserbase, browser-use

New files

File Purpose
tools/browser_providers/lightpanda.py Provider: process lifecycle, CDP readiness polling, session management
tools/lightpanda_adapter.js CDP adapter daemon: open, snapshot, click, fill, scroll, eval, close
tests/tools/test_browser_lightpanda.py 32 unit tests
tests/tools/test_browser_lightpanda_integration.py 8 integration tests (mock binary, no real Lightpanda needed)
tests/tools/helpers/mock_lightpanda.py Minimal CDP server for integration tests

Test plan

  • 40/40 unit + integration tests pass (pytest tests/tools/test_browser_lightpanda*.py)
  • Real e2e: Lightpanda navigates, snapshots, evals, closes on example.com and httpbin.org
  • Fallback chain: Lightpanda crash (rc=-11) detected → session recreated with local Chromium
  • Binary discovery: native binary at ~/.cache/lightpanda-node/lightpanda found without LIGHTPANDA_PATH
  • Existing camofox dispatch preserved (global mode + per-task fallback)

🤖 Generated with Claude Code

@thapecroth thapecroth force-pushed the feat/lightpanda-browser-backend branch from 5a2f61d to 9fdc85a Compare April 16, 2026 07:50
@thapecroth @claude
feat(browser): add Lightpanda headless browser backend with fallback …
fcd2ec8 
…chain

Add Lightpanda as a lightweight, self-hosted headless browser alternative.
Lightpanda is a fast open-source browser written in Zig that exposes a CDP
server, making it ideal for resource-constrained environments like Raspberry Pi.

- LightpandaProvider: spawns lightpanda binary per session, polls CDP readiness,
  manages process lifecycle. Supports external CDP URL mode for Docker.
- lightpanda_adapter.js: daemon+socket pattern (mirrors agent-browser) with
  playwright-core CDP connection. Auto-reconnects on page/context disconnect.
- Provider fallback chain: lightpanda → camofox → local chromium → browserbase.
  When lightpanda crashes, the next command automatically advances backends.
- Binary discovery: checks ~/.cache/lightpanda-node/lightpanda (native binary
  from npm postinstall) before PATH, avoiding Node.js wrapper issues on Node 18.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@thapecroth thapecroth force-pushed the feat/lightpanda-browser-backend branch from 9fdc85a to fcd2ec8 Compare April 16, 2026 07:58
@krichprollsch

krichprollsch commented Apr 16, 2026

Copy link
Copy Markdown

@thapecroth did you see #7144?
Does this PR would cover your needs?

@thapecroth

thapecroth commented Apr 16, 2026

Copy link
Copy Markdown
Author

Hey @krichprollsch, thanks for the heads up! Yes, #7144 covers our needs — the --engine lightpanda approach through agent-browser is much cleaner than what we did here (custom provider + separate adapter daemon). We'll close this in favor of that PR.

A couple of things from our testing on Raspberry Pi that might be useful for #7144:

Binary discovery on Node 18: The @lightpanda/browser npm package installs a Node.js CLI wrapper that requires Node >= 20. On Node 18 hosts, shutil.which("lightpanda") finds the wrapper and it crashes on spawn. The actual native binary lives at ~/.cache/lightpanda-node/lightpanda. Worth checking that agent-browser handles this correctly.

Process crashes on certain sites: Lightpanda segfaults (rc=-11) on some bot-protected pages (e.g. Amazon 503 responses). The per-command fallback in #7144 should catch this, but the failure mode is a full process crash, not just an empty response — worth verifying the fallback still kicks in when the daemon dies mid-session.

Closing this one in favor of #7144.

@thapecroth thapecroth closed this Apr 16, 2026
@alt-glitch alt-glitch mentioned this pull request Apr 29, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@thapecroth @krichprollsch