Lightpanda

https://lightpanda.io/docs
Admin
Lightpanda is an AI-native web browser built from scratch for machines, offering ultra-fast web...
Tokens:37,978
Snippets:475
Trust Score:8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://lightpanda.io/docs/open-source/guides/use-stagehand

Install the required Stagehand and Lightpanda browser packages.

```bash
npm install @browserbasehq/stagehand @lightpanda/browser
```

--------------------------------

### Install dependencies

Source: https://lightpanda.io/docs/guides/use-stagehand

Initialize a new npm project and install the required Stagehand and Lightpanda packages.

```bash
npm init
```

```bash
npm install @browserbasehq/stagehand @lightpanda/browser
```

--------------------------------

### Install Hermes Agent

Source: https://lightpanda.io/docs/guides/use-hermes

Use the official installation script to set up Hermes Agent.

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

--------------------------------

### Starting the Lightpanda REPL

Source: https://lightpanda.io/docs/guides/lightpanda-agent-tutorial

Launch the interactive REPL environment.

```bash
lightpanda agent
```

--------------------------------

### Install dependencies

Source: https://lightpanda.io/docs/guides/retrieve-an-html-webpage

Install the Lightpanda browser package along with either puppeteer-core or playwright-core.

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

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

--------------------------------

### Complete Fetch Request Example

Source: https://lightpanda.io/docs/usage/api

A full cURL command example requesting markdown output for a specific URL.

```bash
$ curl -XPOST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://euwest.cloud.lightpanda.io/api/fetch \
  --data '{"url":"https://example.com", "output_format":"markdown"}'
```

--------------------------------

### Install WSL2 components

Source: https://lightpanda.io/docs/open-source/installation

Commands to set up WSL and Ubuntu on Windows via an administrator shell.

```bash
wsl --install
```

```bash
wsl --install -d Ubuntu
```

```bash
wsl
```

--------------------------------

### Run the script

Source: https://lightpanda.io/docs/quickstart/go-to-production-with-lightpanda-cloud

Execute the script to start and stop the browser.

```bash
node index.js
```

```bash
$ node index.js
🐼 Running Lightpanda's CDP server... { pid: 4084512 }
```

--------------------------------

### Server Startup Output

Source: https://lightpanda.io/docs/open-source/usage

Example output indicating the server is running and listening on the specified address.

```text
INFO  app : server running . . . . . . . . . . . . . . . . .  [+0ms]
      address = 127.0.0.1:9222
```

--------------------------------

### Install Lightpanda via one-liner

Source: https://lightpanda.io/docs/open-source/installation

Installs the latest nightly build on Linux or macOS. Requires curl, jq, and sha256sum.

```bash
curl -fsSL https://pkg.lightpanda.io/install.sh | bash
```

--------------------------------

### Start Hermes Agent

Source: https://lightpanda.io/docs/guides/use-hermes

Launch the Hermes agent after configuration.

```bash
hermes
```

--------------------------------

### Manual binary installation on WSL

Source: https://lightpanda.io/docs/open-source/installation

Downloads the Lightpanda binary and sets execution permissions manually.

```bash
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && \
chmod a+x ./lightpanda
```

--------------------------------

### View browser execution output

Source: https://lightpanda.io/docs/quickstart/your-first-test

Example output when running the browser script.

```bash
$ node index.js
🐼 Running Lightpanda's CDP server... { pid: 4084512 }
```

--------------------------------

### Download and install Lightpanda nightly builds

Source: https://lightpanda.io/docs/run-locally/installation/nightly-builds

Use these commands to download the binary for your specific architecture and make it executable.

```bash

curl -L -o lightpanda \
  https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && \
  chmod a+x ./lightpanda
```

```bash

curl -L -o lightpanda \
  https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-linux && \
  chmod a+x ./lightpanda
```

```bash

curl -L -o lightpanda \
  https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos && \
  chmod a+x ./lightpanda
```

```bash

curl -L -o lightpanda \
  https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-macos && \
  chmod a+x ./lightpanda
```

--------------------------------

### Install Lightpanda with Homebrew

Source: https://lightpanda.io/docs/run-locally/installation/package-managers

Installs the latest nightly version of Lightpanda on macOS.

```bash
brew install lightpanda-io/browser/lightpanda
```

--------------------------------

### Install Lightpanda dependency

