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.

ℹ️

This guide uses CDP locally. Lightpanda is started as a local process via the @lightpanda/browser npm package. For cloud usage, see the Usage / CDP section.

Install the Lightanda and Stagehand dependencies

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

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

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