Building Vagrant WSL2 Provider

Overview The Vagrant WSL2 Provider is a custom Vagrant plugin that brings the familiar Vagrant workflow to Windows Subsystem for Linux 2 (WSL2). It solves a common problem in enterprise Windows environments where traditional virtualization solutions (VirtualBox, VMware) are restricted or perform poorly due to security policies like VBS and Device Guard. The Problem Many developers working in corporate Windows environments face constraints: Virtualization-Based Security (VBS) makes VirtualBox unusable Device Guard/Credential Guard prevents traditional hypervisors from working Nested virtualization overhead causes severe performance penalties Security compliance requirements leave WSL2 as the only viable option This plugin bridges the gap between WSL2’s performance and Vagrant’s standardized development workflow. ...

Finishing What We Started The Vagrant WSL2 provider had a test/integration_old/todos/ folder with unimplemented tests. Two big ones: test_provisioners.ps1 and test_docker.ps1. Both just had TODO comments saying what they should test. We’d already migrated the working tests to Pester 5.x format. The old homegrown PowerShell scripts worked fine - they just weren’t using a framework. Now we needed to implement these missing tests using the same Pester patterns. Provisioners: One Monolith, Five Tests The examples/provisioners/ directory had one massive Vagrantfile testing shell, file, ansible, chef, and salt provisioners all at once. To test them individually, we needed to split them up. ...

The Testing Problem The vagrant-wsl2-provider had integration tests. They worked. They ran actual Vagrant commands and verified WSL2 distributions got created properly. But they were all custom PowerShell scripts with manual error handling, inconsistent output, and no real test framework. Here’s what a typical test looked like: try { Write-Host "Test: Starting VM..." -ForegroundColor Yellow vagrant up if ($LASTEXITCODE -ne 0) { throw "vagrant up failed" } Write-Host "[PASS] VM started" -ForegroundColor Green } catch { Write-Host "[FAIL] Test failed" -ForegroundColor Red exit 1 } It worked, but it was painful to maintain. Each test file had its own error handling, cleanup logic, and output formatting. And when something failed, you got a wall of red text with no clear indication of which specific assertion broke. ...

The Question Nobody Asked Which WSL distributions from the Windows Store actually work with the Vagrant WSL2 Provider? I didn’t know. And I realized - that’s a problem. The provider uses wsl --install --distribution <name> to download and install distributions directly from the Windows Store. But there are 22 distributions available, and I’d only tested Ubuntu-24.04. Time to find out what works and what doesn’t. Building the Test The goal was simple: iterate through every distribution from wsl -l -o, try to create a Vagrant environment with it, and document what fails. ...

“This Should Be Quick” Famous last words. After implementing basic networking support and learning about WSL2’s shared network architecture, I wanted to make it work reliably across multiple distributions. The plan: add integration tests, support more distros (Debian, Fedora, AlmaLinux, Kali, openSUSE), and document the limitations properly. What I thought would be a quick Sunday afternoon turned into a deep dive into systemd services, DNS resolution, and why background processes in SSH are surprisingly hard. ...

The Testing Journey So Far When I started this Vagrant WSL2 Provider project, I knew unit tests would be a waste of tokens. My requirements change daily. AI pair programming with Claude means rapid iteration, constant refactoring, and features that evolve as I discover what WSL2 can and can’t do. So I skipped unit tests entirely and went straight to integration tests. Simple PowerShell scripts that do the real thing: ...

Starting with High Hopes After adding Docker support, snapshots, and data disk management to the Vagrant WSL2 Provider, networking felt like the obvious next step. The goal was simple: make config.vm.network work just like it does in VirtualBox. config.vm.network "private_network", ip: "192.168.33.10" config.vm.network "forwarded_port", guest: 80, host: 8080 How hard could it be? Claude: Narrator: It was harder than expected. The VirtualBox Mental Model When you use VirtualBox, each VM gets its own network interfaces. Private networks create host-only adapters, each VM has its own IP, and everything just works. I assumed WSL2 would be similar - after all, it’s running on Hyper-V, right? ...

Three Times My colleague lost his VM three times. Not in a year - in the last few months we’ve been working together. Each time it happened, we’d shrug it off. That’s what Vagrant is for, right? Just run vagrant up and you’re back in business. The development environment is code - it’s reproducible. Except it wasn’t. All three times, he had uncommitted work on that VM. Database migrations half-done. Configuration files tweaked just right but not yet committed. Local test data. You know, the stuff you’re “definitely going to commit tomorrow.” ...

One Star and a Decision So the Vagrant WSL2 Provider got its first GitHub star. From someone I don’t know. Just one random person finding the project useful enough to click that button. That’s when I realized - okay, maybe it’s time to actually publish this properly. Until now, this was just a tool I built for myself and my team. We needed to migrate from VirtualBox to WSL2, and Vagrant’s existing providers didn’t cut it. So I built one. It worked. We used it. End of story. ...

Introduction Over the past few days, I’ve been working on adding Docker support to the vagrant-wsl2-provider plugin. This turned out to be more challenging than expected, but the journey taught me a lot about WSL2’s internals, systemd initialization, and multi-distribution package management. In this post, I’ll walk through the development process, the challenges we faced, and how we solved them to get Docker running on 8 different Linux distributions in WSL2 through Vagrant. ...