Source: https://lightpanda.io/docs/quickstart/go-to-production-with-lightpanda-cloud

Install the Lightpanda browser package using your preferred package manager.

```bash
npm install --save @lightpanda/browser
```

```bash
yarn add @lightpanda/browser
```

```bash
pnpm add @lightpanda/browser
```

--------------------------------

### Example server output

Source: https://lightpanda.io/docs/guides/interact-with-a-webpage

Displays the console output and the JSON structure returned by the server.

```text
$ 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' ]
  },
  ...
]
```

--------------------------------

### Install core browser packages

Source: https://lightpanda.io/docs/quickstart/go-to-production-with-lightpanda-cloud

Use these commands to install the core versions of Puppeteer or Playwright without downloading a full Chromium browser.

```bash
npm install -save puppeteer-core
```

```bash
npm install -save playwright-core
```

--------------------------------

### Install Lightpanda with Arch Linux AUR

Source: https://lightpanda.io/docs/run-locally/installation/package-managers

Installs Lightpanda or the nightly version using the yay AUR helper.

```bash
yay -S lightpanda-bin
```

```bash
yay -S lightpanda-nightly-bin
```

--------------------------------

### Execute REPL Commands

Source: https://lightpanda.io/docs/usage/agent

Examples of positional arguments, key-value pairs, and raw JSON blobs for browser interaction commands.

```text
/goto 'https://example.com'
```

```text
/extract '{"karma":"#karma"}'
```

```text
/fill selector='#email' value='user@x.com'
```

```text
/extract '{"karma":"#karma"}' save=me
```

```text
/findElement {"role":"button"}
```

```text
/click selector='a.login'
```

--------------------------------

### Start Lightpanda MCP Server

Source: https://lightpanda.io/docs/run-locally/commands/mcp

Executes the Lightpanda MCP server over stdio for LLM integration.

```bash
lightpanda mcp
```

--------------------------------

### Start Local Lightpanda CDP Server

Source: https://lightpanda.io/docs/cloud-offer/tools/cdp

Command to initialize the Lightpanda server locally on a specific host and port.

```bash
lightpanda serve --host 127.0.0.1 --port 9222
```

--------------------------------

### Install specific Lightpanda release

Source: https://lightpanda.io/docs/open-source/installation

Installs a specific version of Lightpanda by passing the version tag as an argument.

```bash
curl -fsSL https://pkg.lightpanda.io/install.sh | bash -s "v0.2.5"
```

--------------------------------

### Connect Chromedp to Local Instance

Source: https://lightpanda.io/docs/usage/cdp/chromedp

Example of using NewRemoteAllocator to connect to a local Lightpanda instance.

```go
package main
 
import (
    "context"
    "flag"
    "log"
 
    "github.com/chromedp/chromedp"
)
 
func main() {
    ctx, cancel = chromedp.NewRemoteAllocator(ctx,
        "ws://127.0.0.1:9222", chromedp.NoModifyURL,
    )
    defer cancel()
 
    ctx, cancel := chromedp.NewContext(allocatorContext)
    defer cancel()
 
    var title string
    if err := chromedp.Run(ctx,
        chromedp.Navigate("https://wikipedia.com/"),
        chromedp.Title(&title),
    ); err != nil {
        log.Fatalf("Failed getting page's title: %v", err)
    }
 
    log.Println("Got title of:", title)
}
```

--------------------------------

### Example markdown output

Source: https://lightpanda.io/docs/open-source/guides/markdown-axtree

The resulting markdown output from the fetch command.

```markdown

# Example Domain
 
This domain is for use in documentation examples without needing permission. Avoid use in operations.
 
[Learn more](https://iana.org/domains/example)
```

--------------------------------

### Start Lightpanda CDP Server

Source: https://lightpanda.io/docs/open-source/usage

Launches the Lightpanda server with specific host, port, and robot-obeying configurations.

```bash
lightpanda serve --obey-robots --host 127.0.0.1 --port 9222
```

--------------------------------

### Fetch command output logs

Source: https://lightpanda.io/docs/run-locally/commands/fetch

Example of the console output generated after running the fetch command, showing navigation and script execution details.

