Stagehand

Stagehand is an open source AI browser automation framework. It lets developers choose what to write in code vs. natural language. By integrating with Kernel, you can run Stagehand automations with cloud-hosted browsers.

This guide targets Stagehand SDK v4. Stagehand v4 runs as a Chrome extension alongside the browser rather than driving it purely over CDP, so a remote Kernel browser needs the extension loaded into it (covered below). If you’re on an earlier version, see the Stagehand migration guide.

Quick start with the Stagehand template

The fastest way to run Stagehand on Kernel is our app template, which comes pre-wired for v4:

kernel create --name my-stagehand-app --language typescript --template stagehand

This scaffolds a self-contained app with two files:

index.ts — the automation (searches a startup on Y Combinator and extracts its team size).
stagehand-extension.ts — a helper that loads the Stagehand extension onto the Kernel browser.

Set a provider-prefixed MODEL and its API key in a .env file:

.env

# MODEL is provider-prefixed, e.g. anthropic/claude-sonnet-4-5, openai/gpt-4.1, google/gemini-2.5-flash
MODEL=anthropic/claude-sonnet-4-5
MODEL_API_KEY=your-api-key

Then deploy and invoke:

kernel deploy index.ts --env-file .env
kernel invoke ts-stagehand teamsize-task --payload '{"company": "kernel"}'
# → {"teamSize":"6"}

See the deploy and invoke guides for more.

Adding Kernel to an existing Stagehand v4 project

If you already have a Stagehand v4 implementation, switch it to Kernel’s cloud browsers with the steps below.

1. Install the Kernel SDK

npm install @onkernel/sdk

Stagehand v4 requires zod v4 for its schema types (it pins zod@4.4.3). If your project is on zod v3, upgrade it.

2. Load the Stagehand extension onto the Kernel browser

Stagehand v4 runs as a Chrome extension. When localBrowser.connect is called without an extensionId, Stagehand loads the extension into the running browser over CDP (Extensions.loadUnpacked), reading it from a path on the browser’s filesystem. Mirror the extension — shipped inside the @browserbasehq/stagehand package — onto the running Kernel browser at that exact path first:

import { Kernel } from "@onkernel/sdk";
import { createReadStream } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";

const stagehandDist = dirname(fileURLToPath(import.meta.resolve("@browserbasehq/stagehand")));
const STAGEHAND_EXTENSION_ZIP = join(stagehandDist, "assets/stagehand-extension.zip");
const STAGEHAND_EXTENSION_DIR = join(stagehandDist, "extension");

async function loadStagehandExtension(kernel: Kernel, sessionId: string): Promise<void> {
  await kernel.browsers.fs.uploadZip(sessionId, {
    dest_path: STAGEHAND_EXTENSION_DIR,
    zip_file: createReadStream(STAGEHAND_EXTENSION_ZIP),
  });
}

3. Create a browser and connect

Create a Kernel browser, load the extension, then connect Stagehand to its CDP URL:

import { Stagehand, localBrowser } from "@browserbasehq/stagehand";
import Kernel from "@onkernel/sdk";

const kernel = new Kernel();

const kernelBrowser = await kernel.browsers.create({ stealth: true });
console.log("Live view url:", kernelBrowser.browser_live_view_url);

await loadStagehandExtension(kernel, kernelBrowser.session_id);

// With no `extensionId`, Stagehand loads the extension over CDP.
const browser = await localBrowser.connect({ cdpUrl: kernelBrowser.cdp_ws_url });

const stagehand = await Stagehand.create({
  browser,
  model: {
    modelName: "anthropic/claude-sonnet-4-5",
    apiKey: process.env.MODEL_API_KEY,
  },
});

4. Use your Stagehand automation

Drive the page with Stagehand’s primitives. Note the v4 API: page access is async (activePage()), and extract returns its result under data:

import { z } from "zod";

const page = await browser.context.activePage();
if (!page) throw new Error("No active page in the Kernel browser");
await page.goto("https://www.ycombinator.com/companies");

await stagehand.act("Type in kernel into the search box");
await stagehand.act("Click on the first search result");

const { data } = await stagehand.extract(
  "Extract the team size (number of employees) shown on this Y Combinator company page.",
  z.object({ teamSize: z.string() }),
);

console.log("Team size:", data.teamSize);

5. Clean up

Stagehand v4 only closes browsers it launched, so close the connection and delete the Kernel browser yourself. Nest the cleanup so a failed close() never skips deleting the browser:

try {
  await stagehand.close();
} finally {
  try {
    await browser.close();
  } finally {
    await kernel.browsers.deleteByID(kernelBrowser.session_id);
  }
}

Benefits of using Kernel with Stagehand

No local browser management: Run automations without installing or maintaining browsers locally
Scalability: Launch multiple browser sessions in parallel
Stealth mode: Built-in anti-detection features for web scraping
Session state: Maintain browser state across runs via Profiles
Live view: Debug your automations with real-time browser viewing

Next steps

Check out live view for debugging your automations
Learn about stealth mode for avoiding detection
Learn how to properly terminate browser sessions
Learn how to deploy your Stagehand app to Kernel

Overview

Working with your browser

deploying your agent

Agent Skills

Integrations

Migrations

Community

Info

Quick start with the Stagehand template

Adding Kernel to an existing Stagehand v4 project

1. Install the Kernel SDK

2. Load the Stagehand extension onto the Kernel browser

3. Create a browser and connect

4. Use your Stagehand automation

5. Clean up

Benefits of using Kernel with Stagehand

Next steps

​Quick start with the Stagehand template

​Adding Kernel to an existing Stagehand v4 project

​1. Install the Kernel SDK

​2. Load the Stagehand extension onto the Kernel browser

​3. Create a browser and connect

​4. Use your Stagehand automation

​5. Clean up

​Benefits of using Kernel with Stagehand

​Next steps

Quick start with the Stagehand template

Adding Kernel to an existing Stagehand v4 project

1. Install the Kernel SDK

2. Load the Stagehand extension onto the Kernel browser

3. Create a browser and connect

4. Use your Stagehand automation

5. Clean up

Benefits of using Kernel with Stagehand

Next steps