How to Create and Reuse Browserbase Persistent Contexts: A Complete Guide

Browserbase persistent contexts are server-side containers that store browser state—including cookies, localStorage, and IndexedDB—across separate sessions, allowing you to authenticate once and reuse that session indefinitely via the Browserbase SDK and Stagehand.

A Browserbase persistent context eliminates the need to re-authenticate for every automated browser session. By storing state server-side in the browserbase/skills repository, you can create a context once and attach it to subsequent cloud browser sessions. This guide walks through the exact implementation found in the cookie-sync skill, covering context creation, state injection, and reuse patterns.

Understanding Browserbase Persistent Contexts

A persistent context acts as a durable container that lives beyond individual browser sessions. Unlike ephemeral sessions that lose all data upon closure, contexts marked with persist: true write state changes back to Browserbase infrastructure. According to the architecture documentation in skills/cookie-sync/REFERENCE.md, this enables long-running authentication states for automation workflows.

The implementation relies on two core dependencies defined in package.json:

• @browserbasehq/sdk – Handles context lifecycle management and cookie operations
• @browserbasehq/stagehand – Bridges local Chrome (via CDP) and cloud browser instances

Creating a New Persistent Context

To initialize a persistent context, the script invokes the Browserbase SDK and explicitly enables persistence.

In skills/cookie-sync/scripts/cookie-sync.mjs, the creation flow works as follows:

1. Initialize the SDK client and call the context creation endpoint
2. Set persist: true to ensure state mutations are written back to the container
3. Capture the returned context ID (e.g., ctx_abc123) for future reuse

The SDK returns a unique identifier that serves as the anchor for all subsequent state storage. As noted in the reference architecture, this ID remains valid indefinitely unless explicitly deleted.

Injecting Browser State into the Context

Once created, the context is empty. The cookie-sync implementation demonstrates how to populate it using Stagehand to extract state from a local Chrome instance.

According to skills/cookie-sync/REFERENCE.md, the injection process involves:

• Extracting cookies from local Chrome using context.cookies() via CDP
• Loading cookies into the cloud context using context.addCookies()

This bidirectional flow—local extraction to cloud injection—ensures your authenticated state transfers seamlessly from your development machine to the Browserbase infrastructure.

Reusing Existing Contexts

The primary benefit of persistent contexts is reuse. Browserbase provides two methods to attach an existing context to a new session.

Method 1: Environment Variable

Set BROWSERBASE_CONTEXT_ID before executing your script. As documented in skills/cookie-sync/REFERENCE.md, the SDK detects this variable and skips creation, instead attaching to the existing context and re-injecting fresh cookies as needed.

Method 2: Command-Line Interface

Pass the context ID directly via the browse CLI. The skills/browserbase-cli/REFERENCE.md file shows the pattern:

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

The --persist flag ensures the session remains alive (keepAlive: true) and writes any new state changes back to the same context.

Practical Usage Examples

Below are runnable commands from the cookie-sync skill demonstrating the full lifecycle. Replace <ctx-id> with your actual context identifier.

Create a new context and sync all cookies:

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

# Output: Context ID: ctx_abc123

Reuse the context for authenticated browsing:

browse open https://github.com/login --context-id ctx_abc123 --persist

Refresh cookies in an existing context:

node skills/cookie-sync/scripts/cookie-sync.mjs --context ctx_abc123

Sync only specific domains:

node skills/cookie-sync/scripts/cookie-sync.mjs \
  --domains google.com,github.com \
  --context ctx_abc123

Combine with stealth mode and residential proxies:

node skills/cookie-sync/scripts/cookie-sync.mjs \
  --context ctx_abc123 \
  --stealth \
  --proxy "San Francisco,CA,US"

Key Implementation Files

Understanding the source structure helps when customizing persistent context workflows:

• skills/cookie-sync/REFERENCE.md – Technical architecture and SDK call details
• skills/cookie-sync/SKILL.md – User-facing documentation and CLI flag explanations
• skills/cookie-sync/scripts/cookie-sync.mjs – Node.js implementation of context creation and cookie injection
• skills/browserbase-cli/REFERENCE.md – browse CLI usage patterns including --context-id and --persist
• package.json – Dependency list for @browserbasehq/sdk and @browserbasehq/stagehand

Summary

• Persistent contexts store browser state server-side using the Browserbase SDK with the persist: true flag
• Context IDs (e.g., `ctx_abc123) serve as durable references that survive across sessions
• Stagehand handles the extraction of cookies from local Chrome and injection into cloud sessions via context.addCookies()
• Reuse methods include setting the BROWSERBASE_CONTEXT_ID environment variable or passing --context-id to the browse CLI
• The --persist flag ensures state changes write back to the context, maintaining authentication across runs

Frequently Asked Questions

How long does a Browserbase persistent context last?

A persistent context remains available indefinitely on Browserbase infrastructure until explicitly deleted. The stored state (cookies, localStorage) persists according to the hosting website's own expiration policies, but the container itself does not expire.

Can I use persistent contexts with the browse CLI?

Yes. The browse open command accepts --context-id <id> to attach an existing context and --persist to ensure state writes back. According to skills/browserbase-cli/REFERENCE.md, this combination allows you to resume authenticated sessions directly from the command line.

What is the difference between a context and a session?

A session is an ephemeral browser instance that terminates when closed. A context is a server-side storage container that survives between sessions. When you reuse a context ID, Browserbase attaches a new session to the existing state container, restoring cookies and localStorage from previous runs.

Do I need Stagehand to use persistent contexts?

While the Browserbase SDK can create and manage contexts independently, Stagehand is required for the cookie-sync workflow demonstrated in skills/cookie-sync/scripts/cookie-sync.mjs. Stagehand provides the CDP bridge to extract cookies from local Chrome instances and inject them into cloud contexts using context.addCookies().

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