```text
INFO  http : navigate . . . . . . . . . . . . . . . . . . . . [+0ms]
      url = https://demo-browser.lightpanda.io/campfire-commerce/
      method = GET
      reason = address_bar
      body = false
 
INFO  browser : executing script . . . . . . . . . . . . . .  [+196ms]
      src = https://demo-browser.lightpanda.io/campfire-commerce/script.js
      kind = javascript
      cacheable = true
 
INFO  http : request complete . . . . . . . . . . . . . . . . [+223ms]
      source = xhr
      url = https://demo-browser.lightpanda.io/campfire-commerce/json/product.json
      status = 200
 
INFO  http : request complete . . . . . . . . . . . . . . . . [+234ms]
      source = xhr
      url = https://demo-browser.lightpanda.io/campfire-commerce/json/reviews.json
      status = 200
<!DOCTYPE html>
```

--------------------------------

### Install dependencies on Debian/Ubuntu

Source: https://lightpanda.io/docs/open-source/guides/build-from-sources

Required system packages for building on Debian or Ubuntu-based Linux distributions.

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

--------------------------------

### Run Lightpanda CDP Server

Source: https://lightpanda.io/docs/guides/retrieve-an-html-webpage

Execute the application using Node.js to start the server and process the target URL.

```bash
node index.js
```

```bash
$ 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',
  ...
]
```

--------------------------------

### Check Hermes Version

Source: https://lightpanda.io/docs/guides/use-hermes

Verify the installed version of Hermes Agent.

```bash
hermes --version
```

--------------------------------

### Create index.js script

Source: https://lightpanda.io/docs/quickstart/go-to-production-with-lightpanda-cloud

A basic script to start and stop the Lightpanda browser instance.

```javascript
'use strict'
 
import { lightpanda } from '@lightpanda/browser';
 
const lpdopts = {
  host: '127.0.0.1',
  port: 9222,
};
 
(async () => {
  // Start Lightpanda browser in a separate process.
  const proc = await lightpanda.serve(lpdopts);
 
  // Do your magic ✨
 
  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();
```

--------------------------------

### Start and Verify Lightpanda CDP Server

Source: https://lightpanda.io/docs/open-source/guides/markdown-axtree

Commands to launch the Lightpanda server and verify the CDP endpoint availability.

```bash
# 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 dependencies on MacOS

Source: https://lightpanda.io/docs/open-source/guides/build-from-sources

Required Homebrew package for building on MacOS.

```bash
brew install cmake
```

--------------------------------

### Cloud Connection Parameters

Source: https://lightpanda.io/docs/usage/cdp/puppeteer

Examples of WebSocket URL parameters for specifying browser types and proxy configurations.

```text
wss://euwest.cloud.lightpanda.io/ws?browser=chrome&token=TOKEN
```

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

--------------------------------

### Configure Cloud Proxy Settings

Source: https://lightpanda.io/docs/cloud-offer/tools/cdp

Example URL parameter to enable datacenter proxy rotation for a specific country.

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

--------------------------------

### Full cloud browser automation scripts

Source: https://lightpanda.io/docs/quickstart/go-to-production-with-lightpanda-cloud

Complete examples for connecting to Lightpanda Cloud and performing web scraping tasks.

```javascript
'use strict'
 
import puppeteer from 'puppeteer-core';
 
const puppeteeropts = {
  browserWSEndpoint: 'wss://euwest.cloud.lightpanda.io/ws?token=' + process.env.LPD_TOKEN,
};
 
(async () => {
  // 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/");
 
  // Find the search box at the bottom of the page and type the term lightpanda
  // to search.
  await page.type('input[name="q"]','lightpanda');
  // Press enter key to run the search.
  await page.keyboard.press('Enter');
 
  // Wait until the search results are loaded on the page, with a 5 seconds
  // timeout limit.
  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 {
        // Extract the title.
        title: row.querySelector('.Story_title span').textContent,
        // Extract the URL.
        url: row.querySelector('.Story_title a').getAttribute('href'),
        // Extract the list of meta data.
        meta: Array.from(row.querySelectorAll('.Story_meta > span:not(.Story_separator, .Story_comment)')).map(row => {
          return row.textContent;
        }),
      }
    });
  });
 
  // Display the result.
  console.log(res);
 
  // Disconnect Puppeteer.
  await page.close();
  await context.close();
  await browser.disconnect();
})();
```

```javascript
'use strict'
 
import { chromium } from 'playwright-core';
 
