Open-source project
sakai135/wsl-vpnkit avatar
sakai135/wsl-vpnkit

wsl-vpnkit's troubleshooting fix lives in a directory its own update procedure deletes

Provides network connectivity to WSL 2 when blocked by VPN

2,981 stars216 forksShellMIT

At a glance

What is it?
wsl-vpnkit restores networking inside WSL 2 when a Windows VPN blocks it, and the file is unusually well ordered: it tells you to test connectivity first, points at two Microsoft-native fixes, and only then describes itself as the fallback. The rough edges are elsewhere, in a copy-paste block that ends mid-command, and in a fix that edits a file inside a distro the documented upgrade path unregisters.
Who is it for?
wsl-vpnkit fits someone whose only problem is that a corporate VPN breaks WSL 2 networking and who cannot change Windows settings, and it is worth trying the built-in options first exactly as the file says, because mirrored mode solves it outright for many people.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 3 days ago.
What is it written in?
Mainly Shell, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • sakai135/wsl-vpnkit2,981 ★ · +16
Star history
Repository2026-09-242026-11-15
sakai135/wsl-vpnkit3k3k

16 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The file puts itself last, after two Microsoft fixes

The setup section opens by telling you not to set the tool up yet. It asks you to try pinging a public address inside WSL 2, and if that succeeds it sends you to Microsoft's own troubleshooting page instead. It then names the two built-in answers, mirrored networking mode and other configuration file options, and says those may resolve the issue as well. Only after all three does it state that the tool is intended for cases where those options do not work. That ordering is the most useful thing in the README and it is rare to see. It also means the tool is a fallback by the author's own account, so a reader who installs it first has skipped the cheaper test and may have solved the problem for free.

No administrator privileges means no admin on Windows, and root in the distro regardless

The opening sentence claims the tool requires no changes to Windows settings and no administrator privileges on the Windows host. That claim is accurate and narrower than it sounds. Read the two installation paths and every one of them needs root inside the distribution: the standalone route installs packages with a package manager, moves three binaries into a system binary directory with elevated privileges, writes a service unit to a system directory by piping through elevated output redirection, and then runs the tool itself under elevated privileges in the foreground. The systemd path does the same. So the guarantee is about the Windows side, which matters for locked-down corporate machines, and the Linux side is assumed to be yours to administer.

The standalone install block ends on the word sud

The Option B block is the one a reader is most likely to copy, and it is nine commands long before it breaks. It installs seven packages, downloads the distribution archive from the latest release, unpacks five named files out of it, deletes the archive, moves three of them into a system binary directory with elevated privileges, and runs the tool under elevated privileges. The next comment says that setting up the service is optional, the service file is moved into a system directory, and then the block ends with four letters:

sh
sud

That is a truncated command rather than a valid instruction, and it is the last line of the most copy-pasted block in the file. Everything before it is complete and correct; the reader has to work out the missing elevated command to finish the optional step themselves.

Option A runs the binaries from one distribution and the service from another

The first installation option imports a distribution archive as its own WSL distribution, which the file says has the advantage that it can start even when your existing distribution has no network at all. The binaries live at a fixed path inside that separate distribution, and it is run from there with a Windows-side invocation that names the distribution, changes to the app directory and executes the tool. To make it automatic, the service file is piped out of that separate distribution and into your working distribution's system directory with elevated privileges, then enabled and started there. So option A is a two-distribution arrangement: one holds files and is never where your work happens, the other runs the service. Both the archive layout and the cross-distribution copy are visible in the commands.

The documented fix edits a directory that the documented upgrade deletes

The troubleshooting section's answer to a proxy that will not execute a Windows binary is a two-step repair. First, write a binfmt registration into a system path by echoing a magic value and a target into a configuration file, then restart the service that owns it. Second, if host security policy only permits executables from certain directories, copy the proxy binary to a permitted location and point the tool's path variable at it. Both steps write into the separate distribution created by option A: the sed command that enables automount edits a configuration file inside that distribution. The update procedure for option A, however, unregisters the distribution and imports the new archive. Every upgrade therefore discards the automount change and any copy you made there, and the file does not say so.

Eight environment variables, two naming schemes and one borrowed hostname

Configuration is entirely environmental, with a table of eight variables and their defaults, and the pointer to the script itself for the complete list. A flag turns on debug output. One variable holds the host name used by the startup DNS diagnostic, and its default is a hostname that belongs to container tooling rather than to this project. Two variables give the paths to the two Windows executables, both resolved from the path. Two are for the gateway address and the interface whose default route gets restored, both auto-detected. One points at a proxy configuration file and additionally requires a YAML tool to be installed. The last decides who creates the tunnel interface: by default this tool creates and configures it, and set to zero a separate component creates it over DHCP instead.

Two of the five shipped files are build outputs, and the dockerignore has no Dockerfile

The archive that both installation paths consume contains five files under one directory: the script, its YAML example, a service unit, and two executables. Three of those are sitting at the repository root. The other two are not in the tree at all, so they are produced by the build script, which is one of four small pieces of tooling alongside an import helper, a directory holding the distribution definition, and a tests directory. That ratio is a reasonable shape for a project whose artefact is a distributable archive. One loose end in the tree listing is a docker ignore file with no container build file beside it, so whatever it excludes is now for a build process that no longer lives in the repository.

Editorial conclusion

wsl-vpnkit fits someone whose only problem is that a corporate VPN breaks WSL 2 networking and who cannot change Windows settings, and it is worth trying the built-in options first exactly as the file says, because mirrored mode solves it outright for many people. If you do install it, choose the standalone-script route rather than the separate distro, since the distro route requires a destructive unregister on every update and that is where the documented fix and the upgrade path collide. Check the minimum WSL release before starting, and keep a note of any environment variables you set, because the file gives you eight and no config file for them.

Frequently asked questions

what does wsl vpnkit do

It restores network connectivity inside WSL 2 when a Windows VPN blocks access, by running its own tunnelling and proxy components and restoring the default route. It requires no changes to Windows settings and no administrator privileges on the Windows host, though it does need root inside the distribution.

how to install wsl vpnkit

Two ways. Import the distribution archive as its own WSL distribution and start it, or install the standalone script in an existing distribution by installing seven packages, unpacking five files from the archive and moving three into a system binary directory. The file tells you to test connectivity and try mirrored mode first.

What version of WSL does wsl-vpnkit need?

Support for importing the .wsl archive format was added in WSL release 2.4.4, and that requirement appears in the troubleshooting section rather than in the setup instructions. Older releases need an import command with the destination folder and a version flag.

How do I update wsl-vpnkit?

By unregistering the wsl-vpnkit distribution and opening the new archive to import it. That destroys the distribution, so anything you changed inside it is lost, including the automount configuration change the troubleshooting section tells you to make there.

How do I configure wsl-vpnkit?

With environment variables only. Eight are documented with defaults, including a debug flag, a host name for the startup DNS check, paths for the two Windows executables, the gateway address, the tunnel interface, a proxy configuration file that additionally needs a YAML tool, and a switch that decides which component creates the tunnel interface.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. sakai135/wsl-vpnkit on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/sakai135-wsl-vpnkit.svg)](https://hysenlabs.com/projects/sakai135-wsl-vpnkit)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/sakai135-wsl-vpnkit.svg)](https://hysenlabs.com/projects/sakai135-wsl-vpnkit)

Was this useful?