Skip to main content

​
Browserbase

Stagehand is built and maintained by Browserbase. As a result, Stagehand has supreme performance and reliability on Browserbase. The Browserbase SDK is very powerful, and allows you to handle a wide variety of use cases such as:
  • Captcha solving
  • Custom contexts and extensions
  • Live browser view
  • Proxy rotation
  • Session recordings
  • Uploads/downloads
Using Browserbase is as easy as setting env: "BROWSERBASE" in your Stagehand constructor: 
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  // Stagehand will automatically read your Browserbase API key and project ID from your environment variables
  // If you'd like to pass in your own API key and project ID, you can do so like this:
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
});

​
Create a Browserbase session

To create a custom Browserbase session, you can pass in browserbaseSessionCreateParams to the Stagehand constructor. For full documentation on the browserbaseSessionCreateParams object, see the Browserbase API documentation. 
const stagehand = new Stagehand({
	env: "BROWSERBASE",
 	browserbaseSessionCreateParams: {
		projectId: "your-project-id",
		extensionId: 'your-extension-id',
		browserSettings: {
			viewport: {
				width: 1920,
				height: 1080,
			},
			proxies: [
				{
					type: 'external',
					server: 'your-proxy-server',
					username: 'your-proxy-username',
					password: 'your-proxy-password',
				},
			],
			context: {
				id: 'your-context-id',
			},
		},
	},
});

​
Resume an existing Browserbase session

You can reconnect to an existing Browserbase session by passing in the browserbaseSessionId to the Stagehand constructor. 
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  browserbaseSessionId: "your-session-id",
});
You can also pass in browserbaseSessionCreateParams, but it will be ignored if browserbaseSessionId is provided. 
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  browserbaseSessionId: "your-session-id",
  
  // This will be ignored because we're providing a browserbaseSessionId
  browserbaseSessionCreateParams: {
	projectId: "your-project-id",
  },
});

​
Local Browser Customization

Stagehand allows you to customize your local browser in a few different ways. You can use localBrowserLaunchOptions type to customize the browser you want Stagehand to use. 
const stagehand = new Stagehand({
  localBrowserLaunchOptions: {
	cdpUrl: 'your-cdp-url',
  }
})

​
Use your personal browser

The cdpUrl config is only supported in Stagehand 2.0+.
You can use Stagehand with any Chromium-based browser, like Arc, Brave, Chrome, Dia, and Edge! To do so, you can pass in a cdpUrl to connect to a remote browser, or pass in an executablePath to use a local browser executable. You’ll also need to open your browser in “debug” mode. For example, if you’re using Chrome on a Mac, you can open it with the following command: 
open -a "Google Chrome" --args --remote-debugging-port=9222
This will open Chrome with remote debugging enabled on port 9222. You can then pass in the cdpUrl to Stagehand like so: 
const stagehand = new Stagehand({
  localBrowserLaunchOptions: {
	cdpUrl: 'http://localhost:9222',
  },
});