wsl2-browser-setup

WSL2 Browser Setup

Use this skill for the complete WSL2 browser path, from browser availability through optional agent-browser setup.

Choose The Path

Need	Start with	Success signal
Interactive browsing or sign-in inside WSL	Native WSL Chrome	Normal HTTPS sites and the target sign-in page render in Linux Chrome.
A WSL tool must control Windows Chrome or Edge	Windows host browser bridge	WSL reaches the bridge's `/json/version` endpoint.
The requested client is `agent-browser`	First establish either browser path, then add the client layer	`agent-browser` opens or attaches to the chosen browser and returns a snapshot.

Read references/architecture.md when the correct path is unclear.

Native WSL Chrome

Run:

bash "${CODEX_HOME:-$HOME/.codex}/skills/wsl2-browser-setup/scripts/setup-native-wsl-chrome.sh"

The script verifies WSL2, installs Linux google-chrome when needed, writes the standard Windows .wslconfig networking settings, and reports whether a WSL restart is needed.

After a configuration change, have the human run wsl --shutdown, reopen WSL, and launch google-chrome. In chrome://settings/security, turn Use secure DNS fully off; OS default (when available) is not off. Reopen Chrome and verify a normal HTTPS site plus the real target or sign-in page.

Windows Host Browser Bridge

Run:

bash "${CODEX_HOME:-$HOME/.codex}/skills/wsl2-browser-setup/scripts/setup-windows-host-browser-bridge.sh"

The script finds Windows Edge or Chrome, launches it with remote debugging, requests Windows elevation for the port proxy and firewall rule, and waits for the CDP endpoint to become reachable from WSL2. It exposes a generic browser endpoint; client attachment is a separate step.

`agent-browser`

Only add this layer after native Chrome browsing or the Windows bridge is proven. Read references/agent-browser.md for runtime installation, the interactive upstream-skill step, native checks, bridge attachment, and the compatibility wrapper.

Safe Checks

Use the non-mutating checks first when diagnosing an existing setup:

bash "${CODEX_HOME:-$HOME/.codex}/skills/wsl2-browser-setup/scripts/setup-native-wsl-chrome.sh" --check-only
bash "${CODEX_HOME:-$HOME/.codex}/skills/wsl2-browser-setup/scripts/setup-windows-host-browser-bridge.sh" --check-only
bash "${CODEX_HOME:-$HOME/.codex}/skills/wsl2-browser-setup/scripts/setup-agent-browser-runtime.sh" --check-only

Deeper Guidance

Read references/troubleshooting.md when a browser launches but browsing, sign-in, bridge access, or agent-browser still fails.
Read references/dead-ends.md before attempting low-level DNS, firewall, package, or client workarounds.
Use scripts/setup-agent-browser-wsl2.sh only when the older one-shot Windows bridge flow is specifically useful.