Sessions & Auth

Log in once and every later run starts logged in; give each agent its own isolated browser so they never fight over tabs. This page covers three things: persisting session state to reuse it across runs, running multiple browsers in parallel with --session, and cleanly resetting the session daemon when it gets stuck.

Persist login state across runs

Log in once, save cookies and localStorage to a file, then load it on later runs to start already logged in — no need to walk through the login form every time. Save with state save; pass --state at launch, or use state load to inject the state into the current session and keep going:

# Log in once, save cookies + localStorage + login state
$ chrome-use state save ./auth.json

# Pass the state at launch — start already logged in
$ chrome-use --state ./auth.json open https://app.example.com

# Or inject saved state into the current session and keep going
$ chrome-use state load ./auth.json
$ chrome-use open https://app.example.com/dashboard

For how to log in cleanly first and then save the session, see Login & Credentials — that page covers the same state save from the login-flow angle.

The state file is a plain JSON document with cookies, both kinds of storage, and an origins list:

{
  "cookies": [...],
  "localStorage": {...},
  "sessionStorage": {...},
  "origins": [...]
}

Automatic save/restore: --session-name

If you'd rather not save/load by hand, use --session-name (or the environment variable AGENT_BROWSER_SESSION_NAME) — state for a same-named session is saved automatically and restored automatically on later runs:

$ AGENT_BROWSER_SESSION_NAME=my-app chrome-use open https://app.example.com
# Run again with the same name later and state is restored automatically

Run multiple browsers in parallel with --session

Each --session <name> is a mutually isolated browser — its own cookies, LocalStorage / SessionStorage, IndexedDB, cache, history, and tabs. Great for testing multi-user flows or scraping in parallel:

$ chrome-use --session a open https://app.example.com
$ chrome-use --session b open https://app.example.com
$ chrome-use --session a fill @e1 "alice@test.com"
$ chrome-use --session b fill @e1 "bob@test.com"

To set a default session for the current shell, use AGENT_BROWSER_SESSION=myapp; when you omit --session, commands land on the default session. Close a session with close when you no longer need it, and use session list to see which sessions are still active:

$ AGENT_BROWSER_SESSION=myapp chrome-use open https://example.com

# Close a specific session
$ chrome-use --session auth close

# List active sessions
$ chrome-use session list

Grab a specific tab across sessions: targetId adoption

Each session has its own tab group with its own t<N> numbering (the same physical tab is t8 in session A and t1 in session B), so t<N> is not a stable handle across sessions. To grab a specific tab from another session (say a session half-filled a form but its handle died), use the stable CDP targetId:

# Re-sync the live tabs, printing target: <id> on each line
$ chrome-use tab list --full --session B

# Adopt that exact tab — no reload, state preserved
$ chrome-use tab <targetId> --session B

tab list rediscovers the live tab set on every call, so a new session can see tabs opened by other sessions (and re-attached tabs), not just its own. Adopting by targetId lands session B on that stranded tab without reloading it, so the half-filled form survives.

Reset a stuck daemon state

Each session runs a background daemon worker to hold the page handles. This daemon is also where the boa JS engine lives — the engine runs outside the page, which is why script survives whole-page hard navigations without losing state. If a session starts misbehaving — commands hitting the wrong tab, refs/handles looking stale, or a stale worker left over because you upgraded chrome-use mid-session — just restart the daemon; don't go hunting for the PID with pgrep/kill:

# List running session daemons (with relay status)
$ chrome-use daemon status

# Kill all session daemon workers
$ chrome-use daemon restart

Rare case: hand a session to the user (session handoff / resume)

session handoff is an escape hatch, not a login method. Use it only when a step is genuinely impossible for the agent — an image/behavioral captcha you can't solve, an SMS/authenticator code you have no access to, a hardware-key tap, a bank's "approve on your phone" prompt. Try autonomously first; hand off only as a last resort:

$ chrome-use session handoff   # last resort: mark user-owned; tell the user exactly what to do
# … the human does the one thing the agent truly can't …
$ chrome-use session resume    # take control back — ONLY after they confirm they're done

Related pages