feat(agent-browser, docs): overhaul CDP docs + add Windows mirrored networking guide

Bump agent-browser from pinned 0.11.1 to latest. Rewrite all CDP
documentation to cover Chrome 136+ --user-data-dir requirement,
Chrome 144+ checkbox method, and host.docker.internal for container
networking. Add new Windows Networking guide for WSL 2 mirrored mode
as the recommended Windows port-forwarding approach. Cross-reference
from before-you-install, accessing-services, troubleshooting, and
devcontainer-cli pages.

Author: AnExiledDev

container/.devcontainer/CHANGELOG.md

@@ -29,6 +29,17 @@
 - **Install order guaranteed** — oh-my-claude added to `overrideFeatureInstallOrder` in devcontainer.json.
 - **Documentation** — added Known Limitations section covering expected `omc doctor` failures, missing slash commands (upstream issue), and role agent filtering.
 
+### Agent Browser
+
+- **Version bumped to latest** — updated from pinned 0.11.1; picks up `--auto-connect` fixes and CDP improvements through v0.26.0
+- **Host Chrome CDP documentation overhauled** — corrected Chrome version requirements (136+ needs `--user-data-dir`, 144+ has `chrome://inspect` checkbox), documented `host.docker.internal` for container-to-host networking, fixed flag naming (`--auto-connect` not `--autoConnect`), added Windows PowerShell launch commands
+
+### Documentation
+
+- **New guide: Windows Networking** — comprehensive WSL 2 mirrored networking setup for Windows users; recommended approach for port forwarding, replacing `dbr` on Windows
+- **Cross-references added** — before-you-install, accessing-services, troubleshooting, and devcontainer-cli pages now link to the Windows networking guide
+- **Agent-browser CDP troubleshooting** — new troubleshooting section for host Chrome connection issues (localhost vs host.docker.internal, Chrome version requirements, port exposure)
+
 ## v2.2.1 — 2026-04-16
 
 ### Configuration

container/.devcontainer/features/agent-browser/README.md

@@ -48,18 +48,26 @@ agent-browser close
 
 ### Host Chrome Connection
 
-Connect to Chrome running on your host machine via CDP (Chrome DevTools Protocol):
+Connect to Chrome running on your host machine via CDP (Chrome DevTools Protocol). Useful when the container's bundled Chromium is insufficient (e.g., specific browser extensions or logged-in sessions needed).
 
-1. Start Chrome on host with remote debugging:
-   ```bash
-   chrome --remote-debugging-port=9222
-   # or on macOS:
-   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
-   ```
+**Chrome 144+** (recommended): No CLI launch needed. Enable remote debugging via a checkbox:
+1. Open `chrome://inspect/#remote-debugging` in Chrome
+2. Check "Enable remote debugging" — Chrome listens on port 9222 by default
 
-2. Connect from container:
-   ```bash
-   agent-browser connect 9222
-   ```
+**Chrome 136–143**: Chrome 136+ requires `--user-data-dir` alongside `--remote-debugging-port` or the flag is silently ignored:
 
-This is useful when the container's bundled Chromium is insufficient (e.g., specific browser extensions needed).
+```bash
+# Linux / macOS
+google-chrome --remote-debugging-port=9222 --user-data-dir="/tmp/chrome-debug"
+
+# Windows PowerShell
+& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-debug"
+```
+
+Connect from the container using `host.docker.internal` — not `localhost`, which refers to the container itself:
+
+```bash
+agent-browser connect host.docker.internal:9222
+```
+
+> **Security note:** CDP exposes the full browser session (cookies, storage, DOM) to anything that can reach the debug port. Use with caution on shared or networked machines.

container/.devcontainer/features/agent-browser/devcontainer-feature.json

