Skip to main content
Stagehand supports two browser environments: local browsers using your machine’s Chrome/Chromium installation, or Browserbase cloud browsers for scalable, headless browser automation.

​
Environment Configuration

Set the environment type using the env option: 
import { Stagehand } from '@browserbasehq/stagehand';

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

​
Local Browser Configuration

Run Stagehand with a local Chrome/Chromium browser on your machine.

​
Basic Local Setup

const stagehand = new Stagehand({
  env: "LOCAL",
  localBrowserLaunchOptions: {
    headless: false, // Set to true for headless mode
  },
});

await stagehand.init();

​
Local Browser Launch Options

The localBrowserLaunchOptions object supports the following configuration:
​
args
string[]
Additional command-line arguments to pass to Chrome
args: ['--window-size=1920,1080', '--disable-blink-features=AutomationControlled']
​
executablePath
string
Path to a Chrome/Chromium executable
executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
​
port
number
Port for the Chrome DevTools Protocol (CDP) server
port: 9222
​
userDataDir
string
Path to a user data directory for storing browser profiles, cookies, and cache
userDataDir: './chrome-user-data'
​
preserveUserDataDir
boolean
Keep the user data directory after browser closes
preserveUserDataDir: true
​
headless
boolean
Run browser in headless mode (no UI)
headless: true
​
devtools
boolean
Auto-open Chrome DevTools
devtools: true
​
chromiumSandbox
boolean
Enable Chromium sandbox (disable for Docker)
chromiumSandbox: false
​
ignoreDefaultArgs
boolean | string[]
Ignore default Chrome arguments or filter specific ones
ignoreDefaultArgs: ['--enable-automation']
​
proxy
object
Proxy server configuration
proxy: {
  server: 'http://proxy.example.com:8080',
  username: 'user',
  password: 'pass',
  bypass: 'localhost,127.0.0.1'
}
​
locale
string
Browser locale
locale: 'en-US'
​
viewport
object
Browser viewport size
viewport: { width: 1920, height: 1080 }
​
deviceScaleFactor
number
Device pixel ratio
deviceScaleFactor: 2
​
hasTouch
boolean
Enable touch events
hasTouch: true
​
ignoreHTTPSErrors
boolean
Ignore HTTPS certificate errors
ignoreHTTPSErrors: true
​
cdpUrl
string
Connect to an existing Chrome DevTools Protocol URL
cdpUrl: 'ws://localhost:9222/devtools/browser/...'
​
connectTimeoutMs
number
Timeout for connecting to the browser (default: 15000ms)
connectTimeoutMs: 30000
​
downloadsPath
string
Directory for downloads
downloadsPath: './downloads'
​
acceptDownloads
boolean
Allow file downloads
acceptDownloads: true

​
Complete Local Example

const stagehand = new Stagehand({
  env: "LOCAL",
  localBrowserLaunchOptions: {
    headless: false,
    viewport: { width: 1920, height: 1080 },
    userDataDir: './chrome-profile',
    preserveUserDataDir: true,
    args: [
      '--disable-blink-features=AutomationControlled',
      '--disable-dev-shm-usage',
    ],
    ignoreHTTPSErrors: true,
  },
});

await stagehand.init();

​
Browserbase Configuration

Use Browserbase for cloud-based, scalable browser automation with built-in anti-detection, session recording, and debugging.

​
Basic Browserbase Setup

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
});

await stagehand.init();
Get your Browserbase API credentials at browserbase.com

​
Browserbase Session Options

Customize Browserbase sessions with browserbaseSessionCreateParams:
​
keepAlive
boolean
Keep session alive after Stagehand closes (for debugging)
keepAlive: true
​
region
string
Browserbase region: us-west-2, us-east-1, eu-central-1, ap-southeast-1
region: 'us-west-2'
​
timeout
number
Session timeout in seconds
timeout: 300
​
browserSettings
object
Browser configuration options
browserSettings: {
  viewport: { width: 1920, height: 1080 },
  blockAds: true,
  solveCaptchas: true,
  advancedStealth: true,
  recordSession: true,
  logSession: true,
}
​
proxies
boolean | object[]
Proxy configuration
proxies: [
  {
    type: 'browserbase',
    geolocation: { country: 'US', state: 'CA' }
  }
]
​
context
object
Persist browser context across sessions
context: {
  id: 'my-context-id',
  persist: true
}

​
Advanced Browserbase Example

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  browserbaseSessionCreateParams: {
    region: 'us-west-2',
    keepAlive: true,
    browserSettings: {
      viewport: { width: 1920, height: 1080 },
      blockAds: true,
      solveCaptchas: true,
      advancedStealth: true,
      recordSession: true,
      fingerprint: {
        browsers: ['chrome'],
        devices: ['desktop'],
        locales: ['en-US'],
        operatingSystems: ['windows'],
      },
    },
    proxies: [
      {
        type: 'browserbase',
        geolocation: { country: 'US', state: 'CA', city: 'San Francisco' },
      },
    ],
  },
});

await stagehand.init();

​
Resume Existing Session

Resume a previously created Browserbase session: 
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  browserbaseSessionID: 'existing-session-id',
});

await stagehand.init();

​
Access Session Information

Get session URLs for debugging and viewing recordings: 
const sessionId = stagehand.browserbaseSessionID;
const sessionUrl = stagehand.browserbaseSessionURL;
const debugUrl = stagehand.browserbaseDebugURL;

console.log(`Session ID: ${sessionId}`);
console.log(`View session: ${sessionUrl}`);
console.log(`Debug session: ${debugUrl}`);

​
Choosing Between Local and Browserbase

Local Browser

Best for:
  • Local development and testing
  • Applications requiring local files
  • Custom browser configurations
  • Cost-sensitive workloads

Browserbase

Best for:
  • Production deployments
  • Scalable automation
  • Anti-detection requirements
  • Session recording and debugging
  • Multi-region support
Tip: Start development locally and switch to Browserbase for production by changing the env parameter.

Build docs developers (and LLMs) love

Get started for freeTalk to us