Fix WSL Browser Agent & Chrome DevTools Connection
This skill diagnoses and resolves connection failures between Antigravity's Linux-based browser subagent (or chrome-devtools MCP server) running inside Windows Subsystem for Linux (WSL2) and Google Chrome running on the Windows host.
Table of Contents
- When to Use
- 1. Check If Fixed Upstream First (Future-Proofing)
- 2. Root Cause Architecture: The Four WSL2 Boundaries
- 3. Diagnostic & Remediation Procedure
- 4. Optional Shell Startup Persistence (Zero Assumptions About
~/.bashrc)
When to Use
Activate this skill whenever:
- The
browsersubagent orchrome-devtoolsMCP fails with:Could not connect to Chrome (Could not find DevToolsActivePort for chrome at /home/<user>/.config/google-chrome/DevToolsActivePort) - A symlink at
~/.config/google-chrome/DevToolsActivePortfails with:Cause: ELOOP: too many symbolic links encountered - Port
9222is unreachable from inside WSL2 even though Chrome is running on Windows.
1. Check If Fixed Upstream First (Future-Proofing)
Google may update Antigravity or chrome-devtools-mcp in a future release to natively detect and bridge to Windows Chrome from WSL2 (for example, by automatically scanning /mnt/c/Users/*/AppData/Local/Google/Chrome/User Data/DevToolsActivePort or establishing a built-in host channel).
Before applying any workarounds:
- Verify Environment: Confirm the session is actually running inside WSL2 (
grep -qi microsoft /proc/version). If not on WSL2, follow standard Linux/macOS Chrome DevTools troubleshooting instead. - Check Upstream Behaviour:
- If the
browsersubagent orchrome-devtoolsMCP (list_pages) succeeds without~/.config/google-chrome/DevToolsActivePortbeing manually synced, stop immediately — Google has resolved the WSL discovery gap upstream. - If the user previously added a custom
DevToolsActivePortsync snippet to their shell configuration and upstream now handles discovery natively, inform the user and offer to remove the obsolete workaround.
- If the
2. Root Cause Architecture: The Four WSL2 Boundaries
When the problem is present, it is caused by up to four distinct boundaries between WSL2 and Windows Chrome:
Boundary 1: Network Isolation (NAT vs mirrored)
By default, WSL2 uses NAT networking on a separate virtual subnet, preventing Linux processes inside WSL2 from reaching Windows 127.0.0.1:9222. Enabling networkingMode=mirrored in %USERPROFILE%\.wslconfig shares localhost directly between Windows and WSL2.
Boundary 2: Chrome 144+ --autoConnect & DevToolsActivePort Path Mismatch
Modern Chrome (144+) and chrome-devtools-mcp --autoConnect do not blindly probe http://127.0.0.1:9222/json/version. Instead, when remote debugging is enabled (chrome://inspect/#remote-debugging), Chrome writes a two-line file named DevToolsActivePort containing the active port and a session-specific WebSocket UUID path:
9222
/devtools/browser/d7936b9a-4469-4faf-97ae-f700b05e5b77
- Windows Chrome writes to:
/mnt/c/Users/<win-user>/AppData/Local/Google/Chrome/User Data/DevToolsActivePort - WSL2
browseragent reads from:~/.config/google-chrome/DevToolsActivePort
Boundary 3: The Sandbox Symlink Trap (ELOOP)
Do NOT create a symbolic link (ln -s) from ~/.config/google-chrome/DevToolsActivePort to /mnt/c/.... Because the Antigravity browser subagent runs inside a sandboxed Linux container where /mnt/c (drvfs) is not mounted or cannot be traversed, symlinks fail with ELOOP: too many symbolic links encountered. The file must be copied as a regular file (cp -f).
Boundary 4: The Legacy socat TCP-LISTEN:9222 Port-Forwarding Trap
Older WSL2 setups often include a background socat daemon in ~/.bashrc that forwards 127.0.0.1:9222 to the Windows Hyper-V NAT gateway IP ($WIN_IP:9222, e.g. 172.19.160.1:9222):
socat TCP-LISTEN:9222,fork,reuseaddr TCP:$WIN_IP:9222 &> /dev/null &
This fails in both networking modes and must be removed:
- In
NATmode: Windows Chrome (chrome://inspect/#remote-debugging) strictly binds to127.0.0.1:9222and[::1]:9222on the Windows loopback interface (netstat.exe -ano | grep 9222) and refuses connections on the172.x.x.xHyper-V interface. However, becausesocatlistens on*:9222in WSL2, TCP connections to127.0.0.1:9222appear to connect and then silently hang until timeout. - In
mirroredmode:socatsquats on port9222inside WSL2 and hijacks traffic away from the native mirrored loopback interface.
3. Diagnostic & Remediation Procedure
Step 1: Run the Diagnostic & Sync Script
Execute the bundled sync_devtools_port.sh helper script unsandboxed (BypassSandbox: true, as it accesses /mnt/c/ and ~/.config/google-chrome/):
bash ~/.gemini/config/skills/fix-wsl-browser-agent/scripts/sync_devtools_port.sh
The script automatically:
- Verifies WSL2 is active.
- Detects and terminates any legacy
socat TCP-LISTEN:9222processes hijacking port 9222 (and warns if~/.bashrcstill contains the legacysocatsnippet). - Locates the active Windows Chrome
DevToolsActivePortfile under/mnt/c/Users/*/AppData/Local/Google/Chrome/User Data/DevToolsActivePort. - Removes any broken symlink at
~/.config/google-chrome/DevToolsActivePortand copies the file as a regular file. - Verifies that
127.0.0.1:<port>is reachable from WSL2, and if unreachable, deterministically checks Windowsnetstat.exe, WSL2 routing mode (NATvsmirrored), and%USERPROFILE%\.wslconfigto pinpoint the exact fix.
Step 2: Handle Any Reported Layer Failures
Depending on the script output:
- If the Windows
DevToolsActivePortfile is missing: Instruct the user to open Google Chrome on Windows, navigate tochrome://inspect/#remote-debugging, and tick the checkbox to enable remote debugging. Once enabled, re-runsync_devtools_port.sh. - If
127.0.0.1:<port>is unreachable from WSL2:- Check the script's diagnostic output: it automatically queries Windows
netstat.exeand WSL's routing table. - If Windows Chrome is not listening on
127.0.0.1:<port>, ask the user to ensure Chrome is open withchrome://inspect/#remote-debuggingenabled. - If Windows Chrome is listening on
127.0.0.1:<port>on Windows, but WSL2 is running inNATmode (default via 172.x.x.x), ensure%USERPROFILE%\.wslconfigcontains:
Then instruct the user to run[wsl2] networkingMode=mirroredwsl --shutdownfrom Windows PowerShell/Terminal and reopen their session when convenient.
- Check the script's diagnostic output: it automatically queries Windows
Step 3: Retry the Browser Subagent
Once ~/.config/google-chrome/DevToolsActivePort is synced and the port is reachable:
- Message the existing
browsersubagent (or invoke a new one / calllist_pages) to retry the operation. - Remind the user that Chrome on Windows may display a one-time "Allow remote debugging?" confirmation prompt in the browser window — they should click Allow.
4. Optional Shell Startup Persistence (Zero Assumptions About ~/.bashrc)
Because Windows Chrome generates a new WebSocket UUID in DevToolsActivePort every time the browser is restarted, the copied file in ~/.config/google-chrome/DevToolsActivePort will become stale after a Chrome restart.
If the user wants this synced automatically on shell startup:
[!IMPORTANT] Make Zero Assumptions About
~/.bashrc: Never assume the user's~/.bashrcfollows a specific template, usesoh-my-bash, or contains an Antigravity fast-exit guard.~/.bashrcconfigurations vary across machines and change over time.
- Always Read
~/.bashrcFirst: Inspect the user's actual~/.bashrcbefore proposing or making any edits. - Determine Placement Dynamically:
- Check whether
~/.bashrccontains any earlyreturnstatements (such as non-interactive guards likecase $- in *i*) ;; *) return;; esac,[ -z "$PS1" ] && return, or agent fast-exit guards). - If any early
returnguards exist, place the sync block above the earliestreturnso it executes for both interactive shells and non-interactive subshells. - If no early
returnguards exist, place it cleanly near the top of~/.bashrc.
- Check whether
- Use a Self-Contained, Silent Snippet:
Either call the helper script or inline this self-contained check (which silently no-ops if Chrome is not installed or if Google later removes
DevToolsActivePort):
# Sync Windows Chrome DevToolsActivePort into WSL2 (if present and changed)
for _win_dtp in /mnt/c/Users/*/AppData/Local/Google/Chrome/"User Data"/DevToolsActivePort; do
if [ -f "$_win_dtp" ]; then
mkdir -p "$HOME/.config/google-chrome"
[ -L "$HOME/.config/google-chrome/DevToolsActivePort" ] && rm -f "$HOME/.config/google-chrome/DevToolsActivePort"
cmp -s "$_win_dtp" "$HOME/.config/google-chrome/DevToolsActivePort" || cp -f "$_win_dtp" "$HOME/.config/google-chrome/DevToolsActivePort" 2>/dev/null
break
fi
done
unset _win_dtp