How to Switch Between Local and Remote Browserbase Sessions: A Complete Guide

Use the browse env command to explicitly set your session mode—browse env local for isolated local Chrome, browse env local --auto-connect to reuse your existing browser profile, or browse env remote for cloud-based Browserbase infrastructure.

The browserbase/skills repository provides a powerful browse CLI that abstracts browser automation across local and remote environments. When you need to switch between local and remote Browserbase sessions, the tool offers both automatic detection based on environment variables and explicit CLI commands for precise control over where your browser sessions execute.

How the Session Daemon Handles Environment Selection

When you execute any browse command, the CLI starts a session daemon that maintains the active browser context. According to the implementation in skills/browser/SKILL.md, this daemon determines whether to launch in local or remote mode through a specific decision hierarchy.

The daemon first checks for the presence of a BROWSERBASE_API_KEY environment variable:

• If the API key exists → Defaults to a remote Browserbase session on cloud infrastructure
• If the API key is absent → Falls back to a local Chrome/Chromium instance

This automatic selection persists until you explicitly override it or terminate the session with browse stop.

Explicit Session Mode Commands

While automatic detection provides convenience, the browse env subcommand gives you granular control over session placement. The CLI provides three distinct commands for switching between local and remote Browserbase sessions:

• browse env local – Launches a clean, isolated Chrome instance with no cookies or persistent state
• browse env local --auto-connect – Connects to your already-running Chrome, preserving cookies, logins, and extensions
• browse env remote – Switches to Browserbase's cloud infrastructure (requires BROWSERBASE_API_KEY)

These overrides are scoped per session and remain active until you run browse stop or issue another browse env command. After stopping, the daemon resets and reverts to automatic selection based on environment variables.

Practical Code Examples

Clean Local Development

Use this mode when testing against localhost or sites without bot detection:

browse env local
browse open https://example.com
browse snapshot
browse stop

Reusing Existing Browser State

Use --auto-connect when you need to maintain login sessions or browser extensions:

browse env local --auto-connect
browse open https://my-dashboard.internal
browse click @0-3
browse stop

Remote Browserbase Sessions

Required for CAPTCHAs, anti-bot protections, or geo-restricted content:

export BROWSERBASE_API_KEY=your-api-key
browse env remote
browse open https://protected-site.com
browse snapshot
browse click @1-2
browse stop

Dynamic Mode Switching

Switch environments mid-workflow without stopping the daemon:

browse env local
browse open http://localhost:3000

# Perform local testing...

browse env remote
browse open https://geo-restricted.com

When to Use Each Mode

Local (clean) – Ideal for development, testing on localhost, and sites without sophisticated bot detection. Provides fast iteration with fresh browser state.

Local (auto-connect) – Best for workflows requiring authenticated sessions or specific browser configurations. Reuses your existing Chrome profile from ~/Library/Application Support/Google/Chrome or equivalent.

Remote – Essential for production sites with Cloudflare, DataDome, or similar protections. Browserbase handles CAPTCHA solving, IP rotation, and session persistence automatically.

Implementation Details

The environment selection logic is documented in skills/browser/SKILL.md, which defines the CLI behavior and session management API. The browse env commands map internally to the bb CLI's session-management endpoints, though the user-facing interface remains encapsulated in the browse wrapper.

Key implementation files include:

• skills/browser/SKILL.md – Defines the browse CLI and environment selection logic
• skills/browser/REFERENCE.md – Contains API reference for CLI options and parameters
• README.md – Provides overview of all skills and default browse env behaviors

Summary

• Automatic detection relies on the BROWSERBASE_API_KEY environment variable; present means remote, absent means local
• Explicit control comes via browse env local, browse env local --auto-connect, and browse env remote
• Session persistence means your mode selection stays active until you run browse stop or switch modes
• Auto-connect mode preserves your existing Chrome profile while clean mode starts isolated sessions
• Dynamic switching allows changing environments mid-workflow without restarting the daemon

Frequently Asked Questions

How does the CLI automatically choose between local and remote?

The daemon checks for the BROWSERBASE_API_KEY environment variable during initialization. If present, it defaults to remote Browserbase infrastructure; if absent, it launches a local Chrome instance. This logic is implemented in the session initialization code within skills/browser/SKILL.md.

What is the difference between browse env local and browse env local --auto-connect?

browse env local launches a fresh Chrome instance with isolated storage, cookies, and cache—perfect for testing from a clean slate. browse env local --auto-connect attaches to your existing Chrome process, preserving all logged-in sessions, extensions, and browsing history from your personal profile.

Do I need to stop the daemon to switch from local to remote?

No. You can switch between local and remote Browserbase sessions dynamically using browse env remote or browse env local without stopping the daemon. The new mode applies immediately to subsequent commands. However, running browse stop clears the override and resets automatic selection for the next session.

Where is the session mode configuration stored?

The session mode is maintained in-memory by the active daemon process rather than written to disk configuration files. This means each new daemon instance (started after browse stop) re-evaluates the BROWSERBASE_API_KEY environment variable to determine the default mode.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}