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.
But that star made me think - if someone else is interested, maybe I should make it actually installable. Not just “clone the repo and build it yourself” but proper vagrant plugin install support.
The Publishing Process
I’ve never published a Vagrant plugin before. Hell, I’ve never published anything to RubyGems.org. So naturally, I asked Claude what the process looks like.
Turns out it’s surprisingly simple:
- Make sure your gemspec is correct
- Update the CHANGELOG
- Register on RubyGems.org
- Build the gem
- Push it
No approval process. No waiting. No HashiCorp permission needed. Just build and push.
Gemspec Cleanup
The gemspec needed a few tweaks. Nothing major - just adding required_ruby_version to avoid warnings:
spec.required_ruby_version = ">= 2.7.0"
Vagrant 2.2+ needs Ruby 2.7+ anyway, so this is safe.
The metadata was already good:
spec.metadata["allowed_push_host"] = "https://rubygems.org"
spec.metadata["homepage_uri"] = spec.homepage
spec.metadata["source_code_uri"] = spec.homepage
spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
CHANGELOG for v0.2.0
Updated the CHANGELOG to move everything from [Unreleased] to [0.2.0]:
## [0.2.0] - 2025-10-30
### Added
- Full snapshot support (save, restore, list, delete)
- Support for `vagrant snapshot push/pop` commands
- `vagrant ssh -c` command execution support
- PowerShell-based integration test suite
- Docker support and systemd enablement on distribution start
- Comprehensive testing for various Linux distributions
- wsl.conf configuration support
### Features
- Snapshots stored as `.tar` files
- Complete distribution state preservation and restoration
- Direct command execution via `vagrant ssh -c`
- Automated integration tests
- Docker-in-WSL2 workflows with systemd support
This is a solid release. Snapshot support was the big one - being able to save/restore WSL2 distribution state is huge for development workflows.
RubyGems.org Registration
Went to rubygems.org, signed up. Email, password, done.
And yes, I typo’d my username. Classic. But turns out it doesn’t matter - gem ownership is tied to email, not username. You can rename your profile anytime.
The Push
gem build vagrant-wsl2-provider.gemspec
Got some warnings about URIs being the same (not a problem) and the Ruby version constraint (already fixed). Build succeeded:
Successfully built RubyGem
Name: vagrant-wsl2-provider
Version: 0.2.0
Then the moment of truth:
gem push vagrant-wsl2-provider-0.2.0.gem
First time, so it asked for credentials. Email and password. Then:
Pushing gem to https://rubygems.org...
Successfully registered gem: vagrant-wsl2-provider (0.2.0)
Done. Published. Live.
Now anyone can run:
vagrant plugin install vagrant-wsl2-provider
And it just works.
Adding a Roadmap
While we were at it, we added a roadmap to the README. People should know what’s coming:
v0.3 - Data Disk Support
- Mount VirtualBox data disks in WSL2
- VHD/VMDK to WSL2 format conversion
- Support for development backup workflows
This is the next big thing. Our team has development environments backed up as VirtualBox data disks. We need a way to convert and mount those in WSL2. That’s the migration path.
v0.4 - Legacy Distribution Support
- Non-interactive setup for Ubuntu 20.04, 22.04
- Support for Oracle Linux distributions
Some WSL distributions use the legacy registration system and require interactive setup. Need to work around that.
v0.5 - Network Configuration
- Fixed network support for multiple WSL2 distributions
- Network isolation and custom IP configuration
WSL2’s dynamic networking is… interesting. Multiple distributions with predictable networking would be nice.
What This Means
The plugin is now officially public and installable. Version 0.2.0 is solid - snapshot support, SSH command execution, Docker/systemd integration, and comprehensive testing across multiple Linux distributions.
It went from “internal tool” to “published open-source project” in about an hour. RubyGems makes it stupidly easy to publish.
Next up: v0.3 and that VirtualBox data disk conversion. That’s the real migration blocker for our team.
But for now - we’re live. The plugin is out there. And hopefully that one star becomes a few more.
Try It
If you’re on Windows with WSL2 and use Vagrant:
vagrant plugin install vagrant-wsl2-provider
Then create a Vagrantfile:
Vagrant.configure("2") do |config|
config.vm.box = "Ubuntu-24.04"
config.vm.provider "wsl2" do |wsl|
wsl.distribution_name = "my-dev-env"
end
end
Run:
vagrant up --provider=wsl2
vagrant snapshot save clean-install
vagrant ssh
And you’ve got a WSL2-based Vagrant environment with snapshot support.
Top comments (0)