Browser

You get a browser from one of Stagehand’s browser factories and hand it to Stagehand.create(). There are three ways to get one:

Browserbase (browserbase.launch): Cloud-managed browser infrastructure optimized for production web automation at scale
Local (localBrowser.launch): Run browsers directly on your machine for development and debugging
Attach over CDP (localBrowser.connect): Attach to any Chromium browser you are already running, by URL

Stagehand closes only the browsers it launched, so browser.close() is yours to call.

TypeScript
Python
Go

const cloud = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY });
const local = await localBrowser.launch({ headless: true });
const connected = await localBrowser.connect({ cdpUrl: "http://127.0.0.1:9222" });

await Stagehand.create({ browser: cloud });

cloud = await browserbase.launch(api_key=os.environ["BROWSERBASE_API_KEY"])
local = await local_browser.launch(headless=True)
connected = await local_browser.connect(cdp_url="http://127.0.0.1:9222")

await Stagehand.create(browser=cloud)

apiKey := os.Getenv("BROWSERBASE_API_KEY")

cloud, _ := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{APIKey: apiKey})
stagehand.Create(ctx, stagehand.CreateOptions{Browser: cloud})

// Or start a browser on your machine, or attach to one you already run:
stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{Headless: true})
stagehand.ConnectLocalBrowser(ctx, stagehand.LocalBrowserConnectOptions{
	CDPURL: "http://127.0.0.1:9222",
})

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. It is also the only browser that supports server-side caching and the Model Gateway.

Browserbase

Read the Browserbase documentation for the full set of session settings Stagehand passes through.

Multi-region support

Browserbase runs browsers in four regions, so you can cut latency by starting the browser near your users or your target site, and keep session data in a required jurisdiction. Set the region on browserbase.launch(); us-west-2 is the default.

TypeScript
Python
Go

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

const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  region: "eu-central-1", // Browser runs in Frankfurt
});
const stagehand = await Stagehand.create({ browser });

import os

from stagehand import Stagehand, browserbase

browser = await browserbase.launch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    region="eu-central-1",  # Browser runs in Frankfurt
)
stagehand = await Stagehand.create(browser=browser)

apiKey := os.Getenv("BROWSERBASE_API_KEY")
region := stagehand.BrowserbaseRegionEUCentral1 // Browser runs in Frankfurt

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{
	APIKey: apiKey,
	Region: &region,
})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

Supported regions: us-west-2 (default), us-east-1, eu-central-1, ap-southeast-1.

You normally do not need to configure a regional endpoint. Stagehand picks the API deployment that matches your session’s region on its own, including for server-side caching. An explicit Stagehand apiUrl overrides that regional selection.

API endpoint overrides

Browserbase session management and Stagehand managed services use separate APIs. Both default to the production service. The SDKs do not read either URL from an environment variable. Pass baseUrl to Browserbase and apiUrl to Stagehand when testing another deployment. Use the service origin without /v1.

TypeScript
Python
Go

const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  baseUrl: "https://api.dev.browserbase.com",
});

const stagehand = await Stagehand.create({
  browser,
  apiUrl: "https://api.stagehand.dev.browserbase.com",
});

browser = await browserbase.launch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    base_url="https://api.dev.browserbase.com",
)

stagehand = await Stagehand.create(
    browser=browser,
    api_url="https://api.stagehand.dev.browserbase.com",
)

apiKey := os.Getenv("BROWSERBASE_API_KEY")
stagehandAPIURL := "https://api.stagehand.dev.browserbase.com"

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{
	APIKey:  apiKey,
	BaseURL: "https://api.dev.browserbase.com",
})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	APIURL:  &stagehandAPIURL,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

The Browserbase URL controls extension, session, and connection requests that browserbase.launch() and browserbase.connect() make. The Stagehand URL controls Model Gateway and managed-cache requests that the browser runtime makes.

Environment variables

Before getting started, set up the required environment variables:

export BROWSERBASE_API_KEY=your_api_key_here

Get your API key from the Browserbase Dashboard. Stagehand does not read this variable for you: read it in your own code and pass it to browserbase.launch().

