--- title: Browser sidebarTitle: Browser description: Configure Stagehand on Browserbase or locally --- import { V3Banner } from '/snippets/v3-banner.mdx'; 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. 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`: ```typescript 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: ```typescript 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: ```bash .env 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](https://browserbase.com/overview) ### Using Stagehand with Browserbase #### Basic Setup The simplest way to get started is with default settings: ```typescript 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: ```typescript 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); ``` ```typescript 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", }, }, }); ``` ### Alternative: Browserbase SDK If you prefer to manage sessions directly, you can use the Browserbase SDK: ```typescript 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: ```typescript 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 ```typescript 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: ```typescript 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 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 ### 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. ```typescript 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. ```typescript 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. ```typescript 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. ```typescript 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 ```typescript // 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