diff --git a/README.md b/README.md index 83ffb14..faaf62b 100644 --- a/README.md +++ b/README.md @@ -308,6 +308,47 @@ agent-browser install # Download Chromium browser agent-browser install --with-deps # Also install system deps (Linux) ``` +## Authentication + +agent-browser provides multiple ways to persist login sessions so you don't re-authenticate every run. + +### Quick summary + +| Approach | Best for | Flag / Env | +|----------|----------|------------| +| **Persistent profile** | Full browser state (cookies, IndexedDB, service workers, cache) across restarts | `--profile ` / `AGENT_BROWSER_PROFILE` | +| **Session persistence** | Auto-save/restore cookies + localStorage by name | `--session-name ` / `AGENT_BROWSER_SESSION_NAME` | +| **Import from your browser** | Grab auth from a Chrome session you already logged into | `--auto-connect` + `state save` | +| **State file** | Load a previously saved state JSON on launch | `--state ` / `AGENT_BROWSER_STATE` | +| **Auth vault** | Store credentials locally (encrypted), login by name | `auth save` / `auth login` | + +### 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: + +```bash +# 1. Launch Chrome with remote debugging enabled +# macOS: +"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 +# Or use --auto-connect to discover an already-running Chrome + +# 2. Connect and save the authenticated state +agent-browser --auto-connect state save ./my-auth.json + +# 3. Use the saved auth in future sessions +agent-browser --state ./my-auth.json open https://app.example.com/dashboard + +# 4. Or use --session-name for automatic persistence +agent-browser --session-name myapp state load ./my-auth.json +# From now on, --session-name myapp auto-saves/restores this state +``` + +> **Security notes:** +> - `--remote-debugging-port` exposes full browser control on localhost. Any local process can connect. Only use on trusted machines and close Chrome when done. +> - State files contain session tokens in plaintext. Add them to `.gitignore` and delete when no longer needed. For encryption at rest, set `AGENT_BROWSER_ENCRYPTION_KEY` (see [State Encryption](#state-encryption)). + +For full details on login flows, OAuth, 2FA, cookie-based auth, and the auth vault, see the [Authentication](docs/src/app/sessions/page.mdx) docs. + ## Sessions Run multiple isolated browser instances: diff --git a/cli/src/output.rs b/cli/src/output.rs index b251aa5..0cd2f1e 100644 --- a/cli/src/output.rs +++ b/cli/src/output.rs @@ -2418,11 +2418,19 @@ Snapshot Options: -d, --depth Limit tree depth -s, --selector Scope to CSS selector +Authentication: + --profile Persist login sessions across restarts (cookies, IndexedDB, cache) + (or AGENT_BROWSER_PROFILE env) + --session-name Auto-save/restore cookies and localStorage by name + (or AGENT_BROWSER_SESSION_NAME env) + --state Load saved auth state (cookies + storage) from JSON file + (or AGENT_BROWSER_STATE env) + --auto-connect Connect to a running Chrome to reuse its auth state + Tip: agent-browser --auto-connect state save ./auth.json + --headers HTTP headers scoped to URL's origin (e.g., Authorization bearer token) + Options: --session Isolated session (or AGENT_BROWSER_SESSION env) - --profile Persistent browser profile (or AGENT_BROWSER_PROFILE env) - --state Load storage state from JSON file (or AGENT_BROWSER_STATE env) - --headers HTTP headers scoped to URL's origin (for auth) --executable-path Custom browser executable (or AGENT_BROWSER_EXECUTABLE_PATH) --extension Load browser extensions (repeatable) --args Browser launch args, comma or newline separated (or AGENT_BROWSER_ARGS) @@ -2441,10 +2449,8 @@ Options: --annotate Annotated screenshot with numbered labels and legend --headed Show browser window (not headless) (or AGENT_BROWSER_HEADED env) --cdp Connect via CDP (Chrome DevTools Protocol) - --auto-connect Auto-discover and connect to running Chrome --color-scheme Color scheme: dark, light, no-preference (or AGENT_BROWSER_COLOR_SCHEME) --download-path Default download directory (or AGENT_BROWSER_DOWNLOAD_PATH) - --session-name Auto-save/restore session state (cookies, localStorage) --content-boundaries Wrap page output in boundary markers (or AGENT_BROWSER_CONTENT_BOUNDARIES) --max-output Truncate page output to N chars (or AGENT_BROWSER_MAX_OUTPUT) --allowed-domains Restrict navigation domains (or AGENT_BROWSER_ALLOWED_DOMAINS) diff --git a/docs/src/app/sessions/page.mdx b/docs/src/app/sessions/page.mdx index bf234c2..1fe44c7 100644 --- a/docs/src/app/sessions/page.mdx +++ b/docs/src/app/sessions/page.mdx @@ -57,6 +57,50 @@ The profile directory stores: - 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: diff --git a/skills/agent-browser/SKILL.md b/skills/agent-browser/SKILL.md index da77998..ba343b0 100644 --- a/skills/agent-browser/SKILL.md +++ b/skills/agent-browser/SKILL.md @@ -44,6 +44,62 @@ agent-browser open https://example.com && agent-browser wait --load networkidle **When to chain:** Use `&&` when you don't need to read the output of an intermediate command before proceeding (e.g., open + wait + screenshot). Run commands separately when you need to parse the output first (e.g., snapshot to discover refs, then interact using those refs). +## Handling Authentication + +When automating a site that requires login, choose the approach that fits: + +**Option 1: Import auth from the user's browser (fastest for one-off tasks)** + +```bash +# Connect to the user's running Chrome (they're already logged in) +agent-browser --auto-connect state save ./auth.json +# Use that auth state +agent-browser --state ./auth.json open https://app.example.com/dashboard +``` + +State files contain session tokens in plaintext -- add to `.gitignore` and delete when no longer needed. Set `AGENT_BROWSER_ENCRYPTION_KEY` for encryption at rest. + +**Option 2: Persistent profile (simplest for recurring tasks)** + +```bash +# First run: login manually or via automation +agent-browser --profile ~/.myapp open https://app.example.com/login +# ... fill credentials, submit ... + +# All future runs: already authenticated +agent-browser --profile ~/.myapp open https://app.example.com/dashboard +``` + +**Option 3: Session name (auto-save/restore cookies + localStorage)** + +```bash +agent-browser --session-name myapp open https://app.example.com/login +# ... login flow ... +agent-browser close # State auto-saved + +# Next time: state auto-restored +agent-browser --session-name myapp open https://app.example.com/dashboard +``` + +**Option 4: Auth vault (credentials stored encrypted, login by name)** + +```bash +echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin +agent-browser auth login myapp +``` + +**Option 5: State file (manual save/load)** + +```bash +# After logging in: +agent-browser state save ./auth.json +# In a future session: +agent-browser state load ./auth.json +agent-browser open https://app.example.com/dashboard +``` + +See [references/authentication.md](references/authentication.md) for OAuth, 2FA, cookie-based auth, and token refresh patterns. + ## Essential Commands ```bash diff --git a/skills/agent-browser/references/authentication.md b/skills/agent-browser/references/authentication.md index 12ef5e4..89f4788 100644 --- a/skills/agent-browser/references/authentication.md +++ b/skills/agent-browser/references/authentication.md @@ -6,6 +6,9 @@ Login flows, session persistence, OAuth, 2FA, and authenticated browsing. ## Contents +- [Import Auth from Your Browser](#import-auth-from-your-browser) +- [Persistent Profiles](#persistent-profiles) +- [Session Persistence](#session-persistence) - [Basic Login Flow](#basic-login-flow) - [Saving Authentication State](#saving-authentication-state) - [Restoring Authentication](#restoring-authentication) @@ -16,6 +19,104 @@ Login flows, session persistence, OAuth, 2FA, and authenticated browsing. - [Token Refresh Handling](#token-refresh-handling) - [Security Best Practices](#security-best-practices) +## Import Auth from Your Browser + +The fastest way to authenticate is to reuse cookies from a Chrome session you are already logged into. + +**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 + +# Windows +"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 +``` + +Log in to your target site(s) in this Chrome window as you normally would. + +> **Security note:** `--remote-debugging-port` exposes full browser control on localhost. Any local process can connect and read cookies, execute JS, etc. Only use on trusted machines and close Chrome when done. + +**Step 2: Grab the auth state** + +```bash +# Auto-discover the running Chrome and save its cookies + localStorage +agent-browser --auto-connect state save ./my-auth.json +``` + +**Step 3: Reuse in automation** + +```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 +``` + +This works for any site, including those with complex OAuth flows, SSO, or 2FA -- as long as Chrome already has valid session cookies. + +> **Security note:** State files contain session tokens in plaintext. Add them to `.gitignore`, delete when no longer needed, and set `AGENT_BROWSER_ENCRYPTION_KEY` for encryption at rest. See [Security Best Practices](#security-best-practices). + +**Tip:** 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 is auto-saved/restored for "myapp" +``` + +## Persistent Profiles + +Use `--profile` to point agent-browser at a Chrome user data directory. This persists everything (cookies, IndexedDB, service workers, cache) across browser restarts without explicit save/load: + +```bash +# First run: login once +agent-browser --profile ~/.myapp-profile open https://app.example.com/login +# ... complete login flow ... + +# All subsequent runs: already authenticated +agent-browser --profile ~/.myapp-profile open https://app.example.com/dashboard +``` + +Use different paths for different projects or test users: + +```bash +agent-browser --profile ~/.profiles/admin open https://app.example.com +agent-browser --profile ~/.profiles/viewer open https://app.example.com +``` + +Or set via environment variable: + +```bash +export AGENT_BROWSER_PROFILE=~/.myapp-profile +agent-browser open https://app.example.com/dashboard +``` + +## Session Persistence + +Use `--session-name` to auto-save and restore cookies + localStorage by name, without managing files: + +```bash +# Auto-saves state on close, auto-restores on next launch +agent-browser --session-name twitter open https://twitter.com +# ... login flow ... +agent-browser close # state saved to ~/.agent-browser/sessions/ + +# Next time: state is automatically restored +agent-browser --session-name twitter open https://twitter.com +``` + +Encrypt state at rest: + +```bash +export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32) +agent-browser --session-name secure open https://app.example.com +``` + ## Basic Login Flow ```bash diff --git a/src/browser.ts b/src/browser.ts index 43d643e..fb03586 100644 --- a/src/browser.ts +++ b/src/browser.ts @@ -920,9 +920,7 @@ export class BrowserManager { const browserbaseApiKey = process.env.BROWSERBASE_API_KEY; if (!browserbaseApiKey) { - throw new Error( - 'BROWSERBASE_API_KEY is required when using browserbase as a provider' - ); + throw new Error('BROWSERBASE_API_KEY is required when using browserbase as a provider'); } const response = await fetch('https://api.browserbase.com/v1/sessions', {