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.

Environment Variables

Before getting started, set up the required environment variables:

BROWSERBASE_API_KEY=your_api_key_here
BROWSERBASE_PROJECT_ID=your_project_id_here

Get your API key and Project ID 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 and Project ID will be pulled directly from your environment
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  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,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  browserbaseSessionCreateParams: {
    projectId: process.env.BROWSERBASE_PROJECT_ID!, // Optional: automatically set if given in environment variable or by Stagehand parameter
    proxies: true,
    region: "us-west-2",
    timeout: 3600, // 1 hour session timeout
    keepAlive: true, // Available on Startup plan
    browserSettings: {
      advancedStealth: false, // this is a Scale Plan feature - reach out to support@browserbase.com to enable
      blockAds: true,
      solveCaptchas: true,
      recordSession: false,
      os: "windows", // Valid: "windows" | "mac" | "linux" | "mobile" | "tablet"
      viewport: {
        width: 1920,
        height: 1080,
      },
    },
    userMetadata: {
      userId: "automation-user-123",
      environment: "production",
    },
  },
});

Initialization Result

After calling stagehand.init(), the method returns configuration information about the initialized session:

const result = await stagehand.init();
console.log(result);

The returned object contains:

{
  debugUrl: 'https://www.browserbase.com/devtools/inspector.html?wss=connect.browserbase.com/debug/f8a21b4a-6fa1-4ab9-9007-fbfe61dc14f0/devtools/page/5474B0E0510C5B6E629BEB06E799CD70?debug=true',
  sessionUrl: 'https://www.browserbase.com/sessions/f8a21b4a-6fa1-4ab9-9007-fbfe61dc14f0',
  sessionId: 'f8a21b4a-6fa1-4ab9-9007-fbfe61dc14f0'
}

debugUrl

Open the Browserbase session live view to include a human-in-the-loop.

sessionUrl

Open the session replay to see the full session recording.

sessionId

Unique identifier for the Browserbase session. This is used to identify the session in the Browserbase dashboard and to connect to the session.

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({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  // 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
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-web-security',
      '--allow-running-insecure-content',
    ],
    env: {
      NODE_ENV: "development",
      DEBUG: "true",
    },
  },
});

await stagehand.init();

Connecting to your local browser

Connect to your existing local Chrome/Chromium browser instead of launching a new one. This lets you automate your normal browser with all your existing tabs, extensions and settings.

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

const stagehand = new Stagehand({
	env: "LOCAL",
	localBrowserLaunchOptions: {
		cdpUrl: 'http://localhost:9222'
	}
});

await stagehand.init();

Troubleshooting

Common Issues

Browserbase Authentication Errors

Verify your BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are 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

Browserbase Environment

Browserbase

Environment Variables

Using Stagehand with Browserbase

Basic Setup

Advanced Configuration

Initialization Result

Alternative: Browserbase SDK

Connecting to an Existing Session

Local Environment

Environment Comparison

Basic Local Setup

Advanced Local Configuration

Connecting to your local browser

Troubleshooting

Common Issues

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

​Browserbase Environment

Browserbase

​Environment Variables

​Using Stagehand with Browserbase

​Basic Setup

​Advanced Configuration

​Initialization Result

​Alternative: Browserbase SDK

​Connecting to an Existing Session

​Local Environment

​Environment Comparison

​Basic Local Setup

​Advanced Local Configuration

​Connecting to your local browser

​Troubleshooting

​Common Issues

Browserbase Environment

Environment Variables

Using Stagehand with Browserbase

Basic Setup

Advanced Configuration

Initialization Result

Alternative: Browserbase SDK

Connecting to an Existing Session

Local Environment

Environment Comparison

Basic Local Setup

Advanced Local Configuration

Connecting to your local browser

Troubleshooting

Common Issues