Browserbase

Browserbase is a cloud browser service that runs browser sessions on remote infrastructure. Superagent integrates with Browserbase as an alternative browser host, giving your agents access to anti-detection features, residential proxies, and persistent browser contexts without running Chrome locally.

When to Use Browserbase

Choose Browserbase when:

• You need stealth browsing. Browserbase offers an advanced stealth mode with a custom Chromium build designed to avoid bot detection on sites that block standard headless browsers.
• You need residential proxies. Route traffic through residential IP addresses to reduce CAPTCHA challenges and avoid IP-based rate limiting. Proxies can be geo-targeted to specific countries, states, or cities.
• You want persistent sessions across agents. Browserbase contexts persist cookies and storage across sessions, so an agent can resume where it left off.
• You are running Superagent on a server. On headless servers where Chrome is not installed, Browserbase provides browser access without local dependencies.

For straightforward browsing tasks on sites without aggressive bot detection, the built-in browser is simpler and has no additional cost. For tasks that need access to your local Chrome profiles and cookies, use Chrome integration instead.

Setup

Browserbase is available through two paths: bringing your own Browserbase account, or using the Platform-managed option.

Bring Your Own Account

1. Sign up at browserbase.com and create a project.
2. Open Settings > Browser in Superagent.
3. Set Browser Host to Browserbase.
4. Enter your API Key and Project ID in the fields that appear.
5. Click Connect. Superagent validates the credentials against the Browserbase API before saving them.

Once validated, a green "Credentials saved" badge appears. You can update or remove saved credentials at any time.

Credentials can also be provided via environment variables instead of the settings UI. Superagent checks for:

• BROWSERBASE_API_KEY
• BROWSERBASE_PROJECT_ID

Environment variables take effect without needing to enter credentials in the UI. The settings page shows "Using environment variable" when this is the case.

Platform-Managed

If you are signed in to a Superagent Platform account, the Platform browser host option is available. This uses Browserbase through the Platform's managed proxy, so you do not need to configure API keys separately. Your Platform subscription covers the browser session costs.

The Platform option supports the same session settings (stealth mode, proxies) as the bring-your-own-account option.

Session Settings

Both Browserbase and Platform-managed browser hosts support the following session settings, configurable in Settings > Browser.

Advanced Stealth Mode

When enabled, Browserbase uses a custom Chromium browser with modifications to avoid common bot detection techniques. This makes the browser appear more like a regular user's browser to anti-bot services.

You can optionally select an Operating System to emulate. This changes the user-agent string and browser environment signals to match the selected platform:

Advanced stealth mode requires a Browserbase Scale plan.

Proxy Configuration

When proxies are enabled, browser traffic is routed through Browserbase's residential proxy network. This helps with:

• Avoiding IP-based rate limiting and blocks.
• Higher CAPTCHA success rates.
• Accessing geo-restricted content.

You can optionally specify a proxy location:

Leave all location fields empty to use Browserbase's default (best-effort US proxy).

Persistent Contexts

Browserbase sessions use persistent contexts that are tied to each agent. A context preserves cookies, local storage, and session storage across browser sessions. This means:

• If an agent logs into a website in one session, it remains logged in the next time it opens the browser.
• Each agent gets its own context, so agents do not share session data with each other.
• Contexts are stored in Browserbase's infrastructure and persist until you delete them.

The context mapping is saved locally so Superagent can reuse the same Browserbase context for each agent across multiple sessions.

How It Works

When an agent opens the browser with Browserbase selected:

1. Superagent creates (or reuses) a Browserbase context for the agent.
2. A new Browserbase session is created with keepAlive enabled, so the session survives temporary disconnections.
3. Superagent connects to the session via its debug WebSocket URL, which supports multiple simultaneous connections (unlike the single-use connect URL).
4. The browser panel in the Superagent UI streams frames from the remote browser, just as it does for local browsers.

If an existing session is still running when the agent opens the browser again, Superagent reuses it instead of creating a new one.

Tradeoffs vs. the Built-in Browser

Troubleshooting

• "API key not configured" -- Make sure you have entered both the API key and project ID in Settings, or set the corresponding environment variables.
• "Failed to create Browserbase session" -- Check that your API key is valid, your Browserbase project exists, and your account has available session capacity.
• Stealth mode not working -- Advanced stealth mode requires a Browserbase Scale plan. Check your Browserbase account tier.
• Proxy location not taking effect -- Verify that the country code is a valid two-letter ISO code and that Browserbase has proxy coverage in the requested location.