Download the video

Prerequisites Copy Chapter

• Lightpanda installed and on your PATH.
• A Hacker News account.
• An LLM API key for the natural-language sections (Anthropic, OpenAI,
  Gemini, Hugging Face or a local Ollama). Recorded .js PandaScripts need no key.

Export your HN credentials as LP_* env vars. The LP_ prefix
matters for security: Lightpanda only resolves these placeholders
inside its own subprocess (so your password never reaches the LLM),
and the getEnv tool refuses any variable that doesn't start with
LP_ (so the LLM can't read your other secrets).

export LP_HN_USERNAME="your-hn-handle"
export LP_HN_PASSWORD="your-hn-password"

Check the variables are set. If one is missing, /fill will silently
type the literal $LP_HN_USERNAME into the form rather than your
username:

lightpanda agent --no-llm

> /getEnv LP_HN_USERNAME

1. Start the REPL Copy Chapter

lightpanda agent

The startup banner shows whether natural language is available;
/model prints the resolved model. REPL history lives in .lp-history
in the working directory.

> /help            # list every browser tool
> /help goto       # JSON schema for one tool
> /quit

No API key? lightpanda agent --no-llm runs the slash-commands-only
REPL.

2. Run a single task Copy Chapter

Before doing anything complicated, run a one-shot task to check
everything works:

lightpanda agent --task "what is the top story on news.ycombinator.com?"

--task runs one user turn, prints the answer on stdout, exits.
Tool calls and progress go to stderr, so redirecting gives you a
clean answer:

lightpanda agent --task "top story on news.ycombinator.com?" > out.txt

Use -a (repeatable) to attach local files.

3. Log in to Hacker News Copy Chapter

Paste these into the REPL in order:

> /goto https://news.ycombinator.com/login
> /fill selector='form[action="login"] input[name="acct"]' value='$LP_HN_USERNAME'
> /fill selector='form[action="login"] input[name="pw"]' value='$LP_HN_PASSWORD'
> /click selector='form[action="login"] input[type="submit"][value="login"]'
> /waitForSelector '#logout'

A few things worth knowing:

• Slash commands only. click '#foo' is forwarded to the LLM;
  only /click '#foo' runs as a command. TAB completes tool names.
• /waitForSelector '#logout' is both a sync point and an
  assertion. It blocks until HN's logged-in DOM renders. If the
  credentials are wrong (or the website throws a captcha, or the layout
  changes), the command times out at the line where the failure
  actually happened. Use this pattern after every state-changing
  action.
• Selectors are CSS only. The click-family tools (/click,
  /fill, /hover, /selectOption, /setChecked) accept CSS
  only. Backend node IDs are invalidated by any DOM mutation and
  can't be serialized into recordings.

Confirm the login worked:

> /extract '{"karma": "#karma"}'
{"karma":"42"}

/extract takes a JSON schema and prints one JSON object to stdout.
Schema grammar:

• "<sel>": text of the first match.
• ["<sel>"]: text of every match.
• {"selector": "<sel>", "attr": "<name>"}: attribute of the first match.
• [{"selector": "<sel>", "fields": {…}}]: array of records, with
  each fields entry resolved relative to the matched element.

Now go to the front page and pull the story list:

> /goto https://news.ycombinator.com
> /extract '''
{
  "topStories": [{
    "selector": ".athing",
    "fields": {
      "rank": ".rank",
      "title": ".titleline > a",
      "url": {"selector": ".titleline > a", "attr": "href"}
    }
  }]
}
'''

Triple-quoted values let a schema span multiple lines.

How we got those selectors Copy Section

Skip this if you're happy treating them as given.

/tree prints the semantic tree. On the login page you'll see two
forms (login and signup) with unlabeled textboxes, which means
/findElement role=textbox name=username returns nothing.

/detectForms reads the HTML directly and surfaces each form's
action plus each input's name. The first form has action: "login"
and fields named acct and pw, which gives us the form-scoped
selector (form[action="login"] input[name="acct"]) that won't
collide with signup.

/nodeDetails backendNodeId=<n> is the alternative: it returns a
ready-to-use CSS selector for any node ID from /tree.

4. Save the session as a script Copy Chapter

Retype the login plus front-page sequence in a single REPL session,
then:

> /save hn_login.js
> /quit

In --no-llm mode, /save transcribes the session deterministically.
With an LLM, it synthesizes an idiomatic script. The result is
JavaScript:

const page = new Page();
await page.goto("https://news.ycombinator.com/login");
page.fill({ selector: "form[action=\"login\"] input[name=\"acct\"]", value: "$LP_HN_USERNAME" });
page.fill({ selector: "form[action=\"login\"] input[name=\"pw\"]", value: "$LP_HN_PASSWORD" });
page.click({ selector: "form[action=\"login\"] input[type=\"submit\"][value=\"login\"]" });
page.waitForSelector("#logout");
await page.goto("https://news.ycombinator.com");
return page.extract({ topStories: [{ selector: ".athing", fields: { rank: ".rank", title: ".titleline > a", url: { selector: ".titleline > a", attr: "href" } } }] });

Only state-mutating commands are recorded; read-only ones (/tree,
/markdown) are dropped. /extract is recorded because it shapes
what the script returns.

5. Replay the script without an LLM Copy Chapter

lightpanda agent hn_login.js

No --provider, no API key, no token spend. Whatever the script
returns is printed automatically as JSON. Because the saved script
ends with return page.extract(...), you get clean JSON on stdout:

lightpanda agent hn_login.js > stories.json

From inside the REPL, /load hn_login.js runs the same script against
the current session.

To reshape the output, assign the result and end with return <value>
(what you return is what prints):

const page = new Page();
await page.goto("https://news.ycombinator.com");

const topStories = page.extract({
  topStories: [{
    selector: ".athing",
    fields: {
      rank: ".rank",
      title: ".titleline > a",
      url: { selector: ".titleline > a", attr: "href" }
    }
  }]
});

return topStories;

6. Add your own JavaScript logic Copy Chapter

Agent scripts run in a separate JavaScript context from the page. No
window, document, DOM API, require, or process. Browser
interaction happens through the Page object: new Page() makes a
page, await page.goto(url) navigates it, and every other primitive is
a synchronous method on it.

Use page.extract(...) to move page data into local logic, then
process it with normal JavaScript:

const page = new Page();
await page.goto("https://news.ycombinator.com");

const topStories = page.extract({
  topStories: [{
    selector: ".athing",
    limit: 5,
    fields: {
      rank: ".rank",
      title: ".titleline > a",
      url: { selector: ".titleline > a", attr: "href" }
    }
  }]
});

return topStories.map((s) => ({ rank: s.rank, title: s.title, url: s.url }));

Use page.evaluate(...) only when you intentionally want a string to
run in the page's JavaScript context. Page evaluate cannot see agent
variables or call agent primitives.

7. Use Lightpanda from another agent (MCP) Copy Chapter

If you're driving Lightpanda from a different agent (Claude Code, a
custom MCP client, your own harness), use lightpanda mcp instead.
The calling agent supplies the LLM, so Lightpanda needs no API key.

