Browser

Stagehand supports two primary environments:

Browserbase - Cloud-managed browser infrastructure optimized for production web automation at scale
Local - Run browsers directly on your machine for development and debugging

Browserbase Environment

Browserbase provides managed cloud browser infrastructure optimized for web automation at scale. It offers advanced features like stealth mode, proxy support, and persistent contexts.

Browserbase

Discover the power of cloud-managed browser infrastructure with Browserbase.

Multi-Region Support

Stagehand API is available in multiple regions to optimize latency and support data residency requirements. The SDK automatically routes requests to the correct regional API endpoint based on your browser session’s region.

Region	API Endpoint
us-west-2 (Default)	https://api.stagehand.browserbase.com
us-east-1	https://api.use1.stagehand.browserbase.com
eu-central-1	https://api.euc1.stagehand.browserbase.com
ap-southeast-1	https://api.apse1.stagehand.browserbase.com

Configure your browser session region in browserbaseSessionCreateParams:

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

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  browserbaseSessionCreateParams: {
    region: "eu-central-1", // Browser runs in Frankfurt
  },
});

await stagehand.init();

The API endpoint must match your browser session region. If there’s a mismatch, you’ll receive an error: Session is in region 'X' but this API instance serves 'Y'. Please route your request to the X Stagehand API endpoint.

Disabling Stagehand API

If you want to use Stagehand purely as a local library without routing through the Stagehand API, you can disable API mode:

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

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  disableAPI: true, // Disable Stagehand API - runs locally with Browserbase
});

await stagehand.init();

Disabling the API is useful when you want to manage browser sessions directly while still using Stagehand’s automation features locally.

Environment Variables

Before getting started, set up the required environment variables:

BROWSERBASE_API_KEY=your_api_key_here

Get your API key from the Browserbase Dashboard

Using Stagehand with Browserbase

Basic Setup

The simplest way to get started is with default settings:

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

const stagehand = new Stagehand({
  env: "BROWSERBASE",
});

await stagehand.init();

Advanced Configuration

Configure browser settings, proxy support, and other session parameters:

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

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  // Optional: API Key will be pulled directly from your environment
  apiKey: process.env.BROWSERBASE_API_KEY,
  browserbaseSessionCreateParams: {
    proxies: true,
    region: "us-west-2",
    browserSettings: {
      viewport: { width: 1920, height: 1080 },
      blockAds: true,
    },
  },
});

await stagehand.init();
console.log("Session ID:", stagehand.sessionId);

Advanced Browserbase Configuration Example

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  apiKey: process.env.BROWSERBASE_API_KEY,
  browserbaseSessionCreateParams: {
    proxies: true,
    region: "us-west-2",
    timeout: 3600, // 1 hour session timeout
    keepAlive: true, // Available on Startup plan
    browserSettings: {
      verified: false, // this is a Scale Plan feature - reach out to support@browserbase.com to enable
      blockAds: true,
      solveCaptchas: true,
      recordSession: false,
      viewport: {
        width: 1920,
        height: 1080,
      },
    },
    userMetadata: {
      userId: "automation-user-123",
      environment: "production",
    },
  },
});

Alternative: Browserbase SDK

If you prefer to manage sessions directly, you can use the Browserbase SDK:

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ 
  apiKey: process.env.BROWSERBASE_API_KEY! 
});

const session = await bb.sessions.create({
  // Add configuration options here
});

Connecting to an Existing Session

Connect to a previously created Browserbase session using its session ID:

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

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  browserbaseSessionID: "existing-session-uuid-here",
});

await stagehand.init();
console.log("Resumed Session ID:", stagehand.sessionId);

Local Environment

The local environment runs browsers directly on your machine, providing full control over browser instances and configurations. Ideal for development, debugging, and scenarios requiring custom browser setups.

Environment Comparison