Using Stagehand with Browserbase

Basic setup

The simplest way to get started is with default settings. browserbase.launch() needs nothing but your Browserbase API key:

TypeScript
Python
Go

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

const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY,
});
const stagehand = await Stagehand.create({ browser });

import os

from stagehand import Stagehand, browserbase

browser = await browserbase.launch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
)
stagehand = await Stagehand.create(browser=browser)

apiKey := os.Getenv("BROWSERBASE_API_KEY")

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{APIKey: apiKey})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

Advanced configuration

Configure browser settings, proxy support, and other session parameters directly on browserbase.launch():

TypeScript
Python
Go

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

const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  proxies: true,
  region: "us-west-2",
  browserSettings: {
    viewport: { width: 1920, height: 1080 },
    blockAds: true,
  },
});
const stagehand = await Stagehand.create({ browser });

import os

from stagehand import BrowserbaseBrowserSettings, Stagehand, browserbase

browser = await browserbase.launch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    proxies=True,
    region="us-west-2",
    browser_settings=BrowserbaseBrowserSettings.model_validate({
        "viewport": {"width": 1920, "height": 1080},
        "block_ads": True,
    }),
)
stagehand = await Stagehand.create(browser=browser)

apiKey := os.Getenv("BROWSERBASE_API_KEY")
region := stagehand.BrowserbaseRegionUSWest2
proxies := stagehand.BrowserbaseProxyEnabled(true)
blockAds := true
width, height := 1920.0, 1080.0

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{
	APIKey:   apiKey,
	Proxies:  &proxies,
	Region:   &region,
	BrowserSettings: &stagehand.BrowserbaseBrowserSettings{
		Viewport: &stagehand.BrowserbaseViewport{Width: &width, Height: &height},
		BlockAds: &blockAds,
	},
})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

Advanced Browserbase configuration example

TypeScript
Python
Go

const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  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",
  },
});

browser = await browserbase.launch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    proxies=True,
    region="us-west-2",
    timeout=3600,  # 1 hour session timeout
    keep_alive=True,  # Available on Startup plan
    browser_settings=BrowserbaseBrowserSettings.model_validate({
        # verified is a Scale Plan feature: contact support@browserbase.com to enable
        "verified": False,
        "block_ads": True,
        "solve_captchas": True,
        "record_session": False,
        "viewport": {"width": 1920, "height": 1080},
    }),
    user_metadata={
        "user_id": "automation-user-123",
        "environment": "production",
    },
)

stagehand = await Stagehand.create(browser=browser)

apiKey := os.Getenv("BROWSERBASE_API_KEY")
region := stagehand.BrowserbaseRegionUSWest2
proxies := stagehand.BrowserbaseProxyEnabled(true)
timeout := 3600.0 // 1 hour session timeout
keepAlive := true // Available on Startup plan

// verified is a Scale Plan feature: contact support@browserbase.com to enable
verified := false
blockAds := true
solveCaptchas := true
recordSession := false
width, height := 1920.0, 1080.0

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{
	APIKey:    apiKey,
	Proxies:   &proxies,
	Region:    &region,
	Timeout:   &timeout,
	KeepAlive: &keepAlive,
	BrowserSettings: &stagehand.BrowserbaseBrowserSettings{
		Verified:      &verified,
		BlockAds:      &blockAds,
		SolveCaptchas: &solveCaptchas,
		RecordSession: &recordSession,
		Viewport:      &stagehand.BrowserbaseViewport{Width: &width, Height: &height},
	},
	UserMetadata: map[string]json.RawMessage{
		"userId":      json.RawMessage(`"automation-user-123"`),
		"environment": json.RawMessage(`"production"`),
	},
})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

When browserbase.launch() creates a session without an extensionId, Stagehand uploads its extension and starts the session against it. Stagehand deletes the upload when you call browser.close() for a launched session without keepAlive enabled.

Alternative: Browserbase SDK

If you prefer to manage sessions directly, create the session with the Browserbase SDK and hand Stagehand the resulting session through browserbase.connect():

TypeScript
Python
Go