{
  "mcpServers": {
    "lightpanda": {
      "command": "/path/to/lightpanda",
      "args": ["mcp"]
    }
  }
}

Drive the browser with the usual tools (goto, fill, click,
waitForSelector), then hand back a script with the save tool:

{
  "tool": "save",
  "args": {
    "path": "hn_login.js",
    "script": "const page = new Page();\nawait page.goto(\"...\");\n..."
  }
}

The path must be relative and free of ... Literal LP_* values are
scrubbed back to placeholders before the file is written. The output
runs unmodified:

lightpanda agent hn_login.js

Further reading Copy Chapter

• Agent: full documentation reference,
• PandaScript: runtime, primitives,
  return values.

File: src/content/guides/markdown-axtree.mdx Copy Chapter

title: Markdown and AXTree Copy Chapter

import { Tabs } from 'nextra/components'
import { Callout } from 'nextra/components'

Markdown and AXTree

Lightpanda outputs web page content as Markdown and Accessibility tree directly from its browser engine, after JavaScript execution. No external HTML-to-Markdown converter needed.

Overview Copy Chapter

Three ways to get Markdown and Accessibility tree from any web page:

CLI: `fetch --dump` Copy Chapter

The fetch command fetches a URL, executes JavaScript, and dumps the result to stdout. Runs standalone with no browser session or CDP connection needed.

Syntax Copy Section

lightpanda fetch --dump <format> [options] <URL>

# Formats:
#   html                Full rendered HTML (post-JS)
#   markdown            CommonMark markdown
#   semantic_tree       JSON accessibility tree
#   semantic_tree_text  Human-readable accessibility tree

Output formats Copy Section

The same page (example.com) in three output formats. Markdown strips all non-semantic markup for a smaller representation.

Basic example Copy Section

lightpanda fetch --dump markdown https://example.com

Example output

# Example Domain

This domain is for use in documentation examples without needing permission. Avoid use in operations.

[Learn more](https://iana.org/domains/example)

`--with-frames` flag Copy Section

Includes rendered iframe content in the output. Without it, iframe content is excluded.

# Without iframe content (default)
lightpanda fetch --dump markdown https://example.com

# With iframe content included
lightpanda fetch --dump markdown --with-frames https://example.com

On pages without iframes, output is identical either way.

`--strip-mode` flag Copy Section

Removes groups of tags from the output. Values can be combined with commas:

# Remove JavaScript and CSS from output
lightpanda fetch --dump html --strip-mode js,css https://example.com

# Keep only the main content, reader-mode style
lightpanda fetch --dump html --strip-mode clutter https://example.com

Find all options in the fetch command reference.

Semantic tree output Copy Section

The semantic_tree format returns the page's accessibility tree as structured JSON:

lightpanda fetch --dump semantic_tree https://example.com

Each node includes:

Example output (first two levels)

{
  "nodeId": "1",
  "backendDOMNodeId": 1,
  "nodeName": "root",
  "xpath": "",
  "nodeType": 9,
  "children": [{
    "nodeId": "2",
    "backendDOMNodeId": 2,
    "nodeName": "html",
    "xpath": "/html[1]",
    "nodeType": 1,
    "isInteractive": false,
    "role": "none",
    "attributes": {"lang": "en"},
    "children": ["..."]
  }]
}

The semantic_tree_text format outputs the same data in a compact readable form:

lightpanda fetch --dump semantic_tree_text https://example.com

Example output

[1] RootWebArea: Example Domain
  [5] heading: Example Domain
  [6] paragraph:
    [7] StaticText: This domain is for use in documentation examples without needing permission. Avoid use in operations.
  [8] paragraph:
    [9] link: Learn more

The CLI semantic_tree and the CDP Accessibility.getFullAXTree return different JSON schemas. The CLI uses flat field names (role, name as strings); CDP uses typed objects (e.g., role: { type: "role", value: "heading" }). See CDP: Accessibility tree for the CDP schema.

CDP: `LP.getMarkdown` Copy Chapter

In server mode (lightpanda serve), Lightpanda exposes a WebSocket CDP endpoint with a custom LP domain. LP.getMarkdown converts the current page's live DOM to Markdown.

Unlike --dump markdown which processes a URL from scratch, LP.getMarkdown converts the DOM at call time. You can click, fill forms, or wait for dynamic content, then call it to capture the current state.

Starting the CDP server Copy Section

# Start CDP server (default: ws://127.0.0.1:9222)
lightpanda serve

# Custom host and port
lightpanda serve --host 0.0.0.0 --port 9333

# Verify it's running
curl http://127.0.0.1:9222/json/version

Using `LP.getMarkdown` Copy Section

<Tabs items={['Puppeteer', 'Playwright']} className="-mb-4">
<Tabs.Tab id="Playwright" className="m-0">

// install: npm install playwright-core
import { chromium } from 'playwright-core';

const browser = await chromium.connectOverCDP('ws://127.0.0.1:9222');
const context = await browser.newContext();
const page = await context.newPage();

await page.goto('https://example.com');

const client = await page.context().newCDPSession(page);
const result = await client.send('LP.getMarkdown', {});
console.log(result.markdown);

await page.close();
await context.close();
await browser.close();

</Tabs.Tab>
<Tabs.Tab id="Puppeteer" className="m-0">

// install: npm install puppeteer-core
import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9222',
});

const context = await browser.createBrowserContext();
const page = await context.newPage();
const client = await page.createCDPSession();

await page.goto('https://example.com', { waitUntil: 'networkidle0' });

const result = await client.send('LP.getMarkdown', {});
console.log(result.markdown);

await page.close();
await context.close();
await browser.disconnect();

</Tabs.Tab>

LP.getMarkdown works the same way locally or on Lightpanda Cloud.

LP.getMarkdown supports converting a sub-portion of the page by targeting specific DOM nodes, useful for skipping headers, footers, and sidebars.

CDP: Accessibility tree Copy Chapter

Lightpanda supports the standard CDP Accessibility.getFullAXTree command, returning the complete accessibility tree as a structured array of nodes, compatible with Chrome's CDP implementation.

Usage with Puppeteer Copy Section

const client = await page.createCDPSession();
const result = await client.send('Accessibility.getFullAXTree', {});

console.log(JSON.stringify(result.nodes, null, 2));
console.log(`Total nodes: ${result.nodes.length}`);

Usage with Playwright Copy Section

