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

> Learn to effortlessly switch between local and remote Browserbase sessions using the browse env command. Control local Chrome or cloud infrastructure for seamless development.

- Repository: [browserbase/skills](https://github.com/browserbase/skills)
- Tags: how-to-guide
- Published: 2026-05-01

---

**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`](https://github.com/browserbase/skills/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/skills/browser/SKILL.md)** – Defines the `browse` CLI and environment selection logic
- **[`skills/browser/REFERENCE.md`](https://github.com/browserbase/skills/blob/main/skills/browser/REFERENCE.md)** – Contains API reference for CLI options and parameters
- **[`README.md`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/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.