Feature	Browserbase	Local
Scalability	High (cloud-managed)	Limited (local resources)
Stealth Features	Advanced fingerprinting	Basic stealth
Proxy Support	Built-in residential proxies	Manual configuration
Session Persistence	Cloud context storage	File-based user data
Geographic Distribution	Multi-region deployment	Single machine
Debugging	Session recordings & logs	Direct DevTools access
Setup Complexity	Environment variables only	Browser installation required
Cost	Usage-based pricing	Infrastructure & maintenance
Best For	Production, scale, compliance	Development, debugging

Basic Local Setup

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

const stagehand = new Stagehand({
  env: "LOCAL"
});
  
await stagehand.init();
console.log("Session ID:", stagehand.sessionId);

Advanced Local Configuration

Customize browser launch options for local development:

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

const stagehand = new Stagehand({
  env: "LOCAL",
  localBrowserLaunchOptions: {
    headless: false, // Show browser window
    devtools: true, // Open developer tools
    viewport: { width: 1280, height: 720 },
    executablePath: '/opt/google/chrome/chrome', // Custom Chrome path
    port: 9222, // Fixed CDP debugging port
    ignoreDefaultArgs: [
      '--site-per-process',
    ], // Remove specific default launch args
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-web-security',
      '--allow-running-insecure-content',
    ],
    userDataDir: './chrome-user-data', // Persist browser data
    preserveUserDataDir: true, // Keep data after closing
    chromiumSandbox: false, // Disable sandbox (adds --no-sandbox)
    ignoreHTTPSErrors: true, // Ignore certificate errors
    locale: 'en-US', // Set browser language
    deviceScaleFactor: 1.0, // Display scaling
    proxy: {
      server: 'http://proxy.example.com:8080',
      username: 'user',
      password: 'pass'
    },
    downloadsPath: './downloads', // Download directory
    acceptDownloads: true, // Allow downloads
    connectTimeoutMs: 30000, // Connection timeout
  },
});

await stagehand.init();

Default Local Launch Arguments

When Stagehand launches a local browser, it adds the following Chrome arguments before any values in localBrowserLaunchOptions.args:

[
  "--remote-allow-origins=*",
  "--no-first-run",
  "--no-default-browser-check",
  "--disable-dev-shm-usage",
  "--site-per-process",
]

Chrome Launcher also adds its own default arguments. To remove default arguments, set localBrowserLaunchOptions.ignoreDefaultArgs:

const stagehand = new Stagehand({
  env: "LOCAL",
  localBrowserLaunchOptions: {
    ignoreDefaultArgs: ["--site-per-process"],
    args: [
      "--disable-features=site-per-process,IsolateOrigins",
      "--renderer-process-limit=6",
    ],
  },
});

Use ignoreDefaultArgs: true to remove all default arguments. Use a string array to remove only exact matches while preserving the rest.

Advanced Configuration

Keep Alive

The keepAlive option controls whether the browser remains running after stagehand.close() is called or when the parent process exits unexpectedly (e.g., crash, SIGTERM, SIGINT). By default, Stagehand terminates the browser and cleans up all resources when it shuts down. Setting keepAlive: true keeps the browser running independently so you can reconnect to it later.

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

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  keepAlive: true,
});

await stagehand.init();

// The browser session continues running after close()
await stagehand.close();

// Later, reconnect to the same session
const stagehand2 = new Stagehand({
  env: "BROWSERBASE",
  browserbaseSessionID: stagehand.browserbaseSessionID,
});
await stagehand2.init();

Behavior by Environment

Behavior	`keepAlive: true`	`keepAlive: false` (default)
Browserbase	Session stays active after `close()`	Session is terminated via API
Local	Chrome process continues running	Chrome process is killed and temp profile is removed
On crash/signal	Browser is left running	Browser is automatically cleaned up

Local Environment

When running locally with keepAlive: true, the Chrome process is detached from the Node.js event loop, allowing your script to exit while the browser stays open. This is useful for debugging or for handing off a browser session to another process.

const stagehand = new Stagehand({
  env: "LOCAL",
  keepAlive: true,
  localBrowserLaunchOptions: {
    headless: false,
  },
});

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

// Browser window stays open after the script exits
await stagehand.close();