const client = await page.context().newCDPSession(page);
const result = await client.send('Accessibility.getFullAXTree', {});
console.log(JSON.stringify(result.nodes, null, 2));

AX node structure Copy Section

Example node shape

{
  "nodeId": 6,
  "backendDOMNodeId": 6,
  "role": { "type": "role", "value": "heading" },
  "ignored": false,
  "name": {
    "type": "computedString",
    "value": "Example Domain",
    "sources": [{ "type": "contents" }]
  },
  "properties": [
    { "name": "level", "value": { "type": "integer", "value": 1 } }
  ],
  "parentId": 5,
  "childIds": [9]
}

For example.com, the CDP accessibility tree contains 12 nodes.

MCP server Copy Chapter

Lightpanda includes a built-in MCP (Model Context Protocol) server for direct integration with AI tools and LLM frameworks.

lightpanda mcp

The MCP server exposes markdown and semantic_tree tools.

For full MCP server documentation — tools, resources, handshake protocol, agent configuration, and HTTP transport — see the MCP server guide and the MCP tools reference.

References Copy Chapter

• Native Markdown Output in Lightpanda
• Playwright markdown demo
• Puppeteer markdown demo
• Playwright AX tree demo
• Puppeteer AX tree demo
• Lightpanda releases
• Cloudflare: Markdown for Agents

File: src/content/guides/retrieve-an-html-webpage.mdx Copy Chapter

title: Retrieve an HTML webpage Copy Chapter

import { Callout, Tabs } from 'nextra/components'

Retrieve an HTML webpage

In this guide, you'll connect a CDP client to Lightpanda and extract all reference links from a Wikipedia page.

Unlike curl, which only fetches raw HTML, Lightpanda executes JavaScript and runs query selectors directly in the browser — making it suitable for dynamic pages.

Prerequisites Copy Chapter

You'll need Node.js installed on your computer.

Create a hn-scraper directory and initialize a new Node.js project. You can accept all the default values in the npm init prompts.

mkdir hn-scraper && \
  cd hn-scraper && \
  npm init

Install the lightpanda and the puppeteer-core or playwright-core npm packages.

<Tabs items={['puppeteer', 'playwright']} className="-mb-4">
<Tabs.Tab id="puppeteer" className="m-0">

npm install --save puppeteer-core @lightpanda/browser

</Tabs.Tab>
<Tabs.Tab id="playwright" className="m-0">

npm install --save playwright-core @lightpanda/browser

</Tabs.Tab>

This guide uses a local Lightpanda instance — see installation for setup details. The code can be adapted to connect to Lightpanda Cloud.

Create index.js Copy Chapter

Create an index.js file. Import the packages, configure the connection, and set up the browser lifecycle:

<Tabs items={['puppeteer', 'playwright']} className="-mb-4">
<Tabs.Tab id="puppeteer" className="m-0">

'use strict'

import { lightpanda } from '@lightpanda/browser';
import puppeteer from 'puppeteer-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const puppeteeropts = {
  browserWSEndpoint: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Puppeteer to the browser.
  const browser = await puppeteer.connect(puppeteeropts);
  const context = await browser.createBrowserContext();
  const page = await context.newPage();

  // Disconnect Puppeteer.
  await page.close();
  await context.close();
  await browser.disconnect();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

</Tabs.Tab>
<Tabs.Tab id="playwright" className="m-0">

'use strict'

import { lightpanda } from '@lightpanda/browser';
import { chromium } from 'playwright-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const playwrightopts = {
  endpointURL: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Playwright's chromium driver to the browser.
  const browser = await chromium.connectOverCDP(playwrightopts);
  const context = await browser.newContext({});
  const page = await context.newPage();

  // Disconnect Playwright.
  await page.close();
  await context.close();
  await browser.close();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

</Tabs.Tab>

Navigate and extract Copy Chapter

Use page.goto to navigate to the Wikipedia page, then run a query selector to extract all external reference links:

<Tabs items={['puppeteer', 'playwright']} className="-mb-4">
<Tabs.Tab id="puppeteer" className="m-0">

// Go to Wikipedia page.
  await page.goto("https://en.wikipedia.org/wiki/Web_browser");

  // Extract all links from the references list of the page.
  const reflist = await page.evaluate(() => {
    return Array.from(document.querySelectorAll('.references a.external')).map(row => {
      return row.getAttribute('href');
    });
  });

  // Display the result.
  console.log("all reference links", reflist);

</Tabs.Tab>
<Tabs.Tab id="playwright" className="m-0">

// Go to Wikipedia page.
  await page.goto("https://en.wikipedia.org/wiki/Web_browser");

  // Extract all links from the references list of the page.
  const reflist = await page.locator('.references a.external').evaluateAll(links =>
    links.map(link => link.getAttribute('href'))
  );

  // Display the result.
  console.log("all reference links", reflist);

</Tabs.Tab>

Full script Copy Chapter

<Tabs items={['puppeteer', 'playwright']} className="-mb-4">
<Tabs.Tab id="puppeteer" className="m-0">

'use strict'

import { lightpanda } from '@lightpanda/browser';
import puppeteer from 'puppeteer-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const puppeteeropts = {
  browserWSEndpoint: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Puppeteer to the browser.
  const browser = await puppeteer.connect(puppeteeropts);
  const context = await browser.createBrowserContext();
  const page = await context.newPage();

  // Go to Wikipedia page.
  await page.goto("https://en.wikipedia.org/wiki/Web_browser");

  // Extract all links from the references list of the page.
  const reflist = await page.evaluate(() => {
    return Array.from(document.querySelectorAll('.references a.external')).map(row => {
      return row.getAttribute('href');
    });
  });

  // Display the result.
  console.log("all reference links", reflist);

  // Disconnect Puppeteer.
  await page.close();
  await context.close();
  await browser.disconnect();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

</Tabs.Tab>
<Tabs.Tab id="playwright" className="m-0">

'use strict'

import { lightpanda } from '@lightpanda/browser';
import { chromium } from 'playwright-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const playwrightopts = {
  endpointURL: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Playwright's chromium driver to the browser.
  const browser = await chromium.connectOverCDP(playwrightopts);
  const context = await browser.newContext({});
  const page = await context.newPage();

  // Go to Wikipedia page.
  await page.goto("https://en.wikipedia.org/wiki/Web_browser");

  // Extract all links from the references list of the page.
  const reflist = await page.locator('.references a.external').evaluateAll(links =>
    links.map(link => link.getAttribute('href'))
  );

  // Display the result.
  console.log("all reference links", reflist);

  // Disconnect Playwright.
  await page.close();
  await context.close();
  await browser.close();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

</Tabs.Tab>

Run it Copy Chapter

node index.js

