Persistent Browser Sessions Explained

The problem

Every time an AI agent opens a new browser session, it starts from scratch — no cookies, no localStorage, no login state. If your agent logged into Twitter, filled out forms, or authenticated with an OAuth provider, all that state is lost when the session closes.

For short-lived tasks this is fine. But for agents that need to maintain relationships with websites over time — monitoring dashboards, managing social media, or automating workflows that require authentication — starting fresh every time is a showstopper.

What gets saved

BrowserFabric's persistent contexts capture the full browser state that websites use to identify and remember you:

• Cookies — session tokens, auth cookies, tracking cookies, consent preferences
• localStorage — app state, user preferences, cached data, JWT tokens
• Origins — which domains the state belongs to

This is Playwright's storageState — the same format used by Playwright's own persistence features, so it's well-tested and reliable.

How it works

1. Save on close (automatic)

Create a session with persist=True. When the session closes, the browser state is automatically extracted and saved to the database.

async with browserfabric.browser(persist=True) as session:
    await session.navigate("https://app.example.com/login")
    await session.type("#email", "user@example.com")
    await session.type("#password", "secret")
    await session.click("#submit")
    # State auto-saved when session closes

2. Save manually (explicit)

Call save_context at any point during a session to snapshot the current state. You can save multiple times — each save creates a new version.

ctx = await session.save_context("my-app-login")
# Returns: {"context_id": "uuid", "version": 1, "cookies_count": 12}

# Save again after more actions
ctx2 = await session.save_context("my-app-login")
# Returns: {"context_id": "uuid", "version": 2, "cookies_count": 15}

3. Restore in a new session

Pass the context ID when creating a new session. The saved cookies and localStorage are injected before any navigation — the website sees you as already logged in.

async with browserfabric.browser(
    context_id=ctx["context_id"]
) as session:
    await session.navigate("https://app.example.com/dashboard")
    # Already authenticated — no login needed

Context versioning

Every time you save a context with the same name, BrowserFabric creates a new version and marks the previous one as "superseded". This gives you a history of state changes and the ability to restore any previous version.

TTL and expiration

Contexts can have a time-to-live (TTL). After the TTL expires, the context is automatically cleaned up. This is useful for temporary auth sessions or test data.

# Context expires in 24 hours
await session.save_context("temp-login", ttl_hours=24)

Encryption at rest

Browser contexts contain sensitive data — auth tokens, session cookies, personal preferences. BrowserFabric encrypts all context data at rest using Fernet symmetric encryption. Set the CONTEXT_ENCRYPTION_KEY environment variable to enable it.

Use cases

• Social media agents — log in once, run daily tasks without re-authentication
• E-commerce monitoring — maintain cart state, wishlists, and account preferences
• SaaS automation — interact with dashboards that require login without storing raw credentials
• Testing — set up auth state once, reuse across hundreds of test runs

Get started with persistent sessions in the documentation.