Core Concepts

Profiles

Profiles are isolated Chrome user data directories with encrypted state. Each profile has its own cookies, localStorage, extensions, and saved passwords — completely separate from every other profile.

Two kinds of profiles

Pagerunner supports two profile types:

  • Personal profiles — your existing Chrome profiles with real accounts, cookies, and saved passwords. Use these when you need authenticated access to sites you're already logged into.
  • Agent profiles — fresh Chrome data directories created specifically for automation. Clean state, no personal data, purpose-built for the agent's work.

Auto-detect profiles

The easiest way to set up profiles is to let pagerunner discover your existing Chrome profiles:

terminal
pagerunner init

This reads Chrome's profile list and writes ~/.pagerunner/config.toml. Run pagerunner status to verify, or pagerunner profiles to list them.

Listing profiles

terminal
# Human-readable
pagerunner profiles
# JSON (for agents)
pagerunner list-profiles
# Via MCP tool
list_profiles()

Profile isolation

Each profile is completely sandboxed:

  • Cookies and sessions — logging into GitHub in the work profile doesn't affect the personal profile
  • localStorage and IndexedDB — site data stays within its profile
  • Extensions — each profile can have different Chrome extensions installed
  • Snapshots and checkpoints — scoped to their profile in the encrypted database
  • Site knowledge — adapters and selector data are per-profile

Manual configuration

You can also configure profiles by hand in ~/.pagerunner/config.toml. Run pagerunner example-config to see the format.

~/.pagerunner/config.toml
[[profiles]]
name = "personal"
chrome_profile = "Default"
[[profiles]]
name = "work"
chrome_profile = "Profile 1"

Encrypted storage

All profile data stored by pagerunner (snapshots, checkpoints, site knowledge, KV entries, secrets) is encrypted with AES-256-GCM. The encryption key is stored in the macOS Keychain under pagerunner / db_key — it never touches the filesystem in plaintext.

Profiles only lock Chrome's profile directory while a session is active. Close any Chrome window using a profile before opening a pagerunner session on it.

Next: Sessions & Tabs →