On this page
On this page
Tools
Lightweight browsers
Lightweight browsers
Lightpanda is an opt-in engine for text and DOM browser tasks. It uses the same
OpenClaw browser tool through an explicitly configured profile. It is not a
visual-browser replacement: keep a Chromium profile for screenshots, PDF output,
and applications that require unsupported browser features.
The examples pin Lightpanda 1.0.2. They do not change your existing browser profile, install a service, or migrate a logged-in Chrome profile.
Browser plugin architecture
The bundled Browser plugin owns both engine adapters. Chromium and Lightpanda
use the same browser tool, profile selection, route admission, navigation
policy, and session lifecycle. The registered adapter selects capabilities,
CDP normalization, snapshot defaults, and connection lifetime; it does not add
a second browser tool or process manager.
Browser status reports availableEngines and the selected engine's
sessionScope and screenshotFidelity. Chromium keeps its managed,
existing-session, extension-relay, and remote-CDP profiles. Lightpanda remains
an explicitly selected, attach-only external engine with one page per
connection and no automatic read replay after session loss.
These are adapters inside the existing plugin, not separately installable third-party plugins. Enabling the adapter does not download, launch, or bundle the Lightpanda engine. Existing profiles and engine configuration are unchanged.
Licensing and distribution
OpenClaw's adapter remains MIT-licensed. The optional Lightpanda engine is
AGPL, not MIT. Version 1.0.2 has inconsistent declarations: its
licensing document
says AGPL-3.0-only, while its
pinned source notice
allows later versions. Record that discrepancy during your SBOM review; neither
interpretation makes the engine permissively licensed.
The existing Playwright client is Apache-2.0; the existing ws client is MIT.
Their licenses and third-party notices still apply.
These examples connect over CDP to an independently installed, unmodified engine. They do not bundle or relicense Lightpanda in OpenClaw's package or image. The engine and its container dependencies are not an MIT-only distribution. If your deployment excludes copyleft software, do not select this engine.
Mirroring or bundling the engine requires a separate redistribution review, including license notices, Corresponding Source, and third-party obligations. Modifying a network-served engine also requires reviewing AGPL section 13. A separate process is not a blanket legal exemption, and checksum verification does not establish license compliance. See the artifact and dependency review for the verified pins and remaining limits.
Alternatives reviewed
The following is a licensing comparison as of 2026-09-21, not a claim that these alternatives have passed OpenClaw integration or cross-platform tests. An MIT-compatible application and an entirely permissive engine distribution are different requirements.
| Option | Engine and licensing boundary |
|---|---|
| Chromium headless shell | An established CDP engine, not an all-permissive binary. The inspected 153.0.8010.12 distribution's LICENSE.headless_shell includes LGPL and MPL notices; its pinned sources identify FFmpeg's LGPL terms and mixed-license hyphenation data. |
| Cloudflare Kitesurf | A hosted, stateless Browser Run engine, not a downloadable replacement in this review. Cloudflare's announcement describes open-sourcing as future work; a self-hosted engine release and its license were not available for this audit. Service terms are separate from client-library licenses. |
| Obscura 0.2.3 | A standalone Rust engine with embedded Deno/V8 and an Apache-2.0 root license. It is the strongest standalone lightweight candidate reviewed for avoiding an AGPL engine, but has MPL dependencies and unresolved redistribution-notice work. It is not an all-permissive replacement. |
Automation clients do not replace the engine. For example, Vercel's agent-browser offers Chrome and Lightpanda backends; its own Apache-2.0 license does not change the selected engine's license. The same distinction applies to Playwright and Puppeteer clients.
Obscura audit boundary
Release v0.2.3
was reviewed at commit 1a3169da276d7720732c7b20535474942917fb83.
Its lockfile
contains 471 registry packages. Their license declarations include no AGPL,
but five are MPL-2.0-only: cooked-waker 5.0.0, cssparser 0.34.0,
cssparser-macros 0.6.1, dtoa-short 0.3.5, and selectors 0.26.0.
These dependencies remain in the no-render engine's DOM/JavaScript paths.
MPL's file-level obligations
do not require unrelated MIT adapter files to become MPL; they still apply to
the covered code and its distribution.
The downloaded Linux x86-64 no-render archive matched release SHA-256
b5e55e8f2c97814127a521cd59af1a84b79dc40cf658fda04df04af81a2d89f3.
It contained only obscura and obscura-worker, without license or notice files.
The pinned release workflow
packages only those executables and does not use Cargo's --locked flag.
Consequently, source-lock metadata is not proof of the complete dependency set
inside each release binary. Full V8/third-party and platform-library review,
notices, source availability, and runtime compatibility remain to be verified
before bundling or recommending an integrated deployment.
Choose where the engine runs
| OpenClaw location | Lightpanda location | Profile CDP URL |
|---|---|---|
| Host, including Windows | Docker/Podman with a loopback-published port | ws://127.0.0.1:9222 |
| Linux or macOS host | Native binary on the same host | ws://127.0.0.1:9222 |
| Docker Compose | Sidecar in the same Compose project | ws://lightpanda:9222 |
| WSL | Native Linux binary in the same WSL distribution | ws://127.0.0.1:9222 |
localhost inside an OpenClaw container means that container, not the host and
not the Lightpanda sidecar. Use the service name for container-to-container
connections. On Windows, run Docker Desktop in Linux container mode, or run
both OpenClaw and the Linux engine inside WSL. Lightpanda does not publish a native
Windows binary. macOS and Linux have official x86-64 and ARM64 release binaries;
the official container image has Linux amd64 and arm64 variants.
Upstream installation information.
Docker with OpenClaw on the host
From the repository root:
The sample publishes CDP on 127.0.0.1:9222 only. Set LIGHTPANDA_PORT to select
another host port, and update the profile URL to match. The image is pinned by its
multi-platform digest, so Docker selects the host architecture without pulling a
moving latest or nightly version.
The healthcheck opens an independent local CDP WebSocket session and checks its
handshake. This proves listener readiness, not successful browsing or OpenClaw
integration. The sample leaves memory, CPU, and PID limits unset. Set limits for
your measured workload in your deployment's Compose configuration, or use
docker update
with --memory, --cpus, and --pids-limit for an existing container.
restart: unless-stopped restarts a crashed engine but does not restart a
still-running unhealthy container. Monitor unhealthy status and replace failed
workers through your deployment's supervisor. Restarting loses that worker's
page/login state; do not automatically replay clicks or submissions.
The stop signal is SIGTERM, with a 10-second grace period, overriding the
upstream image's immediate SIGKILL. This is a single-worker example, not a
high-availability service or transparent failover guarantee.
CDP gives a client control over the browser; the sample does not add CDP authentication. Do not change the loopback binding to a public address. Use an authenticated tunnel for access from another host.
To stop and remove only this sample's container and network:
Docker Compose with OpenClaw in a container
Merge the sidecar into the repository's existing Compose project:
Configure the OpenClaw Gateway with cdpUrl: "ws://lightpanda:9222" in the profile
below. Use the same Compose files and project name when starting the Gateway.
No browser port is published to the host in this variant. The containers share
the project's bridge network and retain outbound internet access; the network
is not declared internal: true because that would prevent public-site browsing.
Use your normal OpenClaw Docker setup for its state directory, authentication, and Gateway startup. The sidecar does not mount your OpenClaw state, browser cookies, or host Docker socket.
For Podman, use an installed Compose provider and verify service-name DNS before
choosing the sidecar URL. A netavark installation without its aardvark-dns
helper can start a loopback-published engine while leaving container DNS broken;
successful engine startup does not prove sidecar connectivity.
Native Linux and macOS
Download the release binary for your operating system and CPU from
Lightpanda 1.0.2.
The sample's deploy/lightpanda/SHA256SUMS records the release asset digests.
For Linux x86-64, run from the repository root:
For macOS Apple silicon:
Use lightpanda-aarch64-linux for Linux ARM64 or
lightpanda-x86_64-macos for Intel macOS. Only execute the downloaded binary after
its checksum matches. Linux release binaries require glibc; use the official
container image on musl-based systems such as Alpine. These commands run the
engine in the foreground; stop it with Ctrl+C.
Configure an opt-in profile
Merge this browser block into your existing configuration:
Use profile: "lightpanda" on browser tool calls. When the selected workload has
passed your checks, set browser.defaultProfile to "lightpanda" to make it the
default. Preserve your Chromium profile and select it explicitly for visual or
unsupported work. Restore the previous defaultProfile to undo the selection.
engine declares the capability contract; a CDP endpoint alone does not imply
Chromium compatibility. attachOnly means OpenClaw attaches to the service you
started instead of launching or taking ownership of a local Chrome process.
Do not set executablePath to Lightpanda: its CLI is not Chrome's launch CLI.
Session and capability limits
- A Lightpanda CDP connection owns its page state. Closing the connection, stopping the container, or restarting the engine loses that state; reconnecting does not resume the previous page or login.
- One CDP connection supports one page target. Separate connections can coexist, but a Lightpanda profile is not a general multi-tab Chromium session.
- No automatic cross-engine replay occurs after an action fails. A click or form submission may already have happened; inspect its outcome before repeating it.
- Lightpanda's text-layout preview is not a rendered screenshot. It cannot prove CSS, image, font, or visual-layout correctness.
- The verified snapshot path is AI format with
ariareferences. The engine selects those references by default, including efficient snapshot mode. Explicit role references, selector/frame-scoped snapshots, labeled screenshots, and the separateariasnapshot format are unsupported in this adapter. - JavaScript and web APIs are not a guarantee that every website will work. Verify the sites and interaction patterns you actually use.
- Lightpanda 1.0.2 enforces CORS by default. Cross-origin fetch/XHR requests need
the destination's appropriate CORS headers; the sample does not disable this
protection. The engine also takes its language from
--localeinstead of falling back to English.
The engine and its session model are documented in the pinned Lightpanda source. See browser profiles and remote browsers for the shared profile and routing rules.
Page classification and judge
Browser action="judge" triages page blockers with the calling agent's selected
Decision model, without returning page text to the
primary model. It reads up to 6,000 body-text characters from the existing tab,
adds the untrusted-content wrapper, and returns the typed Decision outcome.
It works with both text-capable Chromium and Lightpanda profiles. The bundled
browser-automation skill explains the separate loading,
empty-results, login, consent, bot-challenge, paywall, error, and unsupported-browser
questions. It is explicit, advisory work, not automatic navigation policy.
Use the selected provider only when page data is authorized for that destination. Hosted Decision providers can charge; a local browser does not imply local inference. Missing tools or unavailable inference leave ordinary browser inspection available, not an automatic model/engine fallback. Missing, uncertain, or all-low blocker scores do not prove usable content, especially on blank or truncated pages. Consent, login, CAPTCHA, and payment actions still need their normal authorization.
This is not native Lightpanda judge() support. As inspected on October 24,
2026, upstream
page.judge()
on the experimental page-classify branch calls the MCP classify tool. The
branch's CDP LP dispatcher
does not expose classification. OpenClaw's adapter uses CDP, so neither an engine
version nor a successful connection establishes this capability. Opening a
separate MCP session would not classify the existing CDP page and its login state.
The upstream classification implementation
builds URL/title/status plus at most 8,192 bytes of semantic-tree content, then
calls TypeSafe.
It is not evidence of embedded model weights or offline inference. Native
integration needs an upstream classification operation that targets the existing
CDP session, with explicit capability discovery and inference configuration.
Until then, do not guess LP.classify/LP.judge methods or forward OpenClaw
credentials into an external browser process.
The released Lightpanda 1.0.2
does not include the experimental classification tool. Python's feature branch
also shortcuts HTTP failures into local flags; these are not model probabilities
and OpenClaw does not fabricate those judgments.
Lightpanda 1.0.2 compatibility
The normal OpenClaw snapshot, reference-based typing/clicking, wait, and text workflow was verified with the Linux x86-64 release binary and Playwright 1.64.0. A successful click response is not proof that the task finished: wait for the expected page state and read it back before reporting success or retrying a submission.
The release improves mouse events inside shadow DOM, but an OpenClaw fixture
with a button in an open shadow root still fails Playwright's hit-target check
(root.elementsFromPoint is not a function). Use Chromium for affected sites;
do not force clicks or replay submissions to hide this compatibility gap.
Upstream's fetch --dump structured_data and fetch --markdown-alternate are
standalone Lightpanda CLI features, not new OpenClaw browser-tool arguments.
The upstream LP.getPageStatus CDP method reports page issues, including
JavaScript errors and failed or skipped resources. It is not exposed as an
OpenClaw browser action, and a clean issue summary alone does not prove task
completion. The adapter's capability limits above remain unchanged.
Verification and benchmarks
Engine startup, CDP connectivity, task completion, and full OpenClaw integration
are separate checks. A running container or a successful Browser.getVersion
does not prove that snapshots, references, and actions work through OpenClaw.
Chromium headless shell baseline
For an alternative without Lightpanda's AGPL engine, first test Chromium's headless shell through the existing Chromium profile. It retains Chromium's third-party license obligations; this is not an MIT-only binary. It does not require another automation daemon or an OpenClaw engine adapter.
Use the repository-pinned Playwright installer rather than an unpinned wrapper:
The second command prints the selected version, platform download, and install
directory. Locate chrome-headless-shell (or chrome-headless-shell.exe on
Windows) in that directory. Linux also needs the browser's system libraries and
fonts; see Linux troubleshooting.
Run from the repository root, quoting paths that contain spaces:
The report labels the requested distribution separately from its Chromium
protocol engine and the observed browser version. --headless-shell selects
the benchmark executable only: it does not install a production browser,
change a profile, or establish binary provenance. Preserve its complete
distribution and LICENSE.headless_shell when reviewing deployment. The installer
also downloads platform helper assets, including FFmpeg; review and retain their
own notices separately. Use
separate invocations for the full Chromium and headless-shell comparisons;
memory or startup savings must be measured, not inferred from download size.
Native engine comparison
Run the opt-in synthetic route benchmark from the repository root after installing development dependencies:
Any binary flag can be used alone. The script creates isolated OpenClaw
state and browser data, serves a local form, then verifies navigation, the default
efficient AI snapshot, reference-based typing/clicking, exactly one form
submission, waiting, and text extraction through the browser route dispatcher.
The Chromium baseline uses OpenClaw's managed headless launch flags and disables
the sandbox for this isolated local fixture; it does not change production
browser configuration. Minimal Linux hosts still need Chromium's shared
libraries and fonts. A task-local installation can be selected using
LD_LIBRARY_PATH and FONTCONFIG_FILE without changing the host's packages.
Lightpanda additionally checks unsupported-operation rejection, its single-page
limit, and stale-target rejection after disconnecting. These checks do not use
an LLM and do not measure model reasoning or end-to-end agent token cost.
--iterations accepts 1 through 100 and counts warm tasks. A separate first
task includes the initial page open and CDP attachment; every warm task includes
navigation and the same form workflow. Native runs also report process startup
and time from startup through the first completed task. Warm percentiles exclude
the first task. Capability/session checks run after the measurement window.
A combined run uses one Node controller and records engine order; its later engine can reuse controller modules already loaded by the earlier engine. The first-task and process-start figures are not cold CLI/controller measurements. Use separate invocations when comparing independently initialized controllers.
The memory fields are maximum sampled process-tree PSS/RSS, not true peaks.
They use Linux /proc with sampling attempts every 50 ms and at task boundaries.
Short-lived processes or transient allocations can be missed. Unsupported hosts
and externally managed engines report null, as do runs with unreadable process
memory, never a guessed engine-memory
figure. Controller RSS is a separate end-of-workload sample, not incremental
controller overhead; do not add independently sampled maxima and call the sum
total peak host memory.
An externally managed engine
Use a dedicated engine instance. External mode closes the benchmark's control connection and its own Chromium tab, but does not stop the engine process:
This example addresses a Docker Desktop engine from its host. The synthetic
fixture listener is explicitly exposed on the host so the container can reach
it; --fixture-host must name the controller from the browser's network, not
from the controller's own network. Linux Docker needs a reachable host address
or a configured host-gateway mapping. The default fixture listener/hostname
remain 127.0.0.1 when those flags are omitted.
External mode reports engine startup and memory as null. Capture the pinned
container/binary version separately with the report. A Windows Node controller
can use the same external-engine interface, but Windows Docker runtime behavior
has not been verified for this sample.
Compare the same deterministic tasks with a pinned Chromium baseline. Record task completion before reporting speed or memory improvements; unsupported or failed work must not be counted as a successful fast result. Report warm and cold runs separately, engine versions, host OS/architecture, client overhead, and whether memory includes the whole process tree or container.
For Docker Desktop, container memory does not include the VM's host overhead. Do not compare a native-process RSS figure with a container-only figure and call the difference total host savings. Keep all benchmark fixtures public or local; do not export an existing logged-in browser profile to make a benchmark pass.
Platform support listed above describes upstream distribution and the deployment topologies, not a claim that every platform has passed the same runtime tests. Record actual platform and container-runtime results with the benchmark report.