const playwrightopts = {
  endpointURL: 'wss://euwest.cloud.lightpanda.io/ws?token=' + process.env.LPD_TOKEN,
};
 
(async () => {
  // Connect using 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/");
 
  // Find the search box at the bottom of the page and type the term lightpanda
  // to search.
  await page.locator('input[name="q"]').fill('lightpanda');
  // Press enter key to run the search.
  await page.keyboard.press('Enter');
 
  // Wait until the search results are loaded on the page, with a 5 seconds
  // timeout limit.
  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 {
        // Extract the title.
        title: row.querySelector('.Story_title span').textContent,
        // Extract the URL.
        url: row.querySelector('.Story_title a').getAttribute('href'),
        // Extract the list of meta data.
        meta: Array.from(row.querySelectorAll('.Story_meta > span:not(.Story_separator, .Story_comment)')).map(row => {
          return row.textContent;
        }),
      }
    });
  });
 
  // Display the result.
  console.log(res);
 
  // Disconnect Playwright.
  await page.close();
  await context.close();
  await browser.close();
})();
```

--------------------------------

### Full script implementation

Source: https://lightpanda.io/docs/guides/retrieve-an-html-webpage

Complete scripts for starting the Lightpanda browser process and connecting via Puppeteer or Playwright.

```javascript

'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();
})();
```

```javascript

'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();
})();
```

--------------------------------

### Configure Cloud Browser Type

Source: https://lightpanda.io/docs/cloud-offer/tools/cdp

Example URL parameter to request a specific browser engine in the cloud.

```text
wss://euwest.cloud.lightpanda.io/ws?browser=chrome&token=TOKEN
```

--------------------------------

### Connect Puppeteer to Lightpanda

Source: https://lightpanda.io/docs/usage/cdp/puppeteer

Examples for connecting Puppeteer to local and cloud instances using browserWSEndpoint.

```javascript
'use strict'
 
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()
 
await page.goto('https://wikipedia.com/')
 
const title = await page.title()
console.log(title)
 
await page.close()
await context.close()
await browser.disconnect()
```

```javascript
'use strict'
 
import puppeteer from 'puppeteer-core'
 
const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://euwest.cloud.lightpanda.io/ws?token=' + process.env.LPD_TOKEN,
})
const context = await browser.createBrowserContext()
const page = await context.newPage()
 
// ...
 
await page.close()
await context.close()
await browser.disconnect()
```

--------------------------------

### Connect Chromedp to Cloud Endpoint

Source: https://lightpanda.io/docs/usage/cdp/chromedp

Example of connecting to the Lightpanda cloud service using an API token.

```go
package main
 
import (
	"context"
	"log"
	"os"
 
	"github.com/chromedp/chromedp"
)
 
func main() {
	ctx, cancel := chromedp.NewRemoteAllocator(context.Background(),
		"wss://euwest.cloud.lightpanda.io/ws?token="+os.Getenv("LPD_TOKEN"), chromedp.NoModifyURL,
	)
	defer cancel()
 
	ctx, cancel = chromedp.NewContext(ctx)
	defer cancel()
 
	var title string
	if err := chromedp.Run(ctx,
		chromedp.Navigate("https://lightpanda.io"),
		chromedp.Title(&title),
	); err != nil {
		log.Fatalf("Failed getting title of lightpanda.io: %v", err)
	}
 
	log.Println("Got title of:", title)
}
```

--------------------------------

### Run Lightpanda container

Source: https://lightpanda.io/docs/run-locally/installation/docker

Starts a new Lightpanda container in detached mode and maps the CDP port to the host.

```bash
docker run -d --name lightpanda -p 127.0.0.1:9222:9222 lightpanda/browser:nightly
```

--------------------------------

### Call HTTP MCP Endpoint

Source: https://lightpanda.io/docs/cloud-offer/tools/mcp

Example cURL commands to initialize an MCP session and call the markdown tool over HTTP.

```bash
# Initialize
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
        "params":{"protocolVersion":"2024-11-05","capabilities":{},
                  "clientInfo":{"name":"curl-test","version":"1.0"}}}'
 
# Extract markdown (pass url inline - HTTP is stateless by default)
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
        "params":{"name":"markdown","arguments":{"url":"https://example.com"}}}'
