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

> Learn how to create and reuse Browserbase persistent contexts. Store browser state like cookies and localStorage across sessions for indefinite session reuse with the Browserbase SDK.

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

---

**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`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/skills/browserbase-cli/REFERENCE.md) file shows the pattern:

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

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

# Output: Context ID: ctx_abc123

```

**Reuse the context for authenticated browsing:**

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

```

**Refresh cookies in an existing context:**

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

```

**Sync only specific domains:**

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

```

**Combine with stealth mode and residential proxies:**

```bash
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`](https://github.com/browserbase/skills/blob/main/skills/cookie-sync/REFERENCE.md) – Technical architecture and SDK call details
- [`skills/cookie-sync/SKILL.md`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/skills/browserbase-cli/REFERENCE.md) – `browse` CLI usage patterns including `--context-id` and `--persist`
- [`package.json`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/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()`.