Stagehand

Getting Started

The fastest way to start using Stagehand

Overview

The Stagehand class is the main entry point for Stagehand v3. It manages browser lifecycle, provides AI-powered automation methods, and handles both local and remote browser environments.

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand(options);
await stagehand.init();

Constructor

new Stagehand()

Create a new Stagehand instance.

const stagehand = new Stagehand(options: V3Options);

V3Options Interface:

interface V3Options {
  env: "LOCAL" | "BROWSERBASE";

  // Browserbase options (required when env = "BROWSERBASE")
  apiKey?: string;
  projectId?: string;
  browserbaseSessionID?: string;
  browserbaseSessionCreateParams?: Browserbase.Sessions.SessionCreateParams;

  // Local browser options
  localBrowserLaunchOptions?: LocalBrowserLaunchOptions;

  // AI/LLM configuration
  model?: ModelConfiguration;
  llmClient?: LLMClient;
  systemPrompt?: string;

  // Behavior options
  selfHeal?: boolean;
  experimental?: boolean;
  domSettleTimeout?: number;
  cacheDir?: string;
  keepAlive?: boolean;
  serverCache?: boolean;

  // Logging options
  verbose?: 0 | 1 | 2;
  logInferenceToFile?: boolean;
  disablePino?: boolean;
  logger?: (line: LogLine) => void;
}

Configuration Parameters

env

"LOCAL" | "BROWSERBASE"

required

Environment to run the browser in.

"LOCAL" - Run browser locally using Chrome/Chromium
"BROWSERBASE" - Run browser on Browserbase cloud platform

Browserbase Options

apiKey

string

Browserbase API key. Required when env is "BROWSERBASE".Can also be set via BROWSERBASE_API_KEY environment variable.

projectId

string

Browserbase project ID. Required when env is "BROWSERBASE".Can also be set via BROWSERBASE_PROJECT_ID environment variable.

browserbaseSessionID

string

Resume an existing Browserbase session by ID instead of creating a new one.

browserbaseSessionCreateParams

object

Additional parameters for Browserbase session creation. See Browserbase documentation for details.

Local Browser Options

localBrowserLaunchOptions

LocalBrowserLaunchOptions

Configuration for local Chrome/Chromium browser.

Show LocalBrowserLaunchOptions

headless

boolean

Run browser in headless mode.Default: true

executablePath

string

Path to Chrome/Chromium executable.

port

number

Fixed Chrome DevTools Protocol (CDP) debugging port for external tool connections.Default: Randomly assigned

args

string[]

Additional Chrome launch arguments.

userDataDir

string

Path to user data directory for browser profile.

viewport

{ width: number; height: number }

Default viewport size.

devtools

boolean

Auto-open DevTools for each tab.Default: false

proxy

object

Proxy configuration.Properties: server, bypass, username, password

ignoreHTTPSErrors

boolean

Ignore HTTPS certificate errors.Default: false

cdpUrl

string

Attach to existing Chrome instance via CDP WebSocket URL.

AI/LLM Configuration

model

ModelConfiguration

Configure the AI model to use for automation. Can be either:

A string in the format "provider/model" (e.g., "openai/gpt-4o", "anthropic/claude-sonnet-4-6")
An object with detailed configuration

Show Model Configuration Object

modelName

string

required

The model name (e.g., “gpt-4o”, “claude-sonnet-4-6”, “gemini-2.5-flash”)

apiKey

string

API key for the model provider (overrides environment variables)

baseURL

string

Base URL for the API endpoint (for custom endpoints or proxies)

llmClient

LLMClient

Provide a custom LLM client implementation instead of using the default.

systemPrompt

string

Custom system prompt to guide AI behavior across all operations.

Behavior Options

selfHeal

boolean

Enable self-healing mode where actions can recover from failures.Default: true

experimental

boolean

Enable experimental features (may change between versions).Default: false

Use with caution in production. Experimental features may break or change between versions without notice.

domSettleTimeout

number

Default timeout for waiting for DOM to stabilize (in milliseconds).Default: 30000

cacheDir

string

Directory path for caching action observations to improve performance.

keepAlive

boolean

Controls whether the browser remains running after stagehand.close() is called or the parent process exits unexpectedly.

true - Browser continues running independently. On Browserbase, the session stays active. Locally, the Chrome process is kept alive.
false - Browser is terminated and resources are cleaned up on close or crash.

When set, this overrides any value in browserbaseSessionCreateParams.keepAlive.Default: false

serverCache

boolean

Enable or disable server-side caching for act(), extract(), and observe() requests. When enabled, repeated calls with the same inputs return instantly without consuming LLM tokens.

