# Sessions Run multiple isolated browser instances: ```bash # Different sessions agent-browser --session agent1 open site-a.com agent-browser --session agent2 open site-b.com # Or via environment variable AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn" # List active sessions agent-browser session list # Output: # Active sessions: # -> default # agent1 # Show current session agent-browser session ``` ## Session isolation Each session has its own: - Browser instance - Cookies and storage - Navigation history - Authentication state ## Persistent profiles By default, browser state is lost when the browser closes. Use `--profile` to persist state across restarts: ```bash # Use a persistent profile directory agent-browser --profile ~/.myapp-profile open myapp.com # Login once, then reuse the authenticated session agent-browser --profile ~/.myapp-profile open myapp.com/dashboard # Or via environment variable AGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com ``` The profile directory stores: - Cookies and localStorage - IndexedDB data - Service workers - Browser cache - Login sessions ## Import auth from your browser If you are already logged in to a site in Chrome, you can grab that auth state and reuse it in agent-browser. This is the fastest way to bypass login flows, OAuth, SSO, or 2FA. **Step 1:** Start Chrome with remote debugging: ```bash # macOS "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 # Linux google-chrome --remote-debugging-port=9222 ``` Log in to your target site(s) in this Chrome window. `--remote-debugging-port` exposes full browser control on localhost. Any local process can connect. Only use on trusted machines and close Chrome when done. **Step 2:** Connect and save the authenticated state: ```bash agent-browser --auto-connect state save ./my-auth.json ``` **Step 3:** Use the saved auth in future sessions: ```bash # Load auth at launch agent-browser --state ./my-auth.json open https://app.example.com/dashboard # Or load into an existing session agent-browser state load ./my-auth.json agent-browser open https://app.example.com/dashboard ``` Combine with `--session-name` so the imported auth auto-persists across restarts: ```bash agent-browser --session-name myapp state load ./my-auth.json # From now on, state auto-saves/restores for "myapp" ``` State files contain session tokens in plaintext. Add them to `.gitignore` and delete when no longer needed. For encryption at rest, see [State encryption](#state-encryption) below. ## Session persistence Use `--session-name` to automatically save and restore cookies and localStorage across browser restarts: ```bash # Auto-save/load state for "twitter" session agent-browser --session-name twitter open twitter.com # Login once, then state persists automatically agent-browser --session-name twitter click "#login" # Or via environment variable export AGENT_BROWSER_SESSION_NAME=twitter agent-browser open twitter.com ``` State files are stored in `~/.agent-browser/sessions/` and automatically loaded on daemon start. ### Session name rules Session names must contain only alphanumeric characters, hyphens, and underscores: ```bash # Valid session names agent-browser --session-name my-project open example.com agent-browser --session-name test_session_v2 open example.com # Invalid (will be rejected) agent-browser --session-name "../bad" open example.com # path traversal agent-browser --session-name "my session" open example.com # spaces agent-browser --session-name "foo/bar" open example.com # slashes ``` ## State encryption Encrypt saved state files (cookies, localStorage) using AES-256-GCM: ```bash # Generate a 256-bit key (64 hex characters) openssl rand -hex 32 # Set the encryption key export AGENT_BROWSER_ENCRYPTION_KEY= # State files are now encrypted automatically agent-browser --session-name secure-session open example.com # List states shows encryption status agent-browser state list ``` ## State auto-expiration Automatically delete old state files to prevent accumulation: ```bash # Set expiration (default: 30 days) export AGENT_BROWSER_STATE_EXPIRE_DAYS=7 # Manually clean old states agent-browser state clean --older-than 7 ``` ## State management commands ```bash # List all saved states agent-browser state list # Show state summary (cookies, origins, domains) agent-browser state show my-session-default.json # Rename a state file agent-browser state rename old-name new-name # Clear states for a specific session name agent-browser state clear my-session # Clear all saved states agent-browser state clear --all # Manual save/load (for custom paths) agent-browser state save ./backup.json agent-browser state load ./backup.json ``` ## Authenticated sessions Use `--headers` to set HTTP headers for a specific origin: ```bash # Headers scoped to api.example.com only agent-browser open api.example.com --headers '{"Authorization": "Bearer "}' # Requests to api.example.com include the auth header agent-browser snapshot -i --json agent-browser click @e2 # Navigate to another domain - headers NOT sent agent-browser open other-site.com ``` Useful for: - **Skipping login flows** - Authenticate via headers - **Switching users** - Different auth tokens per session - **API testing** - Access protected endpoints - **Security** - Headers scoped to origin, not leaked ## Multiple origins ```bash agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}' agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}' ``` ## Global headers For headers on all domains: ```bash agent-browser set headers '{"X-Custom-Header": "value"}' ``` ## Environment variables
VariableDescription
AGENT_BROWSER_SESSIONBrowser session ID (default: "default")
AGENT_BROWSER_SESSION_NAMEAuto-save/load state persistence name
AGENT_BROWSER_ENCRYPTION_KEY64-char hex key for AES-256-GCM encryption
AGENT_BROWSER_STATE_EXPIRE_DAYSAuto-delete states older than N days (default: 30)