GSD Browser Sessions: Isolated Browser Contexts

Named sessions isolate cookies, storage, and cache per workflow. Run parallel agents, persist auth state, and scope the action cache and vault per session.

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

Both sessions run independently — different Chrome windows, different cookies, zero cross-contamination.

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

Set the variable when launching the daemon — either before the first command that starts it, or in the 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

Saved states survive daemon restarts and machine reboots. After restoring, the session is ready to use immediately — the browser picks up authentication cookies and storage from the saved snapshot.

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

This means the action cache learned from a checkout session does not bleed into a dashboard session, and vault credentials stored for checkout are not accessible to dashboard.

Common patterns

Persistent auth

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

Parallel agents

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

Clean test scenarios

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.