```

--------------------------------

### Initialize Node.js project

Source: https://lightpanda.io/docs/guides/retrieve-an-html-webpage

Create a new directory and initialize a Node.js project.

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

--------------------------------

### Initialize NPM project

Source: https://lightpanda.io/docs/open-source/guides/use-stagehand

Create a new npm project directory.

```bash
npm init
```

--------------------------------

### Update Hermes Agent

Source: https://lightpanda.io/docs/guides/use-hermes

Update an existing Hermes installation to the latest version.

```bash
hermes update
```

--------------------------------

### Semantic tree text output

Source: https://lightpanda.io/docs/open-source/guides/markdown-axtree

Example of the human-readable accessibility tree output.

```text

[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
```

--------------------------------

### Navigation Failure Output

Source: https://lightpanda.io/docs/open-source/guides/mcp-server

Example of the error message returned when a navigation attempt fails.

```text

# Navigation failed

Reason: CouldntResolveHost
```

--------------------------------

### Configure HTTP proxy with basic authentication

Source: https://lightpanda.io/docs/open-source/guides/configure-a-proxy

Include credentials directly in the proxy URL using the username:password@ format.

```bash
lightpanda fetch --http-proxy 'http://me:my-password@127.0.0.1:3000' https://lightpanda.io
```

--------------------------------

### Semantic tree JSON output

Source: https://lightpanda.io/docs/open-source/guides/markdown-axtree

Example of the structured JSON output for the accessibility tree.

```json
{
  "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": ["..."]
  }]
}
```

--------------------------------

### Using REPL commands

Source: https://lightpanda.io/docs/guides/lightpanda-agent-tutorial

Common commands for interacting with the browser tools and managing the session.

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

--------------------------------

### Fetch Request JSON Body

Source: https://lightpanda.io/docs/cloud-offer/tools/api

Example JSON payload for the POST /api/fetch endpoint.

```json
{
  "url": "https://lightpanda.io",
  "output_format": "markdown",
  "wait_ms": 50000,
  "wait_event": "networkIdle",
  "raw": false
}
```

--------------------------------

### Connect to Lightpanda

Source: https://lightpanda.io/docs/quickstart/go-to-production-with-lightpanda-cloud

Initialize the Lightpanda server and connect the browser automation library via CDP.

```javascript
'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();
 
  // Do your magic ✨
  console.log("CDP connection is working");
 
  // Disconnect Puppeteer.
  await page.close();
  await context.close();
  await browser.disconnect();
 
  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();
```

```javascript
'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();
 
  // Do your magic ✨
  console.log("CDP connection is working");
 
  // Disconnect Puppeteer.
  await page.close();
  await context.close();
  await browser.close();
 
  // Stop Lightpanda browser process.
  proc.stdout.destroy();
  proc.stderr.destroy();
  proc.kill();
})();
```

--------------------------------

### Generate and use V8 snapshots

Source: https://lightpanda.io/docs/open-source/guides/build-from-sources

Commands to generate a V8 snapshot and build the project using that snapshot binary.

```bash
zig build snapshot_creator -- src/snapshot.bin
```

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

--------------------------------

### tools/call (goto)

Source: https://lightpanda.io/docs/cloud-offer/tools/mcp

Navigates to a specified URL and loads the page into memory.

```APIDOC
## tools/call (goto)

### Description
Navigate to a URL and load the page into memory.

### Request Example
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"goto","arguments":{"url":"https://example.com"}}}

### Response
"Navigated successfully."
```

--------------------------------

### Configure Lightpanda CLI options

Source: https://lightpanda.io/docs/open-source/usage

List of available command-line flags for customizing server settings, network requests, and logging behavior.

```text
options:
  --host <HOST>
          Host of the CDP server.
          Defaults to "127.0.0.1".
  --port <INT>
          Port of the CDP server.
          Defaults to 9222.
  --advertise-host <HOST>
          The host to advertise, e.g. in the /json/version response. Useful,
          for example, when --host is 0.0.0.0.
          Defaults to --host value.
  --cdp-max-connections <INT>
          Maximum number of simultaneous CDP connections.
          Defaults to 16.
  --cdp-max-pending-connections <INT>
          Maximum pending connections in the accept queue.
          Defaults to 128.
  --cookie <PATH>
          Path to a JSON file to load cookies from (read-only).
          Defaults to no cookie loading.
 
