LightpandaEx

Mix tasks for installing and invoking the Lightpanda headless browser.

LightpandaEx follows the same shape as the Phoenix-maintained esbuild package: it downloads a platform-specific executable into _build, exposes a Mix install task, and lets you define named execution profiles in config/config.exs.

The default tracked Lightpanda binary is 0.3.0.

Installation

If you are going to run Lightpanda in production, add lightpanda_ex as a dependency in all environments but only start it in development:

def deps do
  [
    {:lightpanda_ex, "~> 0.1", runtime: Mix.env() == :dev}
  ]
end

If Lightpanda is only used during development, make it a dev-only dependency:

def deps do
  [
    {:lightpanda_ex, "~> 0.1", only: :dev}
  ]
end

Then configure the Lightpanda release in config/config.exs:

config :lightpanda_ex, version: "0.3.0"

Install the binary:

$ mix lightpanda.install

The executable is kept at _build/lightpanda-TARGET, where TARGET is your system target architecture, such as x86_64-linux or aarch64-macos.

Quick start

LightpandaEx ships with a built-in :default profile that starts a CDP server on 127.0.0.1:9222:

$ mix lightpanda default

This runs:

lightpanda serve --host 127.0.0.1 --port 9222

Profiles

The first argument to mix lightpanda is the execution profile. Profiles are configured in config/config.exs and can set:

• :args - arguments passed to the Lightpanda binary
• :cd - the working directory
• :env - environment variables

For example, define a profile that dumps a page to markdown:

config :lightpanda_ex,
  version: "0.3.0",
  dump: [
    args: ~w(fetch --obey-robots --dump markdown),
    env: %{"LIGHTPANDA_DISABLE_TELEMETRY" => "true"}
  ]

Then run:

$ mix lightpanda dump https://example.com

Arguments passed to the Mix task are appended to the configured profile arguments.

Profiles must be configured in config/config.exs. The Mix tasks load config without starting your application, so they will not pick up settings from config/runtime.exs unless you pass --runtime-config.

Dump a URL

Configure a profile:

config :lightpanda_ex,
  version: "0.3.0",
  dump: [
    args: ~w(fetch --obey-robots --dump markdown --log-format pretty --log-level info),
    env: %{"LIGHTPANDA_DISABLE_TELEMETRY" => "true"}
  ]

Then invoke it with a URL:

$ mix lightpanda dump https://demo-browser.lightpanda.io/campfire-commerce/

Start a CDP server with a custom profile

Configure a profile:

config :lightpanda_ex,
  version: "0.3.0",
  serve: [
    args: ~w(serve --obey-robots --log-format pretty --log-level info --host 127.0.0.1 --port 9222),
    env: %{"LIGHTPANDA_DISABLE_TELEMETRY" => "true"}
  ]

Then start Lightpanda:

$ mix lightpanda serve

Once the CDP server is started, you can connect a Puppeteer or Playwright client to ws://127.0.0.1:9222.

Release tracking

By default, LightpandaEx installs the configured :version:

config :lightpanda_ex, version: "0.3.0"

You can also track Lightpanda nightly builds:

config :lightpanda_ex, release: "nightly"

For stable releases, LightpandaEx tries both tag styles because upstream Lightpanda releases have used both 0.3.0 and v0.2.6-style tags.

Custom download URL or mirror

The default binary URL template is:

https://github.com/lightpanda-io/browser/releases/download/$version/lightpanda-$target

You can override it with a mirror or local cache:

config :lightpanda_ex,
  url: "https://my-mirror.example.com/lightpanda/$version/lightpanda-$target"

The $version placeholder receives the configured release (0.3.0, v0.2.6, or nightly). The $target placeholder receives the detected platform target.

Manual binary path

If you manage Lightpanda outside this package, set :path:

config :lightpanda_ex, path: System.get_env("MIX_LIGHTPANDA_PATH")

You can disable the boot-time version warning when using an external binary:

config :lightpanda_ex, version_check: false

Supported targets

LightpandaEx supports the binary targets published by Lightpanda:

• x86_64-linux
• aarch64-linux
• x86_64-macos
• aarch64-macos

Lightpanda does not publish a native Windows binary. Use WSL2 and the Linux binary on Windows.

Checksums

LightpandaEx verifies SHA-256 checksums for the tracked stable release (0.3.0). Checksums are skipped with a warning for custom versions or nightly builds that are not known to this package version.

Telemetry

By default, Lightpanda collects and sends usage telemetry. You can disable this by setting LIGHTPANDA_DISABLE_TELEMETRY=true in the profile :env.

API

The public module is LightpandaEx:

LightpandaEx.install()
LightpandaEx.install_and_run(:default, [])
LightpandaEx.run(:dump, ["https://example.com"])
LightpandaEx.bin_path()
LightpandaEx.bin_version()

License

Copyright (c) 2026 Matthew Neel.

The LightpandaEx package source code is licensed under the MIT License.

Lightpanda Browser is licensed separately by the upstream project under the GNU Affero General Public License v3.0.