Session Management: Persistent State Across Agent Runs

Every time Browser Use launches a fresh Chromium instance, you start from zero. No cookies. No localStorage. No authenticated sessions. If your agent workflow involves logging into a SaaS dashboard, checking an email inbox, or pulling data from a service that requires authentication, that login step has to happen on every. single. run. That's not just wasteful — it's a reliability risk. Login flows are among the most fragile browser automation tasks: a changed button selector, a newly added 2FA prompt, or a CAPTCHA challenge can break your entire pipeline.

The solution is the Chromium user data directory. Chrome stores everything that defines a "session" — cookies, local storage, IndexedDB, service worker registrations, extension state — in a single directory on disk. When you provide a user_data_dir to Browser Use's Browser class, Chromium picks up exactly where it left off. Cookie-based sessions persist. OAuth tokens in localStorage persist. Even the browser cache persists, which speeds up repeat visits to the same domains. In Docker, you mount this directory as a volume so it survives container restarts.

But persistence on a single machine isn't enough for production. If your agent runs on an autoscaling group or a Kubernetes cluster, containers come and go. The user data directory needs to be portable. The pattern: before each agent run, download the latest profile snapshot from S3 (or any object store). After each run, upload the updated profile back. This is essentially a poor man's stateful workload on stateless infrastructure. For multi-agent deployments, add a simple lock file in S3 so two agents don't try to use the same profile simultaneously.

A word on security: a Chromium user data directory contains every cookie and token from every site the agent has visited. In the wrong hands, this is a session hijacking goldmine. Encrypt the profile data at rest — either with S3 server-side encryption (a one-line bucket configuration) or with client-side AES-256 before upload. The full chapter covers encryption in detail, including a script that handles encryption, compression, and upload in a single pipeline.

#!/bin/bash
# Session snapshot/restore for Browser Use agent profiles
# Usage: ./session.sh save agent-1   OR   ./session.sh restore agent-1

PROFILE_DIR="./profiles/$2"
S3_BUCKET="s3://browser-use-sessions/$2"
PROFILE_ARCHIVE="/tmp/$2-profile.tar.gz"
S3_LOCK="s3://browser-use-sessions/$2/.lock"

case "$1" in
  save)
    # Wait for agent to release lock (written by agent on clean exit)
    tar -czf "$PROFILE_ARCHIVE" -C "$PROFILE_DIR" .
    aws s3 cp "$PROFILE_ARCHIVE" "$S3_BUCKET/profile.tar.gz" --sse AES256
    aws s3 rm "$S3_LOCK"
    rm "$PROFILE_ARCHIVE"
    echo "Session saved and lock released."
    ;;
  restore)
    aws s3 cp "$S3_BUCKET/profile.tar.gz" "$PROFILE_ARCHIVE" 2>/dev/null
    if [ $? -eq 0 ]; then
      mkdir -p "$PROFILE_DIR"
      tar -xzf "$PROFILE_ARCHIVE" -C "$PROFILE_DIR"
      rm "$PROFILE_ARCHIVE"
      echo "Session restored from S3."
    else
      echo "No existing session. Starting fresh."
    fi
    ;;
esac