common options:
  --insecure-disable-tls-host-verification
          Disables host verification on all HTTP requests.
          Only set this if you understand and accept the risk.
  --obey-robots
          Fetches and obeys robots.txt of the target page.
          Defaults to false.
  --disable-subframes
          Skip loading <iframe> elements. The parser still registers them in the
          DOM, but no child frame or Page.frameAttached events are produced.
          Defaults to false.
  --disable-workers
          Skip loading dedicated Web Workers. The Worker constructor still
          returns a Worker object, but no script fetch is initiated and its scope
          never runs.
          Defaults to false.
  --enable-external-stylesheets
          Fetch external <link rel=stylesheet> resources so their rules
          contribute to computed styles (and therefore to visibility checks like
          display, visibility, opacity, pointer-events).
          Defaults to false.
  --block-private-networks
          Block HTTP requests to private/internal IP addresses after DNS
          resolution.
          Defaults to false.
  --block-cidrs <LIST>
          Additional CIDR ranges to block, comma-separated.
          Prefix with '-' to allow (exempt from blocking).
          e.g. --block-cidrs 10.0.0.0/8,-10.0.0.42/32
          Can be combined with --block-private-networks.
  --http-proxy <URL>
          HTTP proxy for all HTTP requests.
          username:password may be included for basic auth.
          Defaults to none.
  --proxy-bearer-token <TOKEN>
          Token sent for bearer authentication with the proxy:
          Proxy-Authorization: Bearer <token>.
  --http-max-concurrent <INT>
          Maximum number of concurrent HTTP requests.
          Defaults to 10.
  --http-max-host-open <INT>
          Maximum open connections to a given host:port.
          Defaults to 4.
  --http-connect-timeout <INT>
          Time in ms to establish an HTTP connection before timing out. 0 means
          never.
          Defaults to 0.
  --http-timeout <INT>
          Maximum time in ms the transfer is allowed to complete. 0 means never.
          Defaults to 10000.
  --http-max-response-size <INT>
          Limits the acceptable response size for any request
          e.g. XHR, fetch, script loading.
          Defaults to no limit.
  --ws-max-concurrent <INT>
          Maximum number of concurrent WebSocket connections.
          Defaults to 8.
  --log-level <LEVEL>
          The log level.
          Defaults to warn.
          Allowed values: "debug", "info", "warn", "error", "fatal".
  --log-format <FORMAT>
          The log format.
          Defaults to logfmt.
          Allowed values: "pretty", "logfmt".
  --log-filter-scopes <SCOPES>
          Filter out too-verbose logs per scope, comma-separated.
          e.g. http, unknown_prop, event.
  --user-agent <STRING>
          Override the User-Agent header entirely. Must not impersonate other
          browsers; any value containing "Mozilla" is forbidden. The browser
          still sends Sec-Ch-Ua. Incompatible with --user-agent-suffix.
  --user-agent-suffix <STRING>
          Suffix appended to the Lightpanda/X.Y User-Agent.
  --web-bot-auth-key-file <PATH>
          Path to the Ed25519 private key PEM file.
  --web-bot-auth-keyid <STRING>
          The JWK thumbprint of your public key.
  --web-bot-auth-domain <DOMAIN>
          Your domain, e.g. yourdomain.com.
  --http-cache-dir <PATH>
          Directory used as a filesystem cache for network resources. Omitting
          this disables caching.
          Defaults to no caching.
  --cookie <PATH>
          Path to a JSON file to load cookies from (read-only).
          Defaults to no cookie loading.
  --cookie-jar <PATH>
          Path to a JSON file to save cookies to on exit (write-only).
          Defaults to no cookie saving.
  --storage-engine <ENGINE>
          The storage engine to use.
          Defaults to none.
          Allowed values: "none", "sqlite".
  --storage-sqlite-path <PATH>
          Path to the SQLite database file for persistent storage.
          Use ":memory:" for in-memory storage.
```

--------------------------------

### Configure Stagehand script

Source: https://lightpanda.io/docs/guides/use-stagehand

Create an index.js file to launch Lightpanda locally and connect Stagehand to it via CDP.

```javascript
'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 the connection script

Source: https://lightpanda.io/docs/quickstart/go-to-production-with-lightpanda-cloud

Execute the script and view the output confirming the CDP server is running.

