Sessions & Profiles

Session multiplexing for parallel agents and persistent profiles for stateful browsing.

Sessions

Sessions let multiple AI agents share one Chromium instance. Each session gets its own tabs, cookies, refs, and state — isolated from other sessions.

Creating Sessions

browse --session agent-1 goto https://app.com
browse --session agent-2 goto https://docs.app.com

Each session uses ~5MB of memory (vs ~200MB for separate browser instances).

Session Lifecycle

browse sessions                    # List active sessions
browse --session agent-1 tabs     # List tabs in session
browse session-close agent-1      # Close a session

Sessions auto-close after 30 minutes of inactivity (configurable via BROWSE_IDLE_TIMEOUT).

When to Use Sessions

Parallel agents: Multiple AI agents working simultaneously
Test isolation: Separate browser state per test
Multi-account: Different login states side by side

Persistent Profiles

Profiles go further than sessions — they use a completely separate Chromium instance with its own disk storage. Cookies, localStorage, IndexedDB, and cache persist across server restarts.

Creating Profiles

browse --profile myapp goto https://app.com
# Login, set preferences, etc.
browse stop

# Days later...
browse --profile myapp goto https://app.com
# Still logged in! All state preserved.

Managing Profiles

browse profile list                       # List profiles with disk size
browse profile delete myapp               # Delete a profile
browse profile clean                      # Remove profiles older than 7 days
browse profile clean --older-than 30      # Custom age threshold

Sessions vs Profiles

Feature	Sessions	Profiles
Isolation	Tabs, cookies, refs	Full Chromium instance
Memory	~5MB per session	~200MB per profile
Persistence	Until session closes	Across server restarts
Use case	Parallel agents	Long-lived auth state

On this page