Only applies when env is "BROWSERBASE". Has no effect in local environments.

Can be overridden per-call via the serverCache option on act(), extract(), and observe().Default: true

Logging Options

verbose

0 | 1 | 2

Logging verbosity level.

0 - Minimal logging
1 - Standard logging (default)
2 - Detailed debug logging

Default: 1

logInferenceToFile

boolean

Log AI inference details to files for debugging.Default: false

disablePino

boolean

Disable the Pino logging backend (useful for custom logging integrations).Default: false

logger

(line: LogLine) => void

Custom logger function to receive log events.

Methods

init()

Initialize the Stagehand instance and launch the browser.

await stagehand.init(): Promise<void>

Must be called before using any other methods.

close()

Close the browser and clean up resources.

await stagehand.close(options?: { force?: boolean }): Promise<void>

force

boolean

Force close even if already closing.Default: false

When keepAlive is true, calling close() disconnects Stagehand from the browser without terminating it. The browser session continues running independently and can be reconnected to later using browserbaseSessionID. When keepAlive is false (the default), close() fully terminates the browser and cleans up all resources.

agent()

Create an AI agent instance for autonomous multi-step workflows.

stagehand.agent(config?: AgentConfig): AgentInstance

See the agent() reference for detailed documentation.

Properties

page

Access pages for browser automation. Pages are accessed through the context.

// Get the first page (created automatically on init)
const page = stagehand.context.pages()[0];

// Or get the active page
const activePage = stagehand.context.activePage();

// Create a new page
const newPage = await stagehand.context.newPage();

Type: Page The page object provides methods for:

Navigation (goto(), reload(), goBack(), goForward())
Interaction (click(), type(), keyPress(), locator(), deepLocator())
Inspection (url(), title(), screenshot())
JavaScript evaluation (evaluate())

Important: AI-powered methods (act(), extract(), observe()) are called on the stagehand instance, not on the page object.

context

Access the browser context for managing multiple pages.

const context = stagehand.context;

Type: V3Context The context object provides:

newPage() - Create a new page/tab
pages() - Get all open pages
setActivePage(page) - Switch active page

metrics

Get usage metrics for AI operations.

const metrics = await stagehand.metrics;

Returns: Promise<StagehandMetrics> StagehandMetrics Interface:

interface StagehandMetrics {
  // Act metrics
  actPromptTokens: number;
  actCompletionTokens: number;
  actReasoningTokens: number;
  actCachedInputTokens: number;
  actInferenceTimeMs: number;

  // Extract metrics
  extractPromptTokens: number;
  extractCompletionTokens: number;
  extractReasoningTokens: number;
  extractCachedInputTokens: number;
  extractInferenceTimeMs: number;

  // Observe metrics
  observePromptTokens: number;
  observeCompletionTokens: number;
  observeReasoningTokens: number;
  observeCachedInputTokens: number;
  observeInferenceTimeMs: number;

  // Agent metrics
  agentPromptTokens: number;
  agentCompletionTokens: number;
  agentReasoningTokens: number;
  agentCachedInputTokens: number;
  agentInferenceTimeMs: number;

  // Totals
  totalPromptTokens: number;
  totalCompletionTokens: number;
  totalReasoningTokens: number;
  totalCachedInputTokens: number;
  totalInferenceTimeMs: number;
}

history

Get the history of all operations performed.

const history = await stagehand.history;

Returns: Promise<ReadonlyArray<HistoryEntry>> HistoryEntry Interface:

interface HistoryEntry {
  method: "act" | "extract" | "observe" | "navigate";
  parameters: unknown;
  result: unknown;
  timestamp: string;
}

browserbaseSessionID

Browserbase session identifier for the active Browserbase run.

const sessionId = stagehand.browserbaseSessionID;

Type: string | undefined — undefined for LOCAL runs or before init().

browserbaseSessionURL

Shareable link to the active Browserbase session dashboard.

const sessionUrl = stagehand.browserbaseSessionURL;

Type: string | undefined — undefined until a Browserbase session is active.

browserbaseDebugURL

Debugger URL returned by Browserbase for direct CDP inspection.

const debugUrl = stagehand.browserbaseDebugURL;

Type: string | undefined — undefined for LOCAL runs or if Browserbase doesn’t provide one.

Code Examples

import { Stagehand } from "@browserbasehq/stagehand";

// Remote browser on Browserbase
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  model: "anthropic/claude-sonnet-4-6"
});

await stagehand.init();
const page = stagehand.context.pages()[0];

await page.goto("https://example.com");
const data = await stagehand.extract("get page title", z.object({
  title: z.string()
}));

