[FAQ] Voice input / install fails inside a WSL project — your WSL has no internet, not the plugin #297

TL;DR

If you opened a WSL project (a path like \wsl.localhost\...) and something that needs the network — installing the voice-input kit, updating the CLI, anything that hits npm or an API — just spins and fails, the cause is almost always WSL itself having no outbound internet, not the plugin.

One command settles it. In a WSL shell:

ping -c 3 8.8.8.8

• 0% packet loss → your WSL network is fine; this isn't your problem.
• 100% packet loss → WSL can't reach the internet. Read on.

Why this happens

When you open a project under \wsl.localhost\<distro>\..., the plugin runs its backend inside that WSL distro so it can see your files natively. That backend uses WSL's npm, node, and network — not Windows'. So if WSL is offline, the backend can't download the voice-input package, reach the transcription service, or call any API — even though Windows itself is perfectly online.

WSL 2's default NAT networking sometimes breaks on a given machine — a Hyper-V firewall rule, a VPN that doesn't route to the WSL adapter, or a stack that just wedged. Windows stays online and only WSL goes dark, which is the confusing part.

"But everything else works!"

Two traps:

1. The build works — because it runs on Windows (Git Bash + Windows pnpm/node), never touching WSL's network.
2. DNS resolves — getent hosts google.com returns an address, so it looks online. But resolving a name and actually routing a packet out are different things. That's why ping 8.8.8.8 (raw IP, no DNS, no TLS) is the honest test.

Confirm it

# Inside WSL — both should time out if WSL is offline:
curl -I --max-time 10 https://registry.npmjs.org
curl -I --max-time 10 https://api.anthropic.com

# From Windows (PowerShell) — should return 200 in well under a second:
curl.exe -I --max-time 10 https://registry.npmjs.org

Windows OK + WSL timing out = a WSL-only network problem, confirmed.

The fix: mirrored networking

Switch WSL from NAT to mirrored networking, where WSL shares the Windows host's network stack directly.

1. Create or edit C:\Users\<you>\.wslconfig:

   [wsl2]
   networkingMode=mirrored

2. Restart WSL from PowerShell:

   wsl --shutdown

3. Reopen WSL and re-test:

   ping -c 3 8.8.8.8                     # expect 0% packet loss
   curl -I https://registry.npmjs.org   # expect HTTP 200

Reopen your WSL project in the IDE and the network features work.

Requires a recent WSL (wsl --version >= 2.0; run wsl --update if needed).

Reverting

Mirrored mode is usually an improvement, but on rare setups it changes how localhost / port binding behaves. To revert: delete C:\Users\<you>\.wslconfig (or remove the networkingMode line) and run wsl --shutdown.

Still stuck?

If mirrored mode doesn't restore connectivity, the block is upstream of WSL — usually a corporate VPN or firewall. Check whether a VPN is active and whether it offers a "share with WSL" / split-tunnel option. As a workaround, open the project as a native Windows folder (C:\...) instead of a WSL path; the backend then runs on Windows and uses Windows' network.