Skip to main content
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);

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!,
    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,
      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'
}
Open the Browserbase session live view to include a human-in-the-loop.
Open the session replay to see the full session recording.
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

FeatureBrowserbaseLocal
ScalabilityHigh (cloud-managed)Limited (local resources)
Stealth FeaturesAdvanced fingerprintingBasic stealth
Proxy SupportBuilt-in residential proxiesManual configuration
Session PersistenceCloud context storageFile-based user data
Geographic DistributionMulti-region deploymentSingle machine
DebuggingSession recordings & logsDirect DevTools access
Setup ComplexityEnvironment variables onlyBrowser installation required
CostUsage-based pricingInfrastructure & maintenance
Best ForProduction, scale, complianceDevelopment, 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',
    ],
    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();

​
Advanced Configuration

​
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

  • 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
  • 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)
  • Increase session timeout in browserbaseSessionCreateParams.timeout
  • Use keepAlive: true for long-running sessions
  • Monitor session usage to avoid unexpected terminations