$ node index.js
🐼 Running Lightpanda's CDP server... { pid: 34389 }
all reference links [
  'https://gs.statcounter.com/browser-market-share',
  'https://radar.cloudflare.com/reports/browser-market-share-2024-q1',
  'https://web.archive.org/web/20240523140912/https://www.internetworldstats.com/stats.htm',
  'https://www.internetworldstats.com/stats.htm',
  'https://www.reference.com/humanities-culture/purpose-browser-e61874e41999ede',
  ...
]

File: src/content/guides/use-hermes.mdx Copy Chapter

title: Use Hermes Agent Copy Chapter

import { Callout } from 'nextra/components'

Use Hermes Agent

Hermes Agent is an open source autonomous agent built by Nous Research. It runs autonomously for long stretches, builds persistent memory, spawns subagents in parallel, and reaches you on Telegram, Discord, Slack, and other platforms while working on a remote VM.

Hermes has two browser drivers, and Lightpanda plugs into both:

• Browser Use mode — the default since August 2026. The agent gets a single browser_exec tool that runs Python against a browser over CDP through the Browser Use CLI.
• Built-in browser tools (browser_navigate, browser_snapshot, …) — the older driver, which reaches browsers through agent-browser.

Pick the section below that matches your driver. The setting is the same (browser.engine: lightpanda), what differs is what else has to be true for Hermes to honour it.

Prerequisites Copy Chapter

• Hermes Agent v0.21.0 or later (hermes update, then hermes --version)
• Lightpanda installed and on your PATH — check with which lightpanda

If you don't have Lightpanda yet, follow the installation guide. Hermes and agent-browser also look in ~/.lightpanda/lightpanda and ~/.local/bin/lightpanda.

Option A — Browser Use mode (the Hermes default) Copy Chapter

Since Hermes v0.21.0, Browser Use mode honours browser.engine: lightpanda natively: Hermes starts lightpanda serve itself, one process per session, and hands its endpoint to the Browser Use CLI for every browser_exec call.

Either pick Lightpanda in hermes tools → Browser Automation, or set it in ~/.hermes/config.yaml:

browser:
  cloud_provider: local
  engine: lightpanda

cloud_provider: local matters: browser.engine is the lowest-precedence browser setting in Hermes. It is ignored whenever a cloud provider is active — and on a setup that never picked a browser, any BROWSERBASE_API_KEY, BROWSER_USE_API_KEY or Nous subscription browser in ~/.hermes/.env selects one automatically. A browser.cdp_url / /browser connect override takes precedence too. Since v0.21.0, /browser status and hermes doctor tell you when the engine is set but shadowed, and by what.

Option B — Built-in browser tools Copy Chapter

Switch Hermes off Browser Use mode and select Lightpanda as the local engine:

# ~/.hermes/config.yaml
browser:
  backend: "off"
  cloud_provider: local
  engine: lightpanda

(/browser use off inside Hermes writes backend: "off" for you.)

The same precedence rules as Option A apply (cloud_provider: local, no CDP override), plus one more: Camoufox (CAMOFOX_URL) also wins over browser.engine on this path.

Hermes drives Lightpanda through agent-browser --engine lightpanda over CDP, the same way it drives local Chrome, with automatic Chrome fallback: Lightpanda handles navigate, snapshot, click, type, scroll, back, press and eval; screenshots, browser_vision, PDF generation, file uploads and anything that errors on Lightpanda are retried on Chrome.

Verify the configuration Copy Chapter

Start Hermes and run /browser status.

Option A shows the engine and the binary Hermes will spawn:

Engine: Lightpanda — Browser Use mode: Hermes spawns `lightpanda serve` per session

If it instead reports browser.engine is 'lightpanda' but it is NOT in use: …, the message names what is shadowing it (a cloud provider, a CDP override, …); see the troubleshooting list below.

Option B shows the engine:

🌐 Browser: local Lightpanda (agent-browser --engine lightpanda)
   ⚡ Lightpanda: faster navigation, no screenshot support
   Automatic Chromium fallback for screenshots and failed commands

Then try a prompt that involves browsing:

Visit https://news.ycombinator.com and list the top 5 story titles.

To prove the engine rather than trust the status line, ask the agent for navigator.userAgent: Lightpanda reports Lightpanda/1.0.

Troubleshooting: Hermes uses Chrome even though I set the engine Copy Chapter

Check, in this order:

1. Is Hermes up to date? Browser Use mode only reads browser.engine from v0.21.0; run hermes update. From there, /browser status and hermes doctor say outright when the engine is shadowed.
2. Is a cloud provider selected? browser.cloud_provider in config.yaml, or a cloud API key / Nous subscription browser on a never-configured setup. Set cloud_provider: local.
3. Is a CDP override active? browser.cdp_url or a previous /browser connect (undo with /browser disconnect).
4. Is Camoufox selected? Unset CAMOFOX_URL.
5. Linux sandbox flags on Hermes older than v0.21.0 (Option B, see the warning above).
6. Nightly --timeout rejection (Option B, see Prerequisites): run lightpanda serve --timeout 1 by hand; FATAL app : unknown argument means agent-browser cannot launch this build.

Further reading Copy Chapter

• Hermes browser documentation
• Lightpanda installation guide

File: src/content/guides/use-stagehand.mdx Copy Chapter

title: Use Stagehand Copy Chapter

import { Callout } from 'nextra/components'

Use Stagehand with Lightpanda

Stagehand is a popular, open
source AI Browser Automation
Framework.

With Stagehand you can use natural language and code to control browser.

Since Lightpanda supports Accessibilty
tree, you can use it
instead of Chrome with your Stagehand script.

Install the Lightanda and Stagehand dependencies Copy Chapter

If not set, create a new npm project and install Stagehand depencies.

npm init

npm install @browserbasehq/stagehand@3 @lightpanda/browser

Stay on the Stagehand 3.x line. Stagehand 4 moved its DOM work into a Chrome
extension that localBrowser.connect() loads through the CDP Extensions
domain, which Lightpanda does not implement, so 4.x cannot connect. The API in
this guide is the 3.x one.

Write your Stagehand script with Lightpanda Copy Chapter

Now you can create your Stagehand's. script to connectm by editing index.js
file.

'use strict'

import { lightpanda } from '@lightpanda/browser';

import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v3";

const lpdopts = { host: '127.0.0.1', port: 9222 };