@@ -8,7 +8,7 @@
 		"version": {
 			"type": "string",
 			"description": "agent-browser npm package version",
-			"default": "0.11.1"
+			"default": "latest"
 		},
 		"username": {
 			"type": "string",

container/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/agent-browser/SKILL.md

@@ -61,7 +61,7 @@ agent-browser close
 | `fill @eN "text"` | Type text into an input element | `agent-browser fill @e3 "hello"` |
 | `select @eN "value"` | Select an option from a dropdown | `agent-browser select @e5 "option1"` |
 | `cookie set "..."` | Set a cookie for authenticated sessions | `agent-browser cookie set "session=abc123; domain=.example.com"` |
-| `connect <port>` | Connect to host Chrome via CDP | `agent-browser connect 9222` |
+| `connect <host:port>` | Connect to host Chrome via CDP | `agent-browser connect host.docker.internal:9222` |
 | `close` | End the browser session | `agent-browser close` |
 
 > **Full details:** See `references/cli-reference.md` for complete command syntax, output formats, and all options.
@@ -121,25 +121,38 @@ agent-browser close
 
 ### Host Chrome Connection
 
-Connect to Chrome running on your host machine via CDP (Chrome DevTools Protocol). Useful when the container's bundled Chromium is insufficient (e.g., specific browser extensions needed):
+Connect to Chrome running on your host machine via CDP (Chrome DevTools Protocol). Useful when the container's bundled Chromium is insufficient (e.g., specific browser extensions or logged-in sessions needed).
 
-1. Start Chrome on host with remote debugging:
-   ```bash
-   chrome --remote-debugging-port=9222
-   ```
+**Chrome 144+** (recommended): No CLI launch needed. Enable remote debugging via a checkbox:
+1. Open `chrome://inspect/#remote-debugging` in Chrome
+2. Check "Enable remote debugging" — Chrome listens on port 9222 by default
 
-2. Connect from container:
-   ```bash
-   agent-browser connect 9222
-   ```
+**Chrome 136–143**: Chrome 136+ requires `--user-data-dir` alongside `--remote-debugging-port` or the flag is silently ignored:
+
+```bash
+# Linux / macOS
+google-chrome --remote-debugging-port=9222 --user-data-dir="/tmp/chrome-debug"
+
+# Windows PowerShell
+& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-debug"
+```
+
+Connect from the container — always use `host.docker.internal`, not `localhost`:
+
+```bash
+agent-browser connect host.docker.internal:9222
+```
+
+For Windows users, [mirrored networking](/start-here/windows-networking/) provides the smoothest experience for host Chrome CDP and general port forwarding.
 
 ---
 
 ## Ambiguity Policy
 
 These defaults apply when the user does not specify a preference. State the assumption when applying a default:
 
-- **Mode:** Always use headless mode (bundled Chromium) unless the user explicitly requests host Chrome connection
+- **Mode:** Always use headless mode (bundled Chromium) unless the user explicitly requests host Chrome connection. When host Chrome is requested, default to `host.docker.internal:9222` as the CDP endpoint.
+- **Networking:** When connecting to host Chrome from inside a container, always use `host.docker.internal` — never `localhost`
 - **Snapshot first:** Always run `snapshot` before interacting with elements — never guess element references
 - **Snapshot after:** Always run `snapshot` after interactions to verify results
 - **Close when done:** Always `close` the browser session when the task is complete

container/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/agent-browser/references/cli-reference.md

@@ -187,29 +187,38 @@ agent-browser cookie set "auth_token=xyz789; domain=.app.example.com; path=/; se
 Connects to a Chrome instance running on the host via Chrome DevTools Protocol (CDP).
 
 ```bash
-agent-browser connect <port>
+agent-browser connect <host:port>
 ```
 
 **Arguments:**
-- `<port>` — The remote debugging port Chrome is listening on
+- `<host:port>` — The CDP endpoint. Use `host.docker.internal:9222` when running inside a devcontainer.
 
 **Prerequisites:**
-Chrome must be started on the host with remote debugging enabled:
+Chrome must have remote debugging enabled on the host before connecting.
+
+**Chrome 144+** (recommended): No CLI launch needed. Enable via a checkbox:
+1. Open `chrome://inspect/#remote-debugging` in Chrome
+2. Check "Enable remote debugging" — Chrome listens on port 9222 by default
+
+**Chrome 136–143**: Chrome 136+ requires `--user-data-dir` alongside `--remote-debugging-port` or the flag is silently ignored:
 ```bash
-chrome --remote-debugging-port=9222
-# macOS:
-/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+# Linux / macOS
+google-chrome --remote-debugging-port=9222 --user-data-dir="/tmp/chrome-debug"
+
+# Windows PowerShell
+& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-debug"
 ```
 
 **Examples:**
 ```bash
-agent-browser connect 9222
+agent-browser connect host.docker.internal:9222
 ```
 
 **When to use:**
 - When the container's bundled Chromium is insufficient
 - When specific browser extensions are needed
 - When you need to observe browser behavior visually on the host
+- When you need access to a logged-in Chrome session (cookies, extensions, saved passwords)
 
 ---
 
@@ -237,6 +246,8 @@ agent-browser close
 | Element not found | Reference ID from stale snapshot | Run `snapshot` again to get current references |
 | Session already active | Tried to `open` without `close` | Run `close` first, then `open` |
 | Connection refused (CDP) | Host Chrome not running with debug port | Start Chrome with `--remote-debugging-port` |
+| Connection refused via localhost | Container cannot reach host on localhost | Use `host.docker.internal:9222` instead of `localhost:9222` |
+| Chrome ignores --remote-debugging-port | Chrome 136+ requires --user-data-dir | Add `--user-data-dir` flag when launching Chrome |
 
 **General recovery pattern:**
 ```bash

container/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/agent-browser/references/workflow-patterns.md

@@ -146,6 +146,59 @@ agent-browser close
 
 ---
 
+## Host Chrome CDP Session
+
+Connect to Chrome running on your host machine to use an existing logged-in session, extensions, or saved passwords. This is the recommended approach when the container's bundled Chromium cannot access what you need.
+
+### Prerequisites
+
+The user must enable Chrome remote debugging on their host machine before you can connect.
+
+**Chrome 144+** (recommended): No CLI launch needed. The user enables remote debugging via a checkbox:
+1. Open `chrome://inspect/#remote-debugging` in Chrome
+2. Check "Enable remote debugging"
+3. Chrome listens on port 9222 by default
+
+**Chrome 136–143**: Launch Chrome with explicit flags:
+
+```bash
+# Linux / macOS
+google-chrome --remote-debugging-port=9222 --user-data-dir="/tmp/chrome-debug"
+
+# Windows PowerShell
+& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-debug"
+```
+
+> **Why `--user-data-dir`?** Chrome 136+ silently ignores `--remote-debugging-port` unless a user data directory is also specified.
+
+### Workflow
+
+```bash
+# Connect to host Chrome from inside the container
+agent-browser connect host.docker.internal:9222
+
+# Snapshot to see what's currently open
+agent-browser snapshot
+
+# Navigate to a page (uses host Chrome's cookies and extensions)
+agent-browser open https://example.com/dashboard
+
+# Interact normally
+agent-browser snapshot
+agent-browser click @e3
+
+# Close the CDP connection (does not close Chrome on the host)
+agent-browser close
+```
+
+**Key points:**
+- Always use `host.docker.internal:9222` from inside a devcontainer — `localhost` refers to the container itself
+- The CDP connection gives you access to the host Chrome's full session: cookies, localStorage, extensions, saved passwords
+- Closing the agent-browser session does not close Chrome on the host
+- For Windows users needing broader port forwarding, see [Windows Mirrored Networking](/start-here/windows-networking/)
+
+---
+
 ## Screenshot Capture
 
 Take screenshots for visual verification at key points:

docs/astro.config.mjs

@@ -93,6 +93,10 @@ export default defineConfig({
 								label: "Before You Install",
 								slug: "start-here/before-you-install",
 							},
+							{
+								label: "Windows Networking",
+								slug: "start-here/windows-networking",
+							},
 							{
 								label: "Install in VS Code",
 								slug: "start-here/install-in-vscode",

docs/src/content/docs/reference/changelog.md

@@ -54,6 +54,8 @@ For minor and patch updates, you can usually just rebuild the container. Check t
 - **New feature: `hermes-agent`** — installs [Nous Research's Hermes Agent](https://hermes-agent.nousresearch.com/) CLI via the upstream `curl | bash` installer with `--skip-setup`. Hermes uses the plain `anthropic` / `openai` Python SDKs directly and supports any compatible provider (Anthropic, OpenAI, MiniMax, local models). Enabled by default; set `"version": "none"` in `devcontainer.json` to disable.
 - **Hermes persistence** — dedicated Docker named volume (`codeforge-hermes-config-${devcontainerId}`) for `~/.hermes/`, surviving container rebuilds so `hermes setup` is a one-time cost per devcontainer instance.
 - **No credential seeding** — the interactive `hermes setup` wizard is intentionally skipped during image build. Run `hermes setup` on first use to pick a provider and paste an API key (e.g. from `$MINIMAX_API_KEY`, which already has a slot in `.secrets.example`). Claude OAuth / Codex ChatGPT OAuth cannot be reused — Hermes needs its own provider auth.
+- **Install script now warns on unsupported `version` values** — Hermes upstream has not tagged releases yet, so anything other than `latest` or `none` silently installed HEAD of `main`. The installer now prints a clear WARNING when `version` is set to a semver or unrecognized value, making it obvious that the pin is not honored.
+- **Install script warns on volume-mount mismatch** — the Hermes config volume in `devcontainer.json` is pinned to `/home/vscode/.hermes`. If the feature's auto-detected user resolves to anything other than `vscode` (e.g. `node`, `codespace`, `root`), the installer now surfaces a WARNING that `hermes setup` state will not persist across rebuilds, instead of silently breaking.
 
 ### Configuration
 
@@ -74,6 +76,17 @@ For minor and patch updates, you can usually just rebuild the container. Check t
 - **Install order guaranteed** — oh-my-claude added to `overrideFeatureInstallOrder` in devcontainer.json.
 - **Documentation** — added Known Limitations section covering expected `omc doctor` failures, missing slash commands (upstream issue), and role agent filtering.
 
+### Agent Browser
+
+- **Version bumped to latest** — updated from pinned 0.11.1; picks up `--auto-connect` fixes and CDP improvements through v0.26.0
+- **Host Chrome CDP documentation overhauled** — corrected Chrome version requirements (136+ needs `--user-data-dir`, 144+ has `chrome://inspect` checkbox), documented `host.docker.internal` for container-to-host networking, fixed flag naming (`--auto-connect` not `--autoConnect`), added Windows PowerShell launch commands
+
+### Documentation
+
+- **New guide: Windows Networking** — comprehensive WSL 2 mirrored networking setup for Windows users; recommended approach for port forwarding, replacing `dbr` on Windows
+- **Cross-references added** — before-you-install, accessing-services, troubleshooting, and devcontainer-cli pages now link to the Windows networking guide
+- **Agent-browser CDP troubleshooting** — new troubleshooting section for host Chrome connection issues (localhost vs host.docker.internal, Chrome version requirements, port exposure)
+
 ## v2.2.1 — 2026-04-16
 
 ### Configuration

docs/src/content/docs/reference/troubleshooting.md

@@ -144,6 +144,45 @@ Check:
 2. Your distro is using WSL 2, not WSL 1.
 3. Docker Desktop was restarted after settings changes.
 
+## Agent-Browser Cannot Connect to Host Chrome
+
+Symptom: `agent-browser connect` fails with connection refused, timeout, or empty response.
+
+Check these in order:
+
+1. **Are you using `host.docker.internal`?** Inside a container, `localhost` refers to the container itself. Use `host.docker.internal:9222` to reach the host.
+
+2. **Is Chrome remote debugging actually enabled?**
+   - Chrome 144+: Open `chrome://inspect/#remote-debugging` and check that "Enable remote debugging" is checked.
+   - Chrome 136–143: Chrome must be launched with both `--remote-debugging-port=9222` **and** `--user-data-dir`. Chrome 136+ silently ignores the port flag without a user data directory.
+   - Verify from the host: `curl http://localhost:9222/json/version` should return JSON.
+
+3. **Is the port reachable from the container?**
+   ```bash
+   curl http://host.docker.internal:9222/json/version
+   ```
+   If this fails, the host is not reachable. Windows users should enable [mirrored networking](/start-here/windows-networking/).
+
+4. **Is another Chrome instance blocking the port?** Only one Chrome process can listen on a given debug port. Close other Chrome instances or use a different port.
+
+5. **Firewall blocking?** Windows Firewall may block incoming connections on port 9222. Add an inbound rule or temporarily disable the firewall to test.
+
+## Mirrored Networking Not Working
+
+Symptom: After enabling mirrored networking in `.wslconfig`, ports are still not accessible between host and container.
+
+Check these in order:
+
+1. **Did you restart WSL?** Changes to `.wslconfig` require `wsl --shutdown` from PowerShell, then restarting your WSL distribution or Docker Desktop.
+
+2. **Is mirrored mode actually active?** Run `wsl --status` from PowerShell and look for "Networking mode: Mirrored".
+
+3. **VPN conflict?** Cisco AnyConnect and some VPN clients break mirrored networking. Disconnect the VPN and test again. See the [Windows Networking guide](/start-here/windows-networking/#vpn-conflicts) for workarounds.
+
+4. **Windows update regression?** Microsoft occasionally ships updates that break mirrored mode. Check [WSL GitHub Issues](https://github.com/microsoft/WSL/issues) for known regressions. Revert to NAT mode as a temporary workaround.
+
+5. **Docker Desktop version?** Mirrored networking requires Docker Desktop 4.26.0 or later. Update Docker Desktop if you're on an older version.
+
 ## Reset Options
 
 Use the smallest reset that solves the problem:

docs/src/content/docs/start-here/before-you-install.md

@@ -58,6 +58,12 @@ CodeForge installs Claude Code inside the container, but you still need valid Cl
 
 Windows users need **WSL 2**. Docker Desktop's legacy Hyper-V path is not supported for this workflow.
 
+:::tip[Recommended: Enable mirrored networking]
+For the best experience on Windows, enable WSL 2 mirrored networking. It provides seamless port forwarding between your container and host — required for [host Chrome CDP connections](/start-here/windows-networking/#chrome-remote-debugging-setup) and eliminates the need for manual port forwarding tools.
+
+See the [Windows Networking guide](/start-here/windows-networking/) for setup instructions.
+:::
+
 ## Hardware Guidance
 
 | Resource | Minimum | Recommended |