From 02cf7e6ffa589ab7bb44aa905825baf9b0f8ba2a Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 16 Jun 2026 13:12:52 +0000
Subject: [PATCH] docs: document daemon idle shutdown and new MCP agent
ergonomics
---
browser/concepts/mcp-server.mdx | 8 +++++---
browser/concepts/sessions.mdx | 29 +++++++++++++++++++++++++++++
2 files changed, 34 insertions(+), 3 deletions(-)
diff --git a/browser/concepts/mcp-server.mdx b/browser/concepts/mcp-server.mdx
index 5ad45c4..87cdb5a 100644
--- a/browser/concepts/mcp-server.mdx
+++ b/browser/concepts/mcp-server.mdx
@@ -69,7 +69,7 @@ The MCP server exposes 50+ tools grouped into logical categories. Call `tools/li
- `browser_click_ref`, `browser_fill_ref`, `browser_hover_ref`, `browser_click`, `browser_type`, `browser_press`, `browser_scroll`, `browser_drag`, `browser_select_option`, `browser_set_checked`, `browser_upload_file`, `browser_set_viewport` — precise element interaction using refs or CSS selectors.
+ `browser_click_ref`, `browser_fill_ref`, `browser_hover_ref`, `browser_click`, `browser_type`, `browser_press`, `browser_scroll`, `browser_drag`, `browser_select_option`, `browser_set_checked`, `browser_upload_file`, `browser_set_viewport` — precise element interaction using refs or CSS selectors. `browser_click_ref` accepts an optional `double_click: true` to dispatch a DOM `dblclick` instead of a single click, which some inline-edit and grid components require.
@@ -105,7 +105,7 @@ The MCP server exposes 50+ tools grouped into logical categories. Call `tools/li
- `browser_console`, `browser_network`, `browser_timeline`, `browser_debug_bundle`, `browser_session_summary`, `browser_check_injection` — inspect console logs, network traffic, the action timeline, and get a full debug bundle (screenshot + console + network + a11y) when an agent gets stuck.
+ `browser_console`, `browser_network`, `browser_timeline`, `browser_debug_bundle`, `browser_session_summary`, `browser_check_injection`, `browser_evaluate` (alias: `browser_eval`) — inspect console logs, network traffic, the action timeline, and get a full debug bundle (screenshot + console + network + a11y) when an agent gets stuck. `browser_evaluate` runs arbitrary JavaScript in the active page and safely returns the result; `browser_eval` is an identical short alias for agents that prefer the shorter name.
@@ -113,7 +113,7 @@ The MCP server exposes 50+ tools grouped into logical categories. Call `tools/li
- `browser_batch` — run a sequence of actions atomically in a single round-trip. Highly recommended for complex multi-step flows where partial state errors must be avoided. Supported step actions include `navigate`, `reload`, `click`, `type`, `select_option`, `key_press`, `press`, `wait_for`, `assert`, `click_ref`, `fill_ref`, `hover`, `hover_ref`, `scroll`, `snapshot`, and `diff`.
+ `browser_batch` — run a sequence of actions atomically in a single round-trip. Highly recommended for complex multi-step flows where partial state errors must be avoided. Supported step actions include `navigate`, `reload`, `click`, `type`, `select_option`, `key_press`, `press`, `wait_for`, `assert`, `click_ref` (supports `double_click: true`), `fill_ref`, `hover`, `hover_ref`, `scroll`, `snapshot`, `diff`, and `eval`.
@@ -334,6 +334,8 @@ Follow the `suggested_next_actions` on every call — they contain high-signal h
The MCP server is a thin, high-fidelity adapter over the same daemon client that the CLI uses. When your agent calls a tool, the server translates the JSON-RPC request directly to the daemon's internal API, attaches the standardized response envelope, and returns the result. You get automatic daemon lifecycle management, named session routing, and all the reliability guarantees of the CLI — plus the discoverability and structured envelopes that MCP provides.
+Daemons started on behalf of an MCP client follow the same idle-shutdown and version-mismatch auto-restart rules as the CLI. Tune `GSD_BROWSER_IDLE_SHUTDOWN_SECONDS` in your MCP client's `env` block to control how long an inactive agent session holds a Chrome process open. See [Daemon lifecycle and idle shutdown](/browser/concepts/sessions#daemon-lifecycle-and-idle-shutdown).
+
```
MCP Client (Cursor / Claude / VS Code)
│ JSON-RPC over stdio or HTTP
diff --git a/browser/concepts/sessions.mdx b/browser/concepts/sessions.mdx
index 988d721..a3cfa5e 100644
--- a/browser/concepts/sessions.mdx
+++ b/browser/concepts/sessions.mdx
@@ -43,6 +43,35 @@ gsd-browser --session checkout daemon health
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`:
+
+```bash
+# 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.