mcpField
W
wsl2-browser-setup

wsl2-browser-setup

github.com/arthurzakirovDevelopment1167 installsUpdated 2w ago
Repository

About wsl2-browser-setup

wsl2-browser-setup is a skill for setting up and diagnosing browser access in WSL2, for users who browse interactively or connect automation tools. It separates native Chrome, a Windows browser bridge, and the optional agent-browser layer.

Key features

  1. 01Set up native WSL Chrome
  2. 02Configure a Windows browser bridge
  3. 03Add the agent-browser layer
  4. 04Run non-mutating setup checks
  5. 05Consult troubleshooting guidance

Use cases

  1. 01Enable interactive browsing and sign-in in WSL
  2. 02Let WSL tools control Windows Chrome or Edge
  3. 03Diagnose existing browser and bridge setup
  4. 04Attach agent-browser to a verified browser

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/arthurzakirov/agentdesk --skill wsl2-browser-setup

After installing, type/wsl2-browser-setupin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
agent-browser.md
architecture.md
dead-ends.md
troubleshooting.md
scripts/
connect-windows-browser.sh
ensure-portproxy.ps1
ensure-wslconfig.ps1
invoke-portproxy-admin.ps1
launch-host-browser.ps1
setup-agent-browser-runtime.sh
setup-agent-browser-wsl2.sh
setup-native-wsl-chrome.sh
setup-windows-host-browser-bridge.sh

Details

From the project README

WSL2 Browser Setup

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

Choose The Path

NeedStart withSuccess signal
Interactive browsing or sign-in inside WSLNative WSL ChromeNormal HTTPS sites and the target sign-in page render in Linux Chrome.
A WSL tool must control Windows Chrome or EdgeWindows host browser bridgeWSL reaches the bridge's /json/version endpoint.
The requested client is agent-browserFirst establish either browser path, then add the client layeragent-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

Comments

Markdown supported