Create a Browser Session

​

Overview

A browser session represents a single browser instance running in the cloud. It’s the fundamental building block of Browserbase, providing an isolated environment for your web automation tasks.

​

Creating a Session

Browser sessions are created through the Sessions API, which gives you full control over configuration and features. After creation, you’ll receive a connection URL to use with your preferred automation framework.

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

​

Configuration Options

When creating a session, you can configure various settings. For complete API details, see:

• Create Session API Reference
• Node.js SDK Reference
• Python SDK Reference

​

Basic Settings

• Region - Decrease latency by choosing where your browser runs using one of our browser regions
• Viewport - Set custom screen dimensions for your browser window. Otherwise, the default viewport varies per session
• Keep Alive - Enable longer-running sessions that run even after disconnection
• Recording - Enable/disable session recording (enabled by default)
• Logging - Enable/disable session logging for debugging (enabled by default)

​

Advanced Features

• Stealth Mode - Configure anti-bot mitigations:

  • Basic fingerprinting (devices, locales, operating systems)
  • Advanced stealth mode (Scale plan only)
  • Proxy settings
  • Captcha solving (enabled by default)

• Extensions - Load custom browser extensions to enhance functionality

• Browser Context - Configure isolated browsing contexts for session persistence

• User Metadata - Attach custom data for session organization and filtering

​

Next Steps

Once you’ve created a session, you can:

1. Connect to it using your preferred automation framework - see Using a Browser Session
2. Monitor it through the Session Inspector
3. End it manually or let it timeout - see Manage a Browser Session