Browserbase Environment

On Browserbase, keepAlive: true keeps the cloud session active so you can reconnect later using browserbaseSessionID. This is useful for long-running workflows that span multiple script executions.

The top-level keepAlive option overrides browserbaseSessionCreateParams.keepAlive when both are provided.

Fixed CDP Debugging Port

Specify a fixed Chrome DevTools Protocol (CDP) debugging port instead of using a randomly assigned one.

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

const stagehand = new Stagehand({
  env: "LOCAL",
  localBrowserLaunchOptions: {
    port: 9222,
  },
});

await stagehand.init();

If no port is specified, a random port will be assigned.

DOM Settle Timeout

Configure how long Stagehand waits for the DOM to stabilize before taking actions.

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  domSettleTimeout: 3000 // Wait up to 3 seconds for DOM to settle
});

What is DOM Settling?

DOM settling ensures that:

Animations complete before interacting with elements
Lazy-loaded content has time to appear
JavaScript updates finish before actions are taken
Dynamic content is fully rendered

When to Adjust

Increase domSettleTimeout for pages with:

Heavy animations or transitions
Lazy-loading or infinite scroll
Dynamic JavaScript frameworks (React, Vue, Angular)
Complex single-page applications

// For fast, static pages
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  domSettleTimeout: 500 // Minimal wait
});

// For dynamic, animated pages
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  domSettleTimeout: 5000 // Longer wait for stability
});

Setting domSettleTimeout too low may cause actions to fail on elements that aren’t ready. Setting it too high increases execution time unnecessarily.

Troubleshooting

Browserbase Authentication Errors

Verify your BROWSERBASE_API_KEY is set correctly
Check that your API key has the necessary permissions
Ensure your Browserbase account has sufficient credits

Local Browser Launch Failures

Install Chrome or Chromium on your system
Set the correct executablePath for your Chrome installation
Check that required dependencies are installed (Linux: libnss3-dev libatk-bridge2.0-dev libgtk-3-dev libxss1 libasound2)

Session Timeout Issues

Increase session timeout in browserbaseSessionCreateParams.timeout
Use keepAlive: true for long-running sessions
Monitor session usage to avoid unexpected terminations

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

Migration Guides

Browserbase Environment

Browserbase

Multi-Region Support

Disabling Stagehand API

Environment Variables

Using Stagehand with Browserbase

Basic Setup

Advanced Configuration

Alternative: Browserbase SDK

Connecting to an Existing Session

Local Environment

Environment Comparison

Basic Local Setup

Advanced Local Configuration

Default Local Launch Arguments

Advanced Configuration

Keep Alive

Behavior by Environment

Local Environment

Browserbase Environment

Fixed CDP Debugging Port

DOM Settle Timeout

What is DOM Settling?

When to Adjust

Troubleshooting

​Browserbase Environment

Browserbase

​Multi-Region Support

​Disabling Stagehand API

​Environment Variables

​Using Stagehand with Browserbase

​Basic Setup

​Advanced Configuration

​Alternative: Browserbase SDK

​Connecting to an Existing Session

​Local Environment

​Environment Comparison

​Basic Local Setup

​Advanced Local Configuration

​Default Local Launch Arguments

​Advanced Configuration

​Keep Alive

​Behavior by Environment

​Local Environment

​Browserbase Environment

​Fixed CDP Debugging Port

​DOM Settle Timeout

​What is DOM Settling?

​When to Adjust

​Troubleshooting

Browserbase Environment

Multi-Region Support

Disabling Stagehand API

Environment Variables

Using Stagehand with Browserbase

Basic Setup

Advanced Configuration

Alternative: Browserbase SDK

Connecting to an Existing Session

Local Environment

Environment Comparison

Basic Local Setup

Advanced Local Configuration

Default Local Launch Arguments

Advanced Configuration

Keep Alive

Behavior by Environment

Local Environment

Browserbase Environment

Fixed CDP Debugging Port

DOM Settle Timeout

What is DOM Settling?

When to Adjust

Troubleshooting