const stagehandopts = {
  // Enable LOCAL env to configure the CDP url manually in the launch options.
  env: "LOCAL",
  localBrowserLaunchOptions: {
      cdpUrl: 'ws://' + lpdopts.host + ':' + lpdopts.port,
  },
  // You need an ANTHROPIC_API_KEY env var.
  model: "anthropic/claude-haiku-4-5",
  verbose: 0,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  try {
    // Connect Stagehand to the browser.
    const stagehand = new Stagehand(stagehandopts);

    await stagehand.init();

    // Impportant: in the official documentation, Stagehand uses the default
    // existing page. But Lightpanda requires an explicit page's creation
    // instead.
    const page = await stagehand.context.newPage();

    await page.goto('https://demo-browser.lightpanda.io/amiibo/', {waitUntil: "networkidle"});
    const name = await stagehand.extract("Extract character's name", z.string());
    console.log("===", name);

    await stagehand.close()

  } finally {
    // Stop Lightpanda browser process.
    proc.stdout.destroy();
    proc.stderr.destroy();
    proc.kill();
  }
})();

Run your script Copy Chapter

Before running you script, make sure you have a valid Anthropic api key
exported into the env var ANTHROPIC_API_KEY.
You can also use another
model supported by
Stagehand.

node index.js

You should see in the following logs:

=== Sandy

File: src/content/run-locally/installation/build-from-sources.mdx Copy Chapter

title: Build from sources Copy Chapter

import { Callout } from 'nextra/components'

Build from sources

Prerequisites Copy Chapter

Lightpanda is written with Zig 0.14.0. You will have to
install it with the right version in order to build the project.

You need also to install Rust for building deps.

Lightpanda also depends on
zig-js-runtime (with v8),
Libcurl and html5ever.

To be able to build the v8 engine for zig-js-runtime, you have to install some libs:

For Debian/Ubuntu based Linux:

sudo apt install xz-utils ca-certificates \
        pkg-config libglib2.0-dev \
        clang make curl git

For MacOS, you need Xcode and the following pacakges from homebrew:

brew install cmake

Build and run Copy Chapter

You can build the entire browser with make build or make build-dev for debug
env.

But you can directly use the zig command to run in debug mode:

zig build run

Embed v8 snapshot Copy Section

Lighpanda uses v8 snapshot. By default, it is created on startup but you can
embed it by using the following commands:

Generate the snapshot.

zig build snapshot_creator -- src/snapshot.bin

Build using the snapshot binary.

zig build -Dsnapshot_path=../../snapshot.bin

See #1279 for more details.

Telemetry Copy Chapter

By default, Lightpanda collects and sends usage telemetry. This can be disabled by setting an environment variable LIGHTPANDA_DISABLE_TELEMETRY=true. You can read Lightpanda's privacy policy at: https://lightpanda.io/privacy-policy.

2. Official Technical Reference & Guides (lightpanda-io/docs) Copy Chapter

File: src/content/guides/configure-a-proxy.mdx Copy Chapter

title: Use a proxy Copy Chapter

import { Tabs } from 'nextra/components'

Use a proxy

Lightpanda supports using your own proxy, both locally and on Lightpanda Cloud. On Lightpanda Cloud, you can also use a shared proxy we provide instead.

<Tabs items={['Local', 'Cloud']}>
<Tabs.Tab>

Use a proxy locally Copy Chapter

To use a proxy, start Lightpanda from the command line with --http-proxy followed by an HTTP or HTTPS proxy address. All outgoing requests go through the proxy, regardless of the protocol your client uses to connect to Lightpanda.

The examples below use serve, but fetch, mcp, and agent accept these options too.

lightpanda serve --http-proxy http://127.0.0.1:3000

Authenticate with basic auth Copy Section

Add basic auth credentials to the proxy address with the username:password@ format.

lightpanda serve --http-proxy 'http://me:[email protected]:3000'

Authenticate with a bearer token Copy Section

--proxy-bearer-token authenticates with bearer auth. It adds a Proxy-Authorization header to all outgoing requests.

lightpanda serve --http-proxy 'http://127.0.0.1:3000' --proxy-bearer-token 'MY-TOKEN'

Authenticate from your script Copy Section

You can also pass the proxy credentials from your Puppeteer or Playwright script instead of the command line.

Selenium can't do this, because Lightpanda does not support proxy authentication over WebDriver BiDi. Put the credentials in the --http-proxy URL instead.

<Tabs items={['Puppeteer', 'Playwright']}>
<Tabs.Tab>
With Puppeteer, you have to configure the proxy address when starting
Lightpanda.

lightpanda serve --http-proxy 'http://127.0.0.1:3000'

Then you can call page.authenticate function to inject your authentication
from your script.

const page = await context.newPage();

// Set credentials for HTTP Basic Auth
await page.authenticate({
  username: 'my_username',
  password: 'my_password',
});

You can find the full example in our
demo repository.
</Tabs.Tab>
<Tabs.Tab>
With Playwright, configure the proxy when creating the browser's context.

const context = await browser.newContext({
    baseURL: baseURL,
    proxy: {
      server: 'http://127.0.0.1:3000',
      username: 'my_username',
      password: 'my_password',
    },
});

const page = await context.newPage();

You can find the full example in our
demo repository.
</Tabs.Tab>

</Tabs.Tab>
<Tabs.Tab>

Use a proxy on Lightpanda Cloud Copy Chapter

Add the proxy query parameter to the connection URL to route the session through a proxy. You have two options: use a shared proxy, or add your own.

Use a shared proxy Copy Section

Every account can use two shared proxies.

• fast_dc: the default. A single shared datacenter IP, optimized for speed. Each region has its own, so the IP depends on the endpoint you connect to.
• datacenter: a pool of shared datacenter IPs with automatic rotation. Accepts an optional country parameter (two-letter country code) to target a specific country.

wss://euwest.cloud.lightpanda.io/ws?proxy=datacenter&country=de&token=TOKEN

Omit proxy and the session uses fast_dc. Contact us for additional proxy options.

Use your own proxy Copy Section

Add your proxy on the proxies page in the console, then pass its identifier as the proxy parameter. The console generates the identifier and shows it on the proxy's card. It is not the name you gave the proxy.

wss://euwest.cloud.lightpanda.io/ws?proxy=xK4mP2qR&token=TOKEN

The kind you set on the proxy, datacenter or residential, is a label. It does not change how the session connects.
</Tabs.Tab>

File: src/content/guides/interact-with-a-webpage.mdx Copy Chapter

title: Interact with a webpage Copy Chapter

import { Callout, Tabs } from 'nextra/components'

Interact with a webpage

In this guide, you'll use Lightpanda to run a search on HackerNews, wait for dynamic results to load, and extract structured data from the page.

This example requires Lightpanda because HackerNews uses XHR requests to display search results — raw HTML fetching wouldn't capture them.

Prerequisites Copy Chapter

You'll need Node.js installed on your computer.

Create a hn-scraper directory and initialize a new Node.js project. You can accept all the default values in the npm init prompts.

mkdir hn-scraper && \
  cd hn-scraper && \
  npm init

Install the lightpanda and the puppeteer-core or playwright-core npm package.

