GSD Browser Sessions: Isolated Browser Contexts

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
Parallel agents
Clean test scenarios

# 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.

Get Started

Core Concepts

Guides

Command Reference

GSD Browser Sessions: Isolated Browser Contexts

The default session

Targeting a named session

Daemon management per session

Daemon lifecycle and idle shutdown

Idle shutdown

Auto-restart on version mismatch

Saving and restoring browser state

What sessions scope

Common patterns

Sessions in MCP

​The default session

​Targeting a named session

​Daemon management per session

​Daemon lifecycle and idle shutdown

​Idle shutdown

​Auto-restart on version mismatch

​Saving and restoring browser state

​What sessions scope

​Common patterns

​Sessions in MCP

The default session

Targeting a named session

Daemon management per session

Daemon lifecycle and idle shutdown

Idle shutdown

Auto-restart on version mismatch

Saving and restoring browser state

What sessions scope

Common patterns

Sessions in MCP