docs(browser): document WSL-to-Windows Chrome MCP bridge

website/docs/guides/use-mcp-with-hermes.md

@@ -109,6 +109,81 @@ mcp_servers:
 
 This is usually the best default for sensitive systems.
 
+## WSL2: bridge Hermes in WSL to Windows Chrome
+
+This is the practical setup when:
+
+- Hermes runs inside WSL2
+- the browser you want to control is your normal signed-in Chrome on Windows
+- `/browser connect` is awkward or unreliable from WSL
+
+In this setup, Hermes does **not** connect to Chrome directly. Instead:
+
+- Hermes runs in WSL
+- Hermes starts a local stdio MCP server
+- that MCP server is launched through Windows interop (`cmd.exe` or `powershell.exe`)
+- the MCP server attaches to your live Windows Chrome session
+
+Mental model:
+
+```text
+Hermes (WSL) -> MCP stdio bridge -> Windows Chrome
+```
+
+### Why this mode is useful
+
+- you keep your real Windows browser profile, cookies, and logins
+- Hermes stays in its supported Unix environment (WSL2)
+- browser control is exposed as MCP tools instead of relying on Hermes core browser transport
+
+### Recommended server
+
+Use `chrome-devtools-mcp`.
+
+If your Windows Chrome already has live remote debugging enabled from `chrome://inspect/#remote-debugging`, add it like this from WSL:
+
+```bash
+hermes mcp add chrome-devtools-win --command cmd.exe --args /c "npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics"
+```
+
+After saving the server:
+
+```bash
+hermes mcp test chrome-devtools-win
+```
+
+Then start a fresh Hermes session or run:
+
+```text
+/reload-mcp
+```
+
+### Typical prompt
+
+Once loaded, Hermes can use the MCP-prefixed browser tools directly. For example:
+
+```text
+调用 MCP 工具 mcp_chrome_devtools_win_list_pages，列出当前浏览器标签页。
+```
+
+### When `/browser connect` is the wrong tool
+
+If Hermes runs in WSL and Chrome runs on Windows, `/browser connect` may fail even though Chrome is open and debuggable.
+
+Common reasons:
+
+- WSL cannot reach the same host-local endpoint Chrome exposes to Windows tools
+- newer Chrome live-debugging flows are not the same as a classic `ws://localhost:9222`
+- the browser is easier to attach to from a Windows-side helper like `chrome-devtools-mcp`
+
+In those cases, keep `/browser connect` for same-environment setups and use MCP for WSL-to-Windows browser bridging.
+
+### Known pitfalls
+
+- Start Hermes from a Windows-mounted path like `/mnt/c/Users/<you>` or `/mnt/c/workspace/...` when using Windows stdio executables through MCP.
+- If you start Hermes from `/root` or `/home/...`, Windows may emit a `UNC` current-directory warning before the MCP server starts.
+- If `chrome-devtools-mcp --autoConnect` times out while enumerating pages, reduce background/frozen tabs in Chrome and retry.
+
 ### Example: blacklist dangerous actions
 
 ```yaml

website/docs/reference/faq.md

@@ -36,6 +36,24 @@ Set your provider with `hermes model` or by editing `~/.hermes/.env`. See the [E
 curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 ```
 
+### I run Hermes in WSL2. What's the best way to control my normal Windows Chrome?
+
+Prefer an MCP bridge over `/browser connect`.
+
+Recommended pattern:
+
+- run Hermes inside WSL2
+- keep using your normal signed-in Chrome on Windows
+- add `chrome-devtools-mcp` as an MCP server through `cmd.exe` or `powershell.exe`
+- let Hermes use the resulting MCP browser tools
+
+This is more reliable than trying to force Hermes core browser transport to attach directly across the WSL2/Windows boundary.
+
+See:
+
+- [Use MCP with Hermes](../guides/use-mcp-with-hermes.md#wsl2-bridge-hermes-in-wsl-to-windows-chrome)
+- [Browser Automation](../user-guide/features/browser.md#wsl2--windows-chrome-prefer-mcp-over-browser-connect)
+
 ### Does it work on Android / Termux?
 
 Yes — Hermes now has a tested Termux install path for Android phones.

website/docs/user-guide/features/browser.md

@@ -284,6 +284,22 @@ Then launch the Hermes CLI and run `/browser connect`.
 
 When connected via CDP, all browser tools (`browser_navigate`, `browser_click`, etc.) operate on your live Chrome instance instead of spinning up a cloud session.
 
+### WSL2 + Windows Chrome: prefer MCP over `/browser connect`
+
+If Hermes runs inside WSL2 but the Chrome window you want to control runs on the Windows host, `/browser connect` is often not the best path.
+
+Why:
+
+- `/browser connect` expects Hermes itself to reach a usable CDP endpoint
+- modern Chrome live-debugging sessions often expose a host-local endpoint that is not directly reachable from WSL the same way a classic `9222` port is
+- even when Windows Chrome is debuggable, the cleanest integration is often to let a Windows-side browser MCP server attach to Chrome and let Hermes talk to that MCP server
+
+For that setup, prefer `chrome-devtools-mcp` through Hermes MCP support.
+
+See the MCP guide for the practical setup:
+
+- [Use MCP with Hermes](../../guides/use-mcp-with-hermes.md#wsl2-bridge-hermes-in-wsl-to-windows-chrome)
+
 ### Local browser mode
 
 If you do **not** set any cloud credentials and don't use `/browser connect`, Hermes can still use the browser tools through a local Chromium install driven by `agent-browser`.