<Tabs items={['puppeteer', 'playwright']} className="-mb-4">
<Tabs.Tab id="puppeteer" className="m-0">

npm install --save puppeteer-core @lightpanda/browser

</Tabs.Tab>
<Tabs.Tab id="playwright" className="m-0">

npm install --save playwright-core @lightpanda/browser

</Tabs.Tab>

This guide uses a local Lightpanda instance — see installation for setup details. The code can be adapted to connect to Lightpanda Cloud.

Create index.js Copy Chapter

Create an index.js file. Import the packages, configure the connection, and set up the browser lifecycle:

<Tabs items={['puppeteer', 'playwright']} className="-mb-4">
<Tabs.Tab id="puppeteer" className="m-0">

'use strict'

import { lightpanda } from '@lightpanda/browser';
import puppeteer from 'puppeteer-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const puppeteeropts = {
  browserWSEndpoint: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Puppeteer to the browser.
  const browser = await puppeteer.connect(puppeteeropts);
  const context = await browser.createBrowserContext();
  const page = await context.newPage();

  // Disconnect Puppeteer.
  await page.close();
  await context.close();
  await browser.disconnect();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

</Tabs.Tab>
<Tabs.Tab id="playwright" className="m-0">

'use strict'

import { lightpanda } from '@lightpanda/browser';
import { chromium } from 'playwright-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const playwrightopts = {
  endpointURL: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Playwright's chromium driver to the browser.
  const browser = await chromium.connectOverCDP(playwrightopts);
  const context = await browser.newContext({});
  const page = await context.newPage();

  // Disconnect Playwright.
  await page.close();
  await context.close();
  await browser.close();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

</Tabs.Tab>

Navigate and search Copy Chapter

Navigate to HackerNews, type a search term, and press Enter:

<Tabs items={['puppeteer', 'playwright']} className="-mb-4">
<Tabs.Tab id="puppeteer" className="m-0">

await page.goto("https://news.ycombinator.com/");

  await page.type('input[name="q"]', 'lightpanda');
  await page.keyboard.press('Enter');

</Tabs.Tab>
<Tabs.Tab id="playwright" className="m-0">

await page.goto("https://news.ycombinator.com/");

  await page.locator('input[name="q"]').fill('lightpanda');
  await page.keyboard.press('Enter');

</Tabs.Tab>

Wait for results Copy Chapter

Wait for the search results to appear, with a 5 second timeout:

<Tabs items={['puppeteer', 'playwright']} className="-mb-4">
<Tabs.Tab id="puppeteer" className="m-0">

await page.waitForFunction(() => {
    return document.querySelector('.Story_container') != null;
  }, { timeout: 5000 });

</Tabs.Tab>
<Tabs.Tab id="playwright" className="m-0">

await page.waitForSelector('.Story_container', { timeout: 5000 });

</Tabs.Tab>

Extract the data Copy Chapter

Loop over the results to extract the title, URL, and metadata for each story:

<Tabs items={['puppeteer', 'playwright']} className="-mb-4">
<Tabs.Tab id="puppeteer" className="m-0">

const res = await page.evaluate(() => {
    return Array.from(document.querySelectorAll('.Story_container')).map(row => {
      return {
        title: row.querySelector('.Story_title span').textContent,
        url: row.querySelector('.Story_title a').getAttribute('href'),
        meta: Array.from(row.querySelectorAll('.Story_meta > span:not(.Story_separator, .Story_comment)')).map(row => {
          return row.textContent;
        }),
      }
    });
  });

  console.log(res);

</Tabs.Tab>
<Tabs.Tab id="playwright" className="m-0">

const res = await page.evaluate(() => {
    return Array.from(document.querySelectorAll('.Story_container')).map(row => {
      return {
        title: row.querySelector('.Story_title span').textContent,
        url: row.querySelector('.Story_title a').getAttribute('href'),
        meta: Array.from(row.querySelectorAll('.Story_meta > span:not(.Story_separator, .Story_comment)')).map(row => {
          return row.textContent;
        }),
      }
    });
  });

  console.log(res);

</Tabs.Tab>

Full script Copy Chapter

<Tabs items={['puppeteer', 'playwright']} className="-mb-4">
<Tabs.Tab id="puppeteer" className="m-0">

'use strict'

import { lightpanda } from '@lightpanda/browser';
import puppeteer from 'puppeteer-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const puppeteeropts = {
  browserWSEndpoint: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Puppeteer to the browser.
  const browser = await puppeteer.connect(puppeteeropts);
  const context = await browser.createBrowserContext();
  const page = await context.newPage();

  // Go to hackernews home page.
  await page.goto("https://news.ycombinator.com/");

  // Type the search term and submit.
  await page.type('input[name="q"]', 'lightpanda');
  await page.keyboard.press('Enter');

  // Wait until the search results are loaded.
  await page.waitForFunction(() => {
    return document.querySelector('.Story_container') != null;
  }, { timeout: 5000 });

  // Loop over search results to extract data.
  const res = await page.evaluate(() => {
    return Array.from(document.querySelectorAll('.Story_container')).map(row => {
      return {
        title: row.querySelector('.Story_title span').textContent,
        url: row.querySelector('.Story_title a').getAttribute('href'),
        meta: Array.from(row.querySelectorAll('.Story_meta > span:not(.Story_separator, .Story_comment)')).map(row => {
          return row.textContent;
        }),
      }
    });
  });

  console.log(res);

  // Disconnect Puppeteer.
  await page.close();
  await context.close();
  await browser.disconnect();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

</Tabs.Tab>
<Tabs.Tab id="playwright" className="m-0">

'use strict'

import { lightpanda } from '@lightpanda/browser';
import { chromium } from 'playwright-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const playwrightopts = {
  endpointURL: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Playwright's chromium driver to the browser.
  const browser = await chromium.connectOverCDP(playwrightopts);
  const context = await browser.newContext({});
  const page = await context.newPage();

  // Go to hackernews home page.
  await page.goto("https://news.ycombinator.com/");

  // Type the search term and submit.
  await page.locator('input[name="q"]').fill('lightpanda');
  await page.keyboard.press('Enter');

  // Wait until the search results are loaded.
  await page.waitForSelector('.Story_container', { timeout: 5000 });

  // Loop over search results to extract data.
  const res = await page.evaluate(() => {
    return Array.from(document.querySelectorAll('.Story_container')).map(row => {
      return {
        title: row.querySelector('.Story_title span').textContent,
        url: row.querySelector('.Story_title a').getAttribute('href'),
        meta: Array.from(row.querySelectorAll('.Story_meta > span:not(.Story_separator, .Story_comment)')).map(row => {
          return row.textContent;
        }),
      }
    });
  });

  console.log(res);

  // Disconnect Playwright.
  await page.close();
  await context.close();
  await browser.close();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

