# How to Use Local Isolated Browser vs Auto-Connect Chrome Mode in the Browserbase CLI > Master Browserbase CLI: choose between local isolated browsers or auto-connect Chrome mode for flexible debugging. Learn how to use `browse env local` with or without auto-connect. - Repository: [browserbase/skills](https://github.com/browserbase/skills) - Tags: how-to-guide - Published: 2026-05-01 --- **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`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/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: ```bash # 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: ```bash # Terminal 1: Start Chrome with debugging port google-chrome --remote-debugging-port=9222 ``` Then attach using the CLI: ```bash # 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: ```bash 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: ```bash # 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`](https://github.com/browserbase/skills/blob/main/skills/browser/SKILL.md) (lines 31-41) and implementation details in [`skills/browser/REFERENCE.md`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/skills/browser/SKILL.md) (lines 31-41), while the repository overview in [`README.md`](https://github.com/browserbase/skills/blob/main/README.md) (lines 63-66) provides additional context on default local vs remote environment selection.