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

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

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:

docker compose -f deploy/lightpanda/compose.yaml -f deploy/lightpanda/compose.host.yaml up -ddocker 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:

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:

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. The sample's deploy/lightpanda/SHA256SUMS records the release asset digests.

For Linux x86-64, run from the repository root:

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:

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:

{  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. See browser profiles and remote browsers 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:

node node_modules/playwright-core/cli.js install chromium-headless-shellnode 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. Run from the repository root, quoting paths that contain spaces:

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:

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:

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.