await stagehand.close();

import { Stagehand } from "@browserbasehq/stagehand";

// Local browser
const stagehand = new Stagehand({
  env: "LOCAL",
  model: "openai/gpt-4o"
});

await stagehand.init();
const page = stagehand.context.pages()[0];

// Use the page
await page.goto("https://example.com");
await stagehand.act("click the login button");

// Cleanup
await stagehand.close();

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "LOCAL",
  model: {
    modelName: "gpt-4o",
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: "https://custom-proxy.com/v1"
  },
  systemPrompt: "You are a helpful automation assistant.",
  verbose: 2,
  selfHeal: true
});

await stagehand.init();

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();

// Get the first page
const page1 = stagehand.context.pages()[0];
await page1.goto("https://example.com");

// Create second page
const page2 = await stagehand.context.newPage();
await page2.goto("https://another-site.com");

// Switch active page
stagehand.context.setActivePage(page2);

// Now context.activePage() returns page2
await stagehand.act("click the button");

await stagehand.close();

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "LOCAL",
  model: "openai/gpt-4o"
});

await stagehand.init();
const page = stagehand.context.pages()[0];

await page.goto("https://example.com");
await stagehand.act("fill out the form");
await stagehand.extract("get form data", schema);

// Get usage metrics
const metrics = await stagehand.metrics;
console.log("Total tokens used:", metrics.totalPromptTokens + metrics.totalCompletionTokens);
console.log("Act operations:", {
  tokens: metrics.actPromptTokens + metrics.actCompletionTokens,
  time: metrics.actInferenceTimeMs
});

await stagehand.close();

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "LOCAL",
  verbose: 2,
  logger: (logLine) => {
    console.log(`[${logLine.category}] ${logLine.message}`);
    if (logLine.auxiliary) {
      console.log("Details:", logLine.auxiliary);
    }
  }
});

await stagehand.init();
// All operations will now log through your custom logger

Error Handling

Stagehand methods may throw the following errors:

StagehandInitError - Failed to initialize Stagehand
StagehandNotInitializedError - Methods called before init()
BrowserbaseSessionNotFoundError - Browserbase session not found
MissingLLMConfigurationError - No LLM API key or client configured
MissingEnvironmentVariableError - Required environment variable not set
StagehandEnvironmentError - Invalid environment configuration

Always handle errors appropriately:

try {
  const stagehand = new Stagehand({ env: "LOCAL" });
  await stagehand.init();
  // ... use stagehand
} catch (error) {
  console.error("Stagehand error:", error.message);
} finally {
  await stagehand?.close();
}

Best Practices

Always call init() before using any other methods
Always call close() when done to clean up resources
Use try-finally to ensure cleanup even on errors
Set appropriate timeouts based on your use case
Enable selfHeal for more robust automation
Use metrics to monitor token usage and costs
Configure custom logger for production debugging
Cache directory can significantly improve performance for repeated actions

Environment Variables

Stagehand recognizes the following environment variables:

BROWSERBASE_API_KEY - Browserbase API key
BROWSERBASE_PROJECT_ID - Browserbase project ID
OPENAI_API_KEY - OpenAI API key
ANTHROPIC_API_KEY - Anthropic API key
GOOGLE_API_KEY - Google AI API key

These can be overridden by passing values in the constructor options.

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

Migration Guides

Getting Started

Overview

Constructor

new Stagehand()

Configuration Parameters

Browserbase Options

Local Browser Options

AI/LLM Configuration

Behavior Options

Logging Options

Methods

init()

close()

agent()

Properties

page

context

metrics

history

browserbaseSessionID

browserbaseSessionURL

browserbaseDebugURL

Code Examples

Error Handling

Best Practices

Environment Variables

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

Migration Guides

Getting Started

​Overview

​Constructor

​new Stagehand()

​Configuration Parameters

​Browserbase Options

​Local Browser Options

​AI/LLM Configuration

​Behavior Options

​Logging Options

​Methods

​init()

​close()

​agent()

​Properties

​page

​context

​metrics

​history

​browserbaseSessionID

​browserbaseSessionURL

​browserbaseDebugURL

​Code Examples

​Error Handling

​Best Practices

​Environment Variables

Overview

Constructor

new Stagehand()

Configuration Parameters

Browserbase Options

Local Browser Options

AI/LLM Configuration

Behavior Options

Logging Options

Methods

init()

close()

agent()

Properties

page

context

metrics

history

browserbaseSessionID

browserbaseSessionURL

browserbaseDebugURL

Code Examples

Error Handling

Best Practices

Environment Variables