</Tabs.Tab>

Run it Copy Chapter

node index.js

$ node index.js
🐼 Running Lightpanda's CDP server… { pid: 598201 }
[
  {
    title: 'Show HN: Lightpanda, an open-source headless browser in Zig',
    url: 'https://news.ycombinator.com/item?id=42817439',
    meta: [ '319 points', 'fbouvier', '9 months ago', '137 comments' ]
  },
  {
    title: 'Lightpanda: Headless browser designed for AI and automation',
    url: 'https://news.ycombinator.com/item?id=42812859',
    meta: [ '154 points', 'tosh', '9 months ago', '1 comments' ]
  },
  ...
]

File: src/content/guides/lightpanda-agent-tutorial.mdx Copy Chapter

title: Use Lightpanda Agent Copy Chapter

Use Lightpanda Agent

This tutorial will walk you through how to use Lightpanda Agent to create a
reproducible JavaScript browser script.

Find all flags and REPL commands in the agent command reference.

export LP_HN_USERNAME="your-hn-handle"
export LP_HN_PASSWORD="your-hn-password"

lightpanda agent --no-llm

> /getEnv LP_HN_USERNAME

lightpanda agent

> /help            # list every browser tool
> /help goto       # JSON schema for one tool
> /quit

lightpanda agent --task "what is the top story on news.ycombinator.com?"

lightpanda agent --task "top story on news.ycombinator.com?" > out.txt

> /goto https://news.ycombinator.com/login
> /fill selector='form[action="login"] input[name="acct"]' value='$LP_HN_USERNAME'
> /fill selector='form[action="login"] input[name="pw"]' value='$LP_HN_PASSWORD'
> /click selector='form[action="login"] input[type="submit"][value="login"]'
> /waitForSelector '#logout'

> /extract '{"karma": "#karma"}'
{"karma":"42"}

> /goto https://news.ycombinator.com
> /extract '''
{
  "topStories": [{
    "selector": ".athing",
    "fields": {
      "rank": ".rank",
      "title": ".titleline > a",
      "url": {"selector": ".titleline > a", "attr": "href"}
    }
  }]
}
'''

> /save hn_login.js
> /quit

const page = new Page();
await page.goto("https://news.ycombinator.com/login");
page.fill({ selector: "form[action=\"login\"] input[name=\"acct\"]", value: "$LP_HN_USERNAME" });
page.fill({ selector: "form[action=\"login\"] input[name=\"pw\"]", value: "$LP_HN_PASSWORD" });
page.click({ selector: "form[action=\"login\"] input[type=\"submit\"][value=\"login\"]" });
page.waitForSelector("#logout");
await page.goto("https://news.ycombinator.com");
return page.extract({ topStories: [{ selector: ".athing", fields: { rank: ".rank", title: ".titleline > a", url: { selector: ".titleline > a", attr: "href" } } }] });

lightpanda agent hn_login.js

lightpanda agent hn_login.js > stories.json

const page = new Page();
await page.goto("https://news.ycombinator.com");

const topStories = page.extract({
  topStories: [{
    selector: ".athing",
    fields: {
      rank: ".rank",
      title: ".titleline > a",
      url: { selector: ".titleline > a", attr: "href" }
    }
  }]
});

return topStories;

const page = new Page();
await page.goto("https://news.ycombinator.com");

const topStories = page.extract({
  topStories: [{
    selector: ".athing",
    limit: 5,
    fields: {
      rank: ".rank",
      title: ".titleline > a",
      url: { selector: ".titleline > a", attr: "href" }
    }
  }]
});

return topStories.map((s) => ({ rank: s.rank, title: s.title, url: s.url }));

{
  "mcpServers": {
    "lightpanda": {
      "command": "/path/to/lightpanda",
      "args": ["mcp"]
    }
  }
}

{
  "tool": "save",
  "args": {
    "path": "hn_login.js",
    "script": "const page = new Page();\nawait page.goto(\"...\");\n..."
  }
}

lightpanda agent hn_login.js

lightpanda fetch --dump <format> [options] <URL>

# Formats:
#   html                Full rendered HTML (post-JS)
#   markdown            CommonMark markdown
#   semantic_tree       JSON accessibility tree
#   semantic_tree_text  Human-readable accessibility tree

lightpanda fetch --dump markdown https://example.com

# Example Domain

This domain is for use in documentation examples without needing permission. Avoid use in operations.

[Learn more](https://iana.org/domains/example)

# Without iframe content (default)
lightpanda fetch --dump markdown https://example.com

# With iframe content included
lightpanda fetch --dump markdown --with-frames https://example.com

# Remove JavaScript and CSS from output
lightpanda fetch --dump html --strip-mode js,css https://example.com

# Keep only the main content, reader-mode style
lightpanda fetch --dump html --strip-mode clutter https://example.com

lightpanda fetch --dump semantic_tree https://example.com

{
  "nodeId": "1",
  "backendDOMNodeId": 1,
  "nodeName": "root",
  "xpath": "",
  "nodeType": 9,
  "children": [{
    "nodeId": "2",
    "backendDOMNodeId": 2,
    "nodeName": "html",
    "xpath": "/html[1]",
    "nodeType": 1,
    "isInteractive": false,
    "role": "none",
    "attributes": {"lang": "en"},
    "children": ["..."]
  }]
}

lightpanda fetch --dump semantic_tree_text https://example.com

[1] RootWebArea: Example Domain
  [5] heading: Example Domain
  [6] paragraph:
    [7] StaticText: This domain is for use in documentation examples without needing permission. Avoid use in operations.
  [8] paragraph:
    [9] link: Learn more

# Start CDP server (default: ws://127.0.0.1:9222)
lightpanda serve

# Custom host and port
lightpanda serve --host 0.0.0.0 --port 9333

# Verify it's running
curl http://127.0.0.1:9222/json/version

// install: npm install playwright-core
import { chromium } from 'playwright-core';

const browser = await chromium.connectOverCDP('ws://127.0.0.1:9222');
const context = await browser.newContext();
const page = await context.newPage();

await page.goto('https://example.com');

const client = await page.context().newCDPSession(page);
const result = await client.send('LP.getMarkdown', {});
console.log(result.markdown);

await page.close();
await context.close();
await browser.close();

// install: npm install puppeteer-core
import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9222',
});

const context = await browser.createBrowserContext();
const page = await context.newPage();
const client = await page.createCDPSession();

await page.goto('https://example.com', { waitUntil: 'networkidle0' });

const result = await client.send('LP.getMarkdown', {});
console.log(result.markdown);

await page.close();
await context.close();
await browser.disconnect();

const client = await page.createCDPSession();
const result = await client.send('Accessibility.getFullAXTree', {});

