Skip to main content
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:
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:

​
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.
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: 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

Log in once, save the session state, then restore it on every future run to skip the login flow:

​
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:
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.