```bash
node index.js
```

```bash
$ node index.js
🐼 Running Lightpanda's CDP server... { pid: 31371 }
CDP connection is working
```

--------------------------------

### Navigate to URLs with Lightpanda

Source: https://lightpanda.io/docs/usage/pandascript

Use goto to navigate to a URL. Timeouts do not throw errors, so verify the return value or use wait methods for completeness.

```javascript

const page = new Page();
await page.goto("https://example.com");
 
await page.goto({
  url: "https://example.com/app",
  timeout: 15000
});
```

--------------------------------

### CLI fetch command syntax

Source: https://lightpanda.io/docs/open-source/guides/markdown-axtree

The basic syntax for the fetch command, including available output formats.

```bash

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
```

--------------------------------

### Navigate to a URL

Source: https://lightpanda.io/docs/cloud-offer/tools/mcp

Navigates to a specified URL and loads the page into memory. Always verify success with a follow-up content call as the tool returns success even if the URL is unreachable.

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"goto","arguments":{"url":"https://example.com"}}}
```

--------------------------------

### Verifying environment variables

Source: https://lightpanda.io/docs/guides/lightpanda-agent-tutorial

Check that credentials are correctly set before running the agent.

```bash
lightpanda agent --no-llm
```

```bash
> /getEnv LP_HN_USERNAME
```

--------------------------------

### Run Browser Command

Source: https://lightpanda.io/docs/guides/use-hermes

Execute the browser slash command to verify the backend status.

```text
/browser
```

--------------------------------

### Accessibility Node JSON Structure

Source: https://lightpanda.io/docs/open-source/guides/markdown-axtree

Example of the JSON object structure returned for an individual node within the accessibility tree.

```json

{
  "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]
}
```

--------------------------------

### Configure Browser Engine

Source: https://lightpanda.io/docs/guides/use-hermes

Set the browser engine to Lightpanda in the configuration file.

```yaml
browser:
  engine: lightpanda
```

--------------------------------

### Lightpanda MCP Configuration Options

Source: https://lightpanda.io/docs/run-locally/commands/mcp

Lists available flags for configuring cookies, network behavior, logging, and storage engines.

```text
options:
  --cookie <PATH>
          Path to a JSON file to load cookies from (read-only).
          Defaults to no cookie loading.
  --cookie-jar <PATH>
          Path to a JSON file to save cookies to on exit (write-only).
          Defaults to no cookie saving.
 