import { Browserbase } from "@browserbasehq/sdk";
import { browserbase, Stagehand } from "@browserbasehq/stagehand";

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
});

// Attach by session ID so the browser keeps its Browserbase identity
const browser = await browserbase.connect({
  apiKey: process.env.BROWSERBASE_API_KEY!,
  sessionId: session.id,
});
const stagehand = await Stagehand.create({ browser });

import os

from browserbase import Browserbase

from stagehand import Stagehand
from stagehand import browserbase as stagehand_browserbase

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    # Add configuration options here
)

# Attach by session ID so the browser keeps its Browserbase identity
browser = await stagehand_browserbase.connect(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    session_id=session.id,
)
stagehand = await Stagehand.create(browser=browser)

// Create the session with your Browserbase client of choice, then attach by
// session ID so the browser keeps its Browserbase identity.
session, err := createBrowserbaseSession(ctx)
if err != nil {
	return err
}

browser, err := stagehand.ConnectBrowserbase(ctx, stagehand.BrowserbaseConnectOptions{
	APIKey:    os.Getenv("BROWSERBASE_API_KEY"),
	SessionID: session.ID,
})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

Connecting to an existing session

localBrowser.connect() attaches to any Chromium browser that is already running and exposing a DevTools endpoint, whether that is a Browserbase session you created earlier or a browser on your own machine:

TypeScript
Python
Go

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

const browser = await localBrowser.connect({
  cdpUrl: "wss://connect.browserbase.com/?apiKey=...&sessionId=...",
});
const stagehand = await Stagehand.create({ browser });

from stagehand import Stagehand, local_browser

browser = await local_browser.connect(
    cdp_url=connect_url,  # from your Browserbase session
)
stagehand = await Stagehand.create(browser=browser)

browser, err := stagehand.ConnectLocalBrowser(ctx, stagehand.LocalBrowserConnectOptions{
	CDPURL: "wss://connect.browserbase.com/?apiKey=...&sessionId=...",
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, browser.Close(ctx)) }()

client, err := stagehand.Create(ctx, stagehand.CreateOptions{Browser: browser})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

Stagehand never closes a browser it did not launch. When you connect to an existing browser, close() tears down the Stagehand connection and leaves the browser running.

Local environment

Run browsers directly on your machine when you want full control over the browser process and its launch flags. This suits development, debugging, and 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 and logs	Direct DevTools access
Setup complexity	API key only	Browser installation required
Server-side caching	Supported	Not available
Model Gateway	Supported	Not available
Cost	Usage-based pricing	Infrastructure and maintenance
Best for	Production, scale, compliance	Development, debugging

Basic local setup

TypeScript
Python
Go

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

const browser = await localBrowser.launch();
const stagehand = await Stagehand.create({ browser });

from stagehand import Stagehand, local_browser

browser = await local_browser.launch()
stagehand = await Stagehand.create(browser=browser)

browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

Advanced local configuration

Customize browser launch options for local development:

TypeScript
Python
Go

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

