openclaw
Version:
Multi-channel AI gateway with extensible messaging integrations
364 lines (290 loc) • 21.6 kB
Markdown
---
summary: "Use an externally managed Lightpanda browser for JavaScript and DOM tasks"
title: "Lightweight browsers"
read_when:
- You want browser tasks to use a lightweight engine instead of Chromium
- You run OpenClaw or its browser in Docker
- You need the limits of the Lightpanda browser profile
---
# 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 **0.4.1**. 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-3.0-or-later**, not MIT: see its
[pinned source notice](https://github.com/lightpanda-io/browser/blob/614c1640af8065b1972559abef7ca4cea06f8ba3/src/main.zig#L1)
and [license](https://github.com/lightpanda-io/browser/blob/614c1640af8065b1972559abef7ca4cea06f8ba3/LICENSE).
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](https://github.com/openclaw/openclaw/blob/main/deploy/lightpanda/README.md)
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](https://chromium.googlesource.com/chromium/third_party/ffmpeg/+/53fa34a23be9054d25ac2500dbdae9a0e570bb5c/README.chromium) and [mixed-license hyphenation data](https://chromium.googlesource.com/chromium/src/+/971a7443b0c9b0a9b2860529b33331b76077ec62/third_party/hyphenation-patterns/README.chromium). |
| Cloudflare Kitesurf | A [hosted, stateless Browser Run engine](https://developers.cloudflare.com/browser-run/kitesurf/), not a downloadable replacement in this review. Cloudflare's [announcement](https://blog.cloudflare.com/kitesurf/#final-notes) 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](https://github.com/h4ckf0r0day/obscura/blob/1a3169da276d7720732c7b20535474942917fb83/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](https://github.com/vercel-labs/agent-browser/blob/44583ac8385d814ab98cbf40feec97620376b50e/README.md)
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](https://github.com/h4ckf0r0day/obscura/releases/tag/v0.2.3)
was reviewed at commit `1a3169da276d7720732c7b20535474942917fb83`.
Its [lockfile](https://github.com/h4ckf0r0day/obscura/blob/1a3169da276d7720732c7b20535474942917fb83/Cargo.lock)
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](https://www.mozilla.org/en-US/MPL/2.0/FAQ/)
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](https://github.com/h4ckf0r0day/obscura/blob/1a3169da276d7720732c7b20535474942917fb83/.github/workflows/release.yml)
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](https://github.com/lightpanda-io/browser#install).
## Docker with OpenClaw on the host
From the repository root:
```sh
docker compose -f deploy/lightpanda/compose.yaml -f deploy/lightpanda/compose.host.yaml up -d
docker compose -f deploy/lightpanda/compose.yaml -f deploy/lightpanda/compose.host.yaml exec lightpanda /bin/lightpanda version
```
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.
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:
```sh
docker compose -f deploy/lightpanda/compose.yaml -f deploy/lightpanda/compose.host.yaml down
```
## Docker Compose with OpenClaw in a container
Merge the sidecar into the repository's existing Compose project:
```sh
docker compose -f docker-compose.yml -f deploy/lightpanda/compose.yaml up -d lightpanda
```
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 0.4.1](https://github.com/lightpanda-io/browser/releases/tag/0.4.1).
The sample's `deploy/lightpanda/SHA256SUMS` records the release asset digests.
For Linux x86-64, run from the repository root:
```sh
curl --fail --location --output lightpanda-x86_64-linux https://github.com/lightpanda-io/browser/releases/download/0.4.1/lightpanda-x86_64-linux &&
sha256sum --check --ignore-missing deploy/lightpanda/SHA256SUMS &&
chmod +x lightpanda-x86_64-linux &&
LIGHTPANDA_DISABLE_TELEMETRY=1 LIGHTPANDA_DISABLE_CORE_DUMP=1 ./lightpanda-x86_64-linux serve --host 127.0.0.1 --port 9222
```
For macOS Apple silicon:
```sh
curl --fail --location --output lightpanda-aarch64-macos https://github.com/lightpanda-io/browser/releases/download/0.4.1/lightpanda-aarch64-macos &&
shasum --algorithm 256 --check --ignore-missing deploy/lightpanda/SHA256SUMS &&
chmod +x lightpanda-aarch64-macos &&
LIGHTPANDA_DISABLE_TELEMETRY=1 LIGHTPANDA_DISABLE_CORE_DUMP=1 ./lightpanda-aarch64-macos serve --host 127.0.0.1 --port 9222
```
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:
```json5
{
browser: {
profiles: {
lightpanda: {
engine: "lightpanda",
cdpUrl: "ws://127.0.0.1:9222",
attachOnly: true,
},
},
},
}
```
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 `aria` references. The engine
selects those references by default, including efficient snapshot mode.
Explicit role references, selector/frame-scoped snapshots, labeled screenshots,
and the separate `aria` snapshot 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.
The engine and its session model are documented in the
[pinned Lightpanda source](https://github.com/lightpanda-io/browser/tree/0.4.1).
See [browser profiles](/tools/browser/profiles) and
[remote browsers](/tools/browser/remote) for the shared profile and routing rules.
## 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:
```sh
node node_modules/playwright-core/cli.js install chromium-headless-shell
node node_modules/playwright-core/cli.js install --dry-run chromium-headless-shell
```
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](/tools/browser-linux-troubleshooting).
Run from the repository root, quoting paths that contain spaces:
```sh
node --import ./scripts/tsx.mjs extensions/browser/scripts/bench-lightweight.ts --headless-shell "/path/to/chrome-headless-shell" --iterations 10 --output headless-shell-benchmark.json
```
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:
```sh
node --import ./scripts/tsx.mjs extensions/browser/scripts/bench-lightweight.ts --lightpanda /path/to/lightpanda --chromium /path/to/chrome --iterations 10 --output lightweight-benchmark.json
```
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:
```sh
node --import ./scripts/tsx.mjs extensions/browser/scripts/bench-lightweight.ts --endpoint ws://127.0.0.1:9222 --engine lightpanda --fixture-bind 0.0.0.0 --fixture-host host.docker.internal --iterations 10 --output lightweight-container-benchmark.json
```
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.