How to Sync Cookies from Local Chrome to Browserbase Persistent Contexts

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.

Step-by-Step Implementation

Install Dependencies

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

cd skills/cookie-sync
npm install

Export Cookies from Local Chrome

Launch Chrome with the remote debugging port enabled:

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

Run the sync script to extract and upload cookies:

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:

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:

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:

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:

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:

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:

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, with additional reference diagrams in skills/cookie-sync/REFERENCE.md.

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