--- 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. ## 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.