const browser = await localBrowser.launch({
  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: [
      "--disable-sync",
    ], // Remove specific default launch args
    args: [
      "--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
    hasTouch: false, // Emulate touch input
    proxy: {
      server: "http://proxy.example.com:8080",
      username: "user",
      password: "pass",
    },
    downloadsPath: "./downloads", // Download directory
    acceptDownloads: true, // Allow downloads
});
const stagehand = await Stagehand.create({ browser });

from stagehand import Stagehand, local_browser

browser = await local_browser.launch(
    headless=False,  # Show browser window
    devtools=True,  # Open developer tools
    viewport_width=1280,
    viewport_height=720,
    executable_path="/opt/google/chrome/chrome",  # Custom Chrome path
    port=9222,  # Fixed CDP debugging port
    ignore_default_args=["--disable-sync"],  # Remove specific default launch args
    args=[
        "--disable-web-security",
        "--allow-running-insecure-content",
    ],
    user_data_dir="./chrome-user-data",  # Persist browser data
    preserve_user_data_dir=True,  # Keep data after closing
    chromium_sandbox=False,  # Disable sandbox (adds --no-sandbox)
    ignore_https_errors=True,  # Ignore certificate errors
    locale="en-US",  # Set browser language
    device_scale_factor=1.0,  # Display scaling
    has_touch=False,  # Emulate touch input
    proxy_server="http://proxy.example.com:8080",
    proxy_username="user",
    proxy_password="pass",
    downloads_path="./downloads",  # Download directory
    accept_downloads=True,  # Allow downloads
)
stagehand = await Stagehand.create(browser=browser)

chromiumSandbox := false // Disable sandbox (adds --no-sandbox)
acceptDownloads := true  // Allow downloads
deviceScaleFactor := 1.0 // Display scaling

browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{
		Headless:       false,                            // Show browser window
		Devtools:       true,                             // Open developer tools
		Viewport:       &stagehand.LocalViewport{Width: 1280, Height: 720},
		ExecutablePath: "/opt/google/chrome/chrome",      // Custom Chrome path
		Port:           9222,                             // Fixed CDP debugging port
		IgnoreDefaultArgs: &stagehand.IgnoreDefaultArgs{ // Remove specific default launch args
			Args: []string{"--disable-sync"},
		},
		Args: []string{
			"--disable-web-security",
			"--allow-running-insecure-content",
		},
		UserDataDir:         "./chrome-user-data", // Persist browser data
		PreserveUserDataDir: true,                 // Keep data after closing
		ChromiumSandbox:     &chromiumSandbox,
		IgnoreHTTPSErrors:   true,     // Ignore certificate errors
		Locale:              "en-US",  // Set browser language
		DeviceScaleFactor:   &deviceScaleFactor,
		HasTouch:            false,    // Emulate touch input
		Proxy: &stagehand.LocalProxyConfig{
			Server:   "http://proxy.example.com:8080",
			Username: "user",
			Password: "pass",
		},
		DownloadsPath:    "./downloads", // Download directory
		AcceptDownloads:  &acceptDownloads,
})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

Authenticated local proxies are not supported yet. Setting a proxy username or password raises in all three SDKs; a proxy server and bypass list work everywhere.

Default local launch arguments

When Stagehand launches a local browser, it adds the following Chrome arguments before any values you pass in the launch args:

TypeScript
Python
Go

[
  "--enable-unsafe-extension-debugging",
  "--remote-allow-origins=*",
  "--window-size=1280,800",
  "--enable-features=WebMCPTesting,DevToolsWebMCPSupport",
]

[
    "--enable-unsafe-extension-debugging",
    "--remote-allow-origins=*",
    "--window-size=1280,800",
    "--enable-features=WebMCPTesting,DevToolsWebMCPSupport",
]

[]string{
	"--enable-unsafe-extension-debugging",
	"--remote-allow-origins=*",
	"--window-size=1280,800",
	"--enable-features=WebMCPTesting,DevToolsWebMCPSupport",
}

--enable-unsafe-extension-debugging is required so the SDK can attach a CDP session to the service worker hosting Stagehand’s runtime. Chrome blocks debugger access to extension targets without it. --enable-features=WebMCPTesting,DevToolsWebMCPSupport turns on the browser support behind WebMCP. --window-size follows the viewport option and falls back to 1280,800 when you do not set one.

A larger set of standard Chrome automation flags (disabling background networking, component updates, sync, translation, and similar) is prepended as well. To remove some of them, list the exact flags in the ignore-default-args option:

TypeScript
Python
Go

const browser = await localBrowser.launch({
  ignoreDefaultArgs: ["--disable-sync"],
  args: [
    "--disable-features=site-per-process,IsolateOrigins",
    "--renderer-process-limit=6",
  ],
});

browser = await local_browser.launch(
    ignore_default_args=["--disable-sync"],
    args=[
        "--disable-features=site-per-process,IsolateOrigins",
        "--renderer-process-limit=6",
    ],
)

stagehand = await Stagehand.create(browser=browser)

browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{
	IgnoreDefaultArgs: &stagehand.IgnoreDefaultArgs{
		Args: []string{"--disable-sync"},
	},
	Args: []string{
		"--disable-features=site-per-process,IsolateOrigins",
		"--renderer-process-limit=6",
	},
})
if err != nil {
	return err
}

