# How to Sync Cookies from Local Chrome to Browserbase Persistent Contexts

> Sync local Chrome cookies to Browserbase persistent contexts with the cookie-sync skill. Extract cookies via Chrome DevTools Protocol for authenticated cloud browsing sessions.

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

---

**You can sync cookies from your local Chrome browser to a Browserbase persistent context by running the cookie-sync skill, which extracts cookies via Chrome DevTools Protocol and uploads them to the Browserbase API, enabling authenticated browsing sessions in the cloud.**

The **cookie-sync** skill in the `browserbase/skills` repository bridges your local Chrome session with Browserbase cloud browsers. By extracting authentication cookies from your desktop browser and importing them into a persistent Browserbase context, you eliminate the need to re-authenticate when automating workflows in the cloud.

## Prerequisites for Cookie Synchronization

Before running the sync operation, ensure your local environment meets these requirements:

- **Chrome must run with remote debugging enabled** using `--remote-debugging-port=9222` to expose the Chrome DevTools Protocol (CDP) endpoint.
- **Node.js and npm** installed to execute the `cookie-sync.mjs` script.
- **Browserbase API credentials** configured in your environment to authenticate requests to `/v1/contexts`.

## How the Cookie Sync Architecture Works

According to the `browserbase/skills` source code, the synchronization follows a three-stage pipeline:

1. **Local Chrome Connection** – The script connects to your local Chrome instance via the CDP URL (`http://localhost:9222`) and enumerates open pages.
2. **Cookie Extraction** – Using the CDP `Network.getAllCookies` command, the skill pulls all cookies from the local store and optionally filters them by domain.
3. **Browserbase Context Creation** – The extracted cookies are sent to the Browserbase API, creating or updating a persistent context (`ctx_...`) that retains authentication state across sessions.

The implementation resides in `skills/cookie-sync/scripts/cookie-sync.mjs`, while the high-level workflow is documented in [`skills/cookie-sync/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/cookie-sync/SKILL.md).

## Step-by-Step Implementation

### Install Dependencies

Navigate to the cookie-sync skill directory and install required packages:

```bash
cd skills/cookie-sync
npm install

```

### Export Cookies from Local Chrome

Launch Chrome with the remote debugging port enabled:

```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222

```

Run the sync script to extract and upload cookies:

```bash
node skills/cookie-sync/scripts/cookie-sync.mjs

```

### Import Cookies to Browserbase Context

By default, the script creates a new persistent context. To refresh an existing context instead, pass the context ID:

```bash
node skills/cookie-sync/scripts/cookie-sync.mjs \
  --context ctx_abc123

```

The script outputs the context ID (e.g., `ctx_xyz789`), which you will use to launch authenticated browsing sessions.

## Advanced Configuration Options

### Filter by Domain

Limit cookie synchronization to specific domains to reduce context size and improve security:

```bash
node skills/cookie-sync/scripts/cookie-sync.mjs \
  --domains google.com,github.com

```

This applies domain matching including sub-domains, ensuring only relevant authentication tokens are transferred.

### Enable Stealth Mode

For sites with sophisticated bot detection, enable stealth mode to activate anti-detection evasions:

```bash
node skills/cookie-sync/scripts/cookie-sync.mjs \
  --stealth

```

**Stealth mode** implements user-agent randomization, canvas spoofing, and other fingerprint randomization techniques as implemented in the Browserbase infrastructure.

### Configure Residential Proxy

Align your cloud browser's IP geolocation with your local machine to prevent authentication challenges:

```bash
node skills/cookie-sync/scripts/cookie-sync.mjs \
  --proxy "San Francisco,CA,US"

```

The residential proxy routes traffic through an IP address matching your specified city and country, reducing the likelihood of re-authentication requests.

## Using the Synced Context with the Browse CLI

Once you have a context ID, launch an authenticated browsing session using the `browse` CLI tool:

```bash
browse open https://mail.google.com \
  --context-id ctx_abc123 \
  --persist

```

The `--persist` flag ensures that any new cookies or local storage changes during the session are written back to the same Browserbase context, maintaining state for future runs.

Additional workflow commands include:

```bash
browse snapshot    # Capture page state

browse screenshot  # Take a visual screenshot

browse stop      # Terminate the session

```

## Summary

- The **cookie-sync** skill connects to local Chrome via **Chrome DevTools Protocol** to extract cookies using the `Network.getAllCookies` command.
- The main implementation script is located at `skills/cookie-sync/scripts/cookie-sync.mjs`.
- Use `--domains` to filter which cookies sync, `--stealth` for anti-bot protection, and `--proxy` for geo-matching residential IPs.
- Persistent contexts enable reusing authentication state across multiple `browse` CLI sessions when combined with the `--context-id` and `--persist` flags.

## Frequently Asked Questions

### What is Chrome DevTools Protocol (CDP) and why is it required?

**Chrome DevTools Protocol (CDP)** is a JSON-based remote debugging interface that Chrome exposes when started with `--remote-debugging-port`. The cookie-sync skill requires CDP because it uses the `Network.getAllCookies` command to programmatically read the complete cookie store from your local browser, which is not accessible through standard file system operations.

### How do I refresh cookies in an existing Browserbase context?

Pass the existing context ID using the `--context` flag when running `cookie-sync.mjs`. For example: `node skills/cookie-sync/scripts/cookie-sync.mjs --context ctx_abc123`. This updates the persistent context with fresh cookies from your local browser without creating a new context ID.

### When should I use stealth mode and residential proxies?

Use **stealth mode** (`--stealth`) when targeting sites with aggressive bot detection mechanisms that check for headless browser signatures. Use **residential proxies** (`--proxy "City,ST,Country"`) when the target site performs IP-based geo-verification or when your local and cloud browser IP locations differ significantly, which can trigger additional authentication challenges.

### Where are the cookie-sync scripts located in the repository?

The primary executable is located at `skills/cookie-sync/scripts/cookie-sync.mjs` in the `browserbase/skills` repository. Documentation for the skill resides in [`skills/cookie-sync/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/cookie-sync/SKILL.md), with additional reference diagrams in [`skills/cookie-sync/REFERENCE.md`](https://github.com/browserbase/skills/blob/main/skills/cookie-sync/REFERENCE.md).