How to Use Local Isolated Browser vs Auto-Connect Chrome Mode in the Browserbase CLI

Use browse env local to launch a fresh, isolated Chrome instance with a clean profile, or use browse env local --auto-connect to attach to an existing debuggable Chrome session and automatically fall back to an isolated browser if none is found.

The browserbase/skills repository provides a browse CLI that supports two distinct ways to run browsers locally. Understanding when to use a local isolated browser versus auto-connect Chrome mode helps you choose between reproducible, stateless automation and convenient reuse of existing login sessions.

Understanding the Two Local Modes

The CLI differentiates between environments through the browse env command. When targeting local execution, you have two primary options that control how the browser process starts and manages state.

Local Isolated Mode (browse env local)

Running browse env local instructs the CLI daemon to launch a brand-new Chrome or Chromium process with a temporary profile. According to the documentation in skills/browser/SKILL.md (lines 31-41), this mode guarantees a clean slate with no cookies, local storage, or cached credentials from previous runs.

This mode is ideal for automated testing and CI/CD pipelines where determinism matters. Each invocation starts fresh, eliminating hidden state that could cause flaky behavior across runs.

Auto-Connect Mode (browse env local --auto-connect)

Adding the --auto-connect flag changes the startup behavior significantly. As noted in skills/browser/SKILL.md (lines 35-38), the daemon first attempts to locate an existing Chrome instance running with remote debugging enabled (typically listening on http://localhost:9222).

If the daemon finds a debuggable Chrome, it attaches to that session, preserving any logged-in states, cookies, or extensions you have configured. If no such instance exists, the CLI automatically falls back to launching an isolated browser, ensuring your scripts never fail due to missing prerequisites.

Key Differences and When to Use Each

Aspect	Local Isolated	Auto-Connect
Startup Behavior	Always launches new Chrome process	Attaches to existing Chrome if available; falls back to isolated
Session State	Clean profile, no cookies	Preserves existing login state and cookies
Failure Mode	Succeeds if Chrome is installed	Always succeeds (graceful fallback to isolated)
Best For	Reproducible tests, CI/CD	Local development with manual login workflows

Choose local isolated browser mode when you need deterministic, stateless execution. Choose auto-connect Chrome mode when you want to leverage an existing browser session where you have already completed manual authentication steps.

How It Works Under the Hood

The browse CLI operates through a background daemon that manages browser lifecycle automatically. When you issue your first command (such as browse open), the daemon starts and evaluates your environment settings.

In isolated mode, the daemon spawns Chrome with a temporary user data directory, ensuring complete separation between runs. In auto-connect mode, the daemon checks for a reachable Chrome DevTools Protocol (CDP) endpoint before attempting connection. The implementation details in skills/browser/REFERENCE.md (lines 24-28 and 75-85) describe how the CLI handles the env command parsing and the fallback mechanism.

The chosen environment persists for the duration of your session until you explicitly run browse stop or switch environments using another browse env command.

Practical Code Examples

Launch a Clean, Isolated Browser

Use this approach for reproducible automation and testing scenarios:

# Set environment to isolated local browser

browse env local

# Navigate and interact

browse open https://example.com
browse snapshot
browse click @0-5

# Clean up

browse stop

Connect to an Existing Chrome Session

First, ensure Chrome is running with remote debugging enabled:

# Terminal 1: Start Chrome with debugging port

google-chrome --remote-debugging-port=9222

Then attach using the CLI:

# Set environment to auto-connect mode

browse env local --auto-connect

# Uses existing Chrome session with your logged-in state

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

Attach to a Specific CDP Endpoint

For advanced use cases requiring a specific WebSocket endpoint:

browse env local ws://localhost:9222/devtools/browser/1234
browse open https://example.com

Switching Between Modes

You can override previous environment settings by simply invoking browse env again:

# Switch back to isolated after using auto-connect

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

Summary

• browse env local launches a deterministic, isolated browser with no persisted state, ideal for automated testing and CI/CD pipelines.
• browse env local --auto-connect attempts to reuse an existing Chrome session for convenience, automatically falling back to an isolated browser if no debuggable instance is found.
• The CLI daemon manages browser lifecycle automatically, with environment configurations documented in skills/browser/SKILL.md (lines 31-41) and implementation details in skills/browser/REFERENCE.md.
• Statelessness vs. convenience is the primary trade-off: isolated mode eliminates flaky tests caused by cookie contamination, while auto-connect mode saves time during manual development workflows.

Frequently Asked Questions

What happens if auto-connect cannot find a running Chrome?

The CLI gracefully degrades to isolated mode. As implemented in the environment selection logic referenced in skills/browser/REFERENCE.md (lines 75-85), the daemon detects the missing endpoint and automatically launches a fresh Chrome instance with a temporary profile, ensuring your script continues executing without errors.

How do I enable remote debugging in Chrome for auto-connect mode?

Start Chrome with the --remote-debugging-port=9222 flag. On macOS, use open -a "Google Chrome" --args --remote-debugging-port=9222. The CLI daemon checks http://localhost:9222 by default when --auto-connect is specified, as documented in skills/browser/SKILL.md.

Can I switch between isolated and auto-connect modes in the same session?

Yes. Environment settings persist until overwritten. Simply run browse env local to switch to isolated mode or browse env local --auto-connect to switch to auto-connect mode. The change takes effect immediately for subsequent browse open commands without requiring a browse stop first.

Where is the browser environment configured in the source code?

Configuration logic resides in skills/browser/REFERENCE.md (lines 24-28) for command parsing and lines 75-85 for environment handling. High-level behavior descriptions appear in skills/browser/SKILL.md (lines 31-41), while the repository overview in README.md (lines 63-66) provides additional context on default local vs remote environment selection.

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