console.log(JSON.stringify(result.nodes, null, 2));
console.log(`Total nodes: ${result.nodes.length}`);

const client = await page.context().newCDPSession(page);
const result = await client.send('Accessibility.getFullAXTree', {});
console.log(JSON.stringify(result.nodes, null, 2));

{
  "nodeId": 6,
  "backendDOMNodeId": 6,
  "role": { "type": "role", "value": "heading" },
  "ignored": false,
  "name": {
    "type": "computedString",
    "value": "Example Domain",
    "sources": [{ "type": "contents" }]
  },
  "properties": [
    { "name": "level", "value": { "type": "integer", "value": 1 } }
  ],
  "parentId": 5,
  "childIds": [9]
}

lightpanda mcp

mkdir hn-scraper && \
  cd hn-scraper && \
  npm init

npm install --save puppeteer-core @lightpanda/browser

npm install --save playwright-core @lightpanda/browser

'use strict'

import { lightpanda } from '@lightpanda/browser';
import puppeteer from 'puppeteer-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const puppeteeropts = {
  browserWSEndpoint: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Puppeteer to the browser.
  const browser = await puppeteer.connect(puppeteeropts);
  const context = await browser.createBrowserContext();
  const page = await context.newPage();

  // Disconnect Puppeteer.
  await page.close();
  await context.close();
  await browser.disconnect();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

'use strict'

import { lightpanda } from '@lightpanda/browser';
import { chromium } from 'playwright-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const playwrightopts = {
  endpointURL: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Playwright's chromium driver to the browser.
  const browser = await chromium.connectOverCDP(playwrightopts);
  const context = await browser.newContext({});
  const page = await context.newPage();

  // Disconnect Playwright.
  await page.close();
  await context.close();
  await browser.close();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

// Go to Wikipedia page.
  await page.goto("https://en.wikipedia.org/wiki/Web_browser");

  // Extract all links from the references list of the page.
  const reflist = await page.evaluate(() => {
    return Array.from(document.querySelectorAll('.references a.external')).map(row => {
      return row.getAttribute('href');
    });
  });

  // Display the result.
  console.log("all reference links", reflist);

// Go to Wikipedia page.
  await page.goto("https://en.wikipedia.org/wiki/Web_browser");

  // Extract all links from the references list of the page.
  const reflist = await page.locator('.references a.external').evaluateAll(links =>
    links.map(link => link.getAttribute('href'))
  );

  // Display the result.
  console.log("all reference links", reflist);

'use strict'

import { lightpanda } from '@lightpanda/browser';
import puppeteer from 'puppeteer-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const puppeteeropts = {
  browserWSEndpoint: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Puppeteer to the browser.
  const browser = await puppeteer.connect(puppeteeropts);
  const context = await browser.createBrowserContext();
  const page = await context.newPage();

  // Go to Wikipedia page.
  await page.goto("https://en.wikipedia.org/wiki/Web_browser");

  // Extract all links from the references list of the page.
  const reflist = await page.evaluate(() => {
    return Array.from(document.querySelectorAll('.references a.external')).map(row => {
      return row.getAttribute('href');
    });
  });

  // Display the result.
  console.log("all reference links", reflist);

  // Disconnect Puppeteer.
  await page.close();
  await context.close();
  await browser.disconnect();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

'use strict'

import { lightpanda } from '@lightpanda/browser';
import { chromium } from 'playwright-core';

const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};

const playwrightopts = {
  endpointURL: 'ws://' + lpdopts.host + ':' + lpdopts.port,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  // Connect Playwright's chromium driver to the browser.
  const browser = await chromium.connectOverCDP(playwrightopts);
  const context = await browser.newContext({});
  const page = await context.newPage();

  // Go to Wikipedia page.
  await page.goto("https://en.wikipedia.org/wiki/Web_browser");

  // Extract all links from the references list of the page.
  const reflist = await page.locator('.references a.external').evaluateAll(links =>
    links.map(link => link.getAttribute('href'))
  );

  // Display the result.
  console.log("all reference links", reflist);

  // Disconnect Playwright.
  await page.close();
  await context.close();
  await browser.close();

  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();

node index.js

$ node index.js
🐼 Running Lightpanda's CDP server... { pid: 34389 }
all reference links [
  'https://gs.statcounter.com/browser-market-share',
  'https://radar.cloudflare.com/reports/browser-market-share-2024-q1',
  'https://web.archive.org/web/20240523140912/https://www.internetworldstats.com/stats.htm',
  'https://www.internetworldstats.com/stats.htm',
  'https://www.reference.com/humanities-culture/purpose-browser-e61874e41999ede',
  ...
]

browser:
  cloud_provider: local
  engine: lightpanda

# ~/.hermes/config.yaml
browser:
  backend: "off"
  cloud_provider: local
  engine: lightpanda

Engine: Lightpanda — Browser Use mode: Hermes spawns `lightpanda serve` per session

🌐 Browser: local Lightpanda (agent-browser --engine lightpanda)
   ⚡ Lightpanda: faster navigation, no screenshot support
   Automatic Chromium fallback for screenshots and failed commands

Visit https://news.ycombinator.com and list the top 5 story titles.

npm init

npm install @browserbasehq/stagehand@3 @lightpanda/browser

'use strict'

import { lightpanda } from '@lightpanda/browser';

import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v3";

const lpdopts = { host: '127.0.0.1', port: 9222 };

const stagehandopts = {
  // Enable LOCAL env to configure the CDP url manually in the launch options.
  env: "LOCAL",
  localBrowserLaunchOptions: {
      cdpUrl: 'ws://' + lpdopts.host + ':' + lpdopts.port,
  },
  // You need an ANTHROPIC_API_KEY env var.
  model: "anthropic/claude-haiku-4-5",
  verbose: 0,
};

(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);

  try {
    // Connect Stagehand to the browser.
    const stagehand = new Stagehand(stagehandopts);

    await stagehand.init();

    // Impportant: in the official documentation, Stagehand uses the default
    // existing page. But Lightpanda requires an explicit page's creation
    // instead.
    const page = await stagehand.context.newPage();

    await page.goto('https://demo-browser.lightpanda.io/amiibo/', {waitUntil: "networkidle"});
    const name = await stagehand.extract("Extract character's name", z.string());
    console.log("===", name);

    await stagehand.close()

  } finally {
    // Stop Lightpanda browser process.
    proc.stdout.destroy();
    proc.stderr.destroy();
    proc.kill();
  }
})();

node index.js

=== Sandy

sudo apt install xz-utils ca-certificates \
        pkg-config libglib2.0-dev \
        clang make curl git

brew install cmake

zig build run

zig build snapshot_creator -- src/snapshot.bin

zig build -Dsnapshot_path=../../snapshot.bin