> ## Documentation Index
> Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-stagehand-v4-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Stagehand

[Stagehand](https://github.com/browserbase/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.

<Note>
  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](https://docs.stagehand.dev).
</Note>

## Quick start with the Stagehand template

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

```bash theme={null}
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:

```bash .env theme={null}
# 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:

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

See the [deploy](/apps/deploy) and [invoke](/apps/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

```bash theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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`:

```typescript theme={null}
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:

```typescript theme={null}
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](/auth/profiles)
* **Live view**: Debug your automations with real-time browser viewing

## Next steps

* Check out [live view](/browsers/live-view) for debugging your automations
* Learn about [stealth mode](/browsers/bot-detection/stealth) for avoiding detection
* Learn how to properly [terminate browser sessions](/browsers/termination)
* Learn how to [deploy](/apps/deploy) your Stagehand app to Kernel