A session in GSD Browser is an isolated browser context with its own cookies, local storage, service worker cache, and browser identity. When you target a named session, GSD Browser spins up a separate daemon instance and browser profile dedicated to that name. Sessions enable parallel agent tasks, clean separation between test scenarios, and persistent authentication states that survive across multiple runs.
The default session
If you run any command without --session, GSD Browser uses a single shared default session. This is fine for simple scripting and one-off tasks. For anything that requires isolation — multiple agents running concurrently, different user accounts, or separate test environments — use named sessions.
Targeting a named session
Add --session <name> to any command to route it to that session’s daemon instance:
gsd-browser --session checkout navigate https://myapp.com/checkout
gsd-browser --session checkout snapshot
gsd-browser --session checkout click @v1:e2
# A second session running in parallel
gsd-browser --session dashboard navigate https://myapp.com/dashboard
gsd-browser --session dashboard snapshot
Daemon management per session
Each named session runs its own daemon. Use the daemon subcommands with --session to manage a specific session’s daemon:
# Start a specific session's daemon explicitly
gsd-browser --session checkout daemon start
# Check daemon health for a session
gsd-browser --session checkout daemon health
# Stop a specific session's daemon
gsd-browser --session checkout daemon stop
Daemon lifecycle and idle shutdown
Each session’s daemon is long-lived but not permanent. To keep idle sessions from holding Chrome processes open forever, the daemon automatically exits when it has been idle for a configurable window, and the next CLI or MCP request transparently starts a fresh one.
Idle shutdown
The daemon tracks the time since the last IPC request it handled. After the configured idle window passes with no in-flight requests, it shuts down gracefully through the same path as daemon stop — cleaning up the browser, marking the session manifest as stopped, and releasing the IPC endpoint. The next command on that session auto-starts a new daemon, so the behavior is invisible to scripts and agents.
Configure the window with GSD_BROWSER_IDLE_SHUTDOWN_SECONDS:
# Default: shut down after 1 hour (3600 seconds) of inactivity
gsd-browser --session checkout navigate https://myapp.com
# Aggressive: shut down after 5 minutes (useful for short-lived CI jobs)
export GSD_BROWSER_IDLE_SHUTDOWN_SECONDS=300
gsd-browser --session checkout navigate https://myapp.com
# Disable idle shutdown entirely (long-running interactive sessions)
export GSD_BROWSER_IDLE_SHUTDOWN_SECONDS=0
gsd-browser --session checkout daemon start
env block of your MCP client configuration. The daemon reads it once at startup.
Auto-restart on version mismatch
When you upgrade gsd-browser, the running daemon for a session may still be the previous version. On the next request, the CLI compares its own version against the version recorded in the session manifest. If they differ, the CLI stops the live daemon and starts a new one built from the current binary before forwarding the request. No manual daemon restart is required after an upgrade.
Saving and restoring browser state
Persist the full browser state — cookies, local storage, session storage — to disk so it can be restored later. This is the recommended way to preserve authenticated states across daemon restarts.
# Save state for the current session
gsd-browser --session myapp save-state myapp-auth
# Restore state into a session
gsd-browser --session myapp restore-state myapp-auth
What sessions scope
Named sessions are more than just browser profiles. Several GSD Browser subsystems use the session name as a namespace:
| Subsystem | Scoped per session? |
|---|
| Cookies & local storage | ✅ Yes |
| Service worker & cache | ✅ Yes |
| Action cache (self-healing intent mappings) | ✅ Yes |
| Credential vault entries | ✅ Yes |
| Recording bundles & annotations | ✅ Yes |
| Timeline and diagnostic logs | ✅ Yes |
checkout session does not bleed into a dashboard session, and vault credentials stored for checkout are not accessible to dashboard.
Common patterns
Persistent auth
Parallel agents
Clean test scenarios
Log in once, save the session state, then restore it on every future run to skip the login flow:# First run: log in and save
gsd-browser --session myapp navigate https://myapp.com/login
gsd-browser --session myapp act --intent fill_email
gsd-browser --session myapp act --intent fill_password
gsd-browser --session myapp act --intent submit_form
gsd-browser --session myapp wait-for --condition network_idle
gsd-browser --session myapp save-state myapp-auth
# All future runs: restore and continue
gsd-browser --session myapp restore-state myapp-auth
gsd-browser --session myapp navigate https://myapp.com/dashboard
Run two independent agents at the same time without any interference:# Terminal 1
gsd-browser --session agent-a navigate https://site.com/page-a
gsd-browser --session agent-a snapshot
# Terminal 2 (simultaneously)
gsd-browser --session agent-b navigate https://site.com/page-b
gsd-browser --session agent-b snapshot
Give each test a fresh session so cookies and state from one scenario never affect another:gsd-browser --session test-anonymous navigate https://myapp.com
gsd-browser --session test-logged-in restore-state myapp-auth
gsd-browser --session test-logged-in navigate https://myapp.com/dashboard
Sessions in MCP
When using the MCP server, pass the session name in the server args or as an environment variable so every tool call is automatically routed to the right session:
{
"mcpServers": {
"gsd-browser-checkout": {
"command": "gsd-browser",
"args": ["mcp", "--session", "checkout"]
}
}
}
Using a named session per project keeps the action cache and vault entries scoped to that project. Over time, the self-healing cache becomes more effective because it learns from every successful interaction in that specific session context.