common options:
  --insecure-disable-tls-host-verification
          Disables host verification on all HTTP requests.
          Only set this if you understand and accept the risk.
  --obey-robots
          Fetches and obeys robots.txt of the target page.
          Defaults to false.
  --disable-subframes
          Skip loading <iframe> elements. The parser still registers them in the
          DOM, but no child frame or Page.frameAttached events are produced.
          Defaults to false.
  --disable-workers
          Skip loading dedicated Web Workers. The Worker constructor still
          returns a Worker object, but no script fetch is initiated and its scope
          never runs.
          Defaults to false.
  --enable-external-stylesheets
          Fetch external <link rel=stylesheet> resources so their rules
          contribute to computed styles (and therefore to visibility checks like
          display, visibility, opacity, pointer-events).
          Defaults to false.
  --block-private-networks
          Block HTTP requests to private/internal IP addresses after DNS
          resolution.
          Defaults to false.
  --block-cidrs <LIST>
          Additional CIDR ranges to block, comma-separated.
          Prefix with '-' to allow (exempt from blocking).
          e.g. --block-cidrs 10.0.0.0/8,-10.0.0.42/32
          Can be combined with --block-private-networks.
  --http-proxy <URL>
          HTTP proxy for all HTTP requests.
          username:password may be included for basic auth.
          Defaults to none.
  --proxy-bearer-token <TOKEN>
          Token sent for bearer authentication with the proxy:
          Proxy-Authorization: Bearer <token>.
  --http-max-concurrent <INT>
          Maximum number of concurrent HTTP requests.
          Defaults to 10.
  --http-max-host-open <INT>
          Maximum open connections to a given host:port.
          Defaults to 4.
  --http-connect-timeout <INT>
          Time in ms to establish an HTTP connection before timing out. 0 means
          never.
          Defaults to 0.
  --http-timeout <INT>
          Maximum time in ms the transfer is allowed to complete. 0 means never.
          Defaults to 10000.
  --http-max-response-size <INT>
          Limits the acceptable response size for any request
          e.g. XHR, fetch, script loading.
          Defaults to no limit.
  --ws-max-concurrent <INT>
          Maximum number of concurrent WebSocket connections.
          Defaults to 8.
  --log-level <LEVEL>
          The log level.
          Defaults to warn.
          Allowed values: "debug", "info", "warn", "error", "fatal".
  --log-format <FORMAT>
          The log format.
          Defaults to logfmt.
          Allowed values: "pretty", "logfmt".
  --log-filter-scopes <SCOPES>
          Filter out too-verbose logs per scope, comma-separated.
          e.g. http, unknown_prop, event.
  --user-agent <STRING>
          Override the User-Agent header entirely. Must not impersonate other
          browsers; any value containing "Mozilla" is forbidden. The browser
          still sends Sec-Ch-Ua. Incompatible with --user-agent-suffix.
  --user-agent-suffix <STRING>
          Suffix appended to the Lightpanda/X.Y User-Agent.
  --web-bot-auth-key-file <PATH>
          Path to the Ed25519 private key PEM file.
  --web-bot-auth-keyid <STRING>
          The JWK thumbprint of your public key.
  --web-bot-auth-domain <DOMAIN>
          Your domain, e.g. yourdomain.com.
  --http-cache-dir <PATH>
          Directory used as a filesystem cache for network resources. Omitting
          this disables caching.
          Defaults to no caching.
  --cookie <PATH>
          Path to a JSON file to load cookies from (read-only).
          Defaults to no cookie loading.
  --cookie-jar <PATH>
          Path to a JSON file to save cookies to on exit (write-only).
          Defaults to no cookie saving.
  --storage-engine <ENGINE>
          The storage engine to use.
          Defaults to none.
          Allowed values: "none", "sqlite".
  --storage-sqlite-path <PATH>
          Path to the SQLite database file for persistent storage.
          Use ":memory:" for in-memory storage.
```

--------------------------------

### page.goto

Source: https://lightpanda.io/docs/usage/pandascript

Navigates the browser page to a specified URL.

```APIDOC
## page.goto(url[, options])

### Description
Navigates the page to the given URL.

### Parameters
- **url** (string) - Required - The URL to navigate to.
- **options** (object) - Optional - Configuration object containing timeout settings.
```

--------------------------------

### Run the script

Source: https://lightpanda.io/docs/guides/use-stagehand

Execute the script using Node.js after ensuring the ANTHROPIC_API_KEY environment variable is set.

```bash
node index.js
```

--------------------------------

### Configure browser lifecycle

Source: https://lightpanda.io/docs/guides/retrieve-an-html-webpage

Set up the connection to a local Lightpanda instance and manage the browser lifecycle using Puppeteer or Playwright.

```javascript
'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();
})();
```

```javascript
'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();
})();
```

--------------------------------

### Replay script via CLI

Source: https://lightpanda.io/docs/guides/lightpanda-agent-tutorial

Execute saved scripts directly from the command line without requiring an LLM provider.

```bash
lightpanda agent hn_login.js
```

```bash
lightpanda agent hn_login.js > stories.json
```

--------------------------------

### Exporting Hacker News credentials

Source: https://lightpanda.io/docs/guides/lightpanda-agent-tutorial

Set environment variables with the LP_ prefix to ensure secure access within the Lightpanda subprocess.

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

--------------------------------

### Run Task with File Attachment

Source: https://lightpanda.io/docs/usage/agent

Attach local files to a task using the -a or --attach flag.

```bash
lightpanda agent -a invoice.pdf \
  --task "open shop.example.com/orders/1042 and check the order total matches the attached invoice"
```

--------------------------------

### Configure Connection Options

Source: https://lightpanda.io/docs/quickstart/installation-and-setup

Define the browser connection endpoint using the LPD_TOKEN environment variable.

```javascript

const puppeteeropts = {
  browserWSEndpoint: 'wss://euwest.cloud.lightpanda.io/ws?token=' + process.env.LPD_TOKEN,
};
```

```javascript

const playwrightopts = {
  endpointURL: 'wss://euwest.cloud.lightpanda.io/ws?token=' + process.env.LPD_TOKEN,
};
```
Tokens:
Raw