stagehand.Create(ctx, stagehand.CreateOptions{Browser: browser})

Set the ignore-default-args option to true to remove all default arguments. Use a list to remove only exact matches while preserving the rest.

Advanced configuration

Keep alive

The keep-alive option controls whether the browser remains running after close() is called. By default, Stagehand terminates the browser it launched and cleans up all resources when it shuts down. Turning keep-alive on keeps the browser running independently so you can reconnect to it later.

TypeScript
Python
Go

import { browserbase, localBrowser, Stagehand } from "@browserbasehq/stagehand";

const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  keepAlive: true,
});
const stagehand = await Stagehand.create({ browser });

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

// Later, reconnect to the same session over CDP
const browser2 = await localBrowser.connect({ cdpUrl: existingConnectUrl });
const stagehand2 = await Stagehand.create({ browser: browser2 });

import os

from stagehand import Stagehand, browserbase, local_browser

browser = await browserbase.launch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    keep_alive=True,
)
stagehand = await Stagehand.create(browser=browser)

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

# Later, reconnect to the same session over CDP
browser2 = await local_browser.connect(cdp_url=existing_connect_url)
stagehand2 = await Stagehand.create(browser=browser2)

apiKey := os.Getenv("BROWSERBASE_API_KEY")
keepAlive := true

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{
	APIKey:    apiKey,
	KeepAlive: &keepAlive,
})
if err != nil {
	return err
}
client, err := stagehand.Create(ctx, stagehand.CreateOptions{Browser: browser})
if err != nil {
	return err
}

// The browser session continues running after Close()
if err := client.Close(ctx); err != nil {
	return err
}
if err := browser.Close(ctx); err != nil {
	return err
}

// Later, reconnect to the same session over CDP
browser2, err := stagehand.ConnectLocalBrowser(ctx, stagehand.LocalBrowserConnectOptions{
	CDPURL: existingConnectURL,
})
if err != nil {
	return err
}

client2, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser2,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client2.Close(ctx)) }()

Behavior by environment

Behavior	keep-alive on	keep-alive off (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
Attached over CDP	Always left running	Always left running (Stagehand never owns the browser)

Local environment

When running locally with keep-alive on, Stagehand leaves the Chrome process running when your script exits. This is useful for debugging or for handing off a browser session to another process. Combine it with a fixed port so you can reattach with localBrowser.connect().

TypeScript
Python
Go

const browser = await localBrowser.launch({
  keepAlive: true,
  headless: false,
  port: 9222,
});
const stagehand = await Stagehand.create({ browser });
const [page] = await browser.context.pages();
await page.goto("https://example.com");

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

browser = await local_browser.launch(
    keep_alive=True,
    headless=False,
    port=9222,
)
stagehand = await Stagehand.create(browser=browser)
page = (await browser.context.pages())[0]
await page.goto("https://example.com")

# Browser window stays open after the script exits
await stagehand.close()
await browser.close()

browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{
	KeepAlive: true,
	Headless:  false,
	Port:      9222,
})
if err != nil {
	return err
}
client, err := stagehand.Create(ctx, stagehand.CreateOptions{Browser: browser})
if err != nil {
	return err
}

browserContext, err := browser.Context()
if err != nil {
	return err
}
pages, err := browserContext.Pages(ctx)
if err != nil {
	return err
}
if len(pages) == 0 {
	return errors.New("Stagehand initialized without an active page")
}
page := pages[0]
if _, err := page.Goto(ctx, "https://example.com", nil); err != nil {
	return err
}

// Browser window stays open after the program exits
return errors.Join(client.Close(ctx), browser.Close(ctx))

A temporary user data directory is deleted when a local browser shuts down. Set userDataDir (or turn on the preserve option) if you want the profile to survive.

Browserbase environment

On Browserbase, keep-alive keeps the cloud session active so you can reconnect later with browserbase.connect(). This is useful for long-running workflows that span multiple script executions.

Keeping sessions alive is available on the Browserbase Startup plan and above.

