ProfileDock

Persistent, auditable browser identities for humans and AI agents — local-first.

The only browser profile platform with a published threat model, anti-PID-recycling process guarantees, and a machine-stable contract. Every profile has its own browser user-data directory, preserving cookies, sessions, local storage, cache, history, and login state independently. It also automates through each profile's authenticated session (read, screenshot, PDF, JavaScript, live cookie surgery), pins per-profile identity presets (proxy, user agent, locale, timezone), serves an MCP interface for LLM agents (Claude Code, Cursor, AutoGen), and monitors live resource usage.

• Machine-stable contract: versioned CLI exit codes and frozen JSON schemas backed by golden fixtures (docs/reference/cli-contract.md).
• Auditable process identity: zero PID-recycling hazards via Win32 kernel32 process times, Linux /proc boot epochs, and BSD macOS start times.
• In-memory session integrity: live CDP cookie surgery and session extraction resilient against Windows DPAPI App-Bound Encryption — no browser restart required.
• Published threat model: transparent security boundaries documenting exact containment rules (docs/reference/threat-model.md).

Installation

Python 3.10 or newer is required. Google Chrome or Chromium is required for the default Direct engine. From the cloned repository root:

python scripts/setup_project.py --dev

This creates an isolated .venv — nothing touches your system Python — and installs the exact pinned dependency versions from requirements-dev.lock. Activate it, then verify:

.\.venv\Scripts\Activate.ps1

source .venv/bin/activate

profiledock --version

For the Playwright engine add:

python scripts/setup_project.py --with-playwright

Manual setup, per-platform commands, and troubleshooting: Installation guide.

Quick start

profiledock create "Personal" --engine direct
profiledock create "Work" --engine playwright
profiledock launch Personal --tabs 3
profiledock close Personal
profiledock launch Personal --tabs 3

Login is always manual. Relaunching the same profile reuses its persistent browser data.

Core commands

profiledock create NAME
profiledock list
profiledock show PROFILE
profiledock launch PROFILE [--tabs N]
profiledock close PROFILE
profiledock status [PROFILE]
profiledock top [PROFILE]
profiledock read PROFILE [URL]
profiledock shot PROFILE [URL] [--full-page]
profiledock pdf PROFILE [URL]
profiledock eval PROFILE SCRIPT
profiledock cookies PROFILE [--output FILE]
profiledock config set PROFILE SETTING VALUE
profiledock backup PROFILE --output ARCHIVE
profiledock restore ARCHIVE
profiledock doctor
profiledock delete PROFILE

Full command list with every argument, option, alias, exit code, and JSON behavior: command reference.

Documentation

The full documentation covers:

• Installation and getting started
• Every command
• Configuration and browser engines
• Storage, backup, restore, migration, and recovery
• Operations, troubleshooting, updates, and complete removal
• Security and privacy and the threat model
• Planned 1.0 CLI compatibility contract
• Command-specific JSON output schemas
• Development and testing

Security note

Browser-data directories contain sensitive session information. Keep the data root private, protect backups, and close profiles before backup or migration.

Development

python scripts/setup_project.py --dev --with-playwright
python -m pytest -q

License

ProfileDock is licensed under the MIT License.