Fixed CDP debugging port

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

TypeScript
Python
Go

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

const browser = await localBrowser.launch({ port: 9222 });
const stagehand = await Stagehand.create({ browser });

from stagehand import Stagehand, local_browser

browser = await local_browser.launch(port=9222)
stagehand = await Stagehand.create(browser=browser)

browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{Port: 9222})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

Stagehand picks a random free port when you do not set one.

DOM settle timeout

Configure how long Stagehand waits for the DOM to stabilize before taking actions. The default is 5000 ms.

TypeScript
Python
Go

const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY });
const stagehand = await Stagehand.create({
  browser,
  domSettleTimeoutMs: 3000, // Wait up to 3 seconds for DOM to settle
});

browser = await browserbase.launch(api_key=os.environ["BROWSERBASE_API_KEY"])
stagehand = await Stagehand.create(
    browser=browser,
    dom_settle_timeout_ms=3000,  # Wait up to 3 seconds for DOM to settle
)

apiKey := os.Getenv("BROWSERBASE_API_KEY")
domSettleTimeoutMs := 3000 // Wait up to 3 seconds for DOM to settle

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{APIKey: apiKey})
if err != nil {
	return err
}
client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser:            browser,
	DOMSettleTimeoutMs: &domSettleTimeoutMs,
})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

DOM settling applies to act() calls that take a natural-language instruction. Replaying an observed Action skips the wait, and observe() and extract() read a snapshot of the page as they find it.

What is DOM settling?

Before an instruction-based act() call runs, Stagehand waits for the page’s network activity to go quiet, up to the timeout. That gives lazy-loaded content, JavaScript updates, and other dynamic rendering time to finish before the action targets an element.

When to adjust

Increase the DOM settle timeout for pages with:

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

TypeScript
Python
Go

// For fast, static pages
const fastBrowser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY });
const fast = await Stagehand.create({
  browser: fastBrowser,
  domSettleTimeoutMs: 500, // Minimal wait
});

// For dynamic, animated pages
const dynamicBrowser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY });
const dynamic = await Stagehand.create({
  browser: dynamicBrowser,
  domSettleTimeoutMs: 5000, // Longer wait for stability
});

# For fast, static pages
fast_browser = await browserbase.launch(api_key=os.environ["BROWSERBASE_API_KEY"])
fast = await Stagehand.create(
    browser=fast_browser,
    dom_settle_timeout_ms=500,  # Minimal wait
)

# For dynamic, animated pages
dynamic_browser = await browserbase.launch(api_key=os.environ["BROWSERBASE_API_KEY"])
dynamic = await Stagehand.create(
    browser=dynamic_browser,
    dom_settle_timeout_ms=5000,  # Longer wait for stability
)

apiKey := os.Getenv("BROWSERBASE_API_KEY")

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{APIKey: apiKey})
if err != nil {
	return err
}
settleTimeout := 500 // Fast, static pages
if os.Getenv("PAGE_PROFILE") == "dynamic" {
	settleTimeout = 5000 // Dynamic, animated pages
}
client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser:            browser,
	DOMSettleTimeoutMs: &settleTimeout,
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

Setting the DOM settle timeout 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 read and passed to browserbase.launch()
Check that your API key has the necessary permissions
Ensure your Browserbase account has sufficient credits
Remember that browserbase.launch() requires an API key: it fails without one

Local browser launch failures

Install Chrome or Chromium on your system
Set the correct executable path for your Chrome installation, or set CHROME_PATH
Check that required dependencies are installed (Linux: libnss3-dev libatk-bridge2.0-dev libgtk-3-dev libxss1 libasound2)
If the extension fails to load, confirm nothing is stripping --enable-unsafe-extension-debugging from the launch arguments

Session timeout issues

Increase the session timeout on browserbase.launch()
Turn on keep-alive for long-running sessions
Monitor session usage to avoid unexpected terminations

First steps

The basics

Configuration

Best practices

Migration guide

SDK reference

Browserbase environment

Browserbase

Multi-region support

API endpoint overrides

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

​API endpoint overrides

​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

API endpoint overrides

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