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.

Key Features

Clean Base Distribution Cache

Every vagrant up starts with a pristine environment by maintaining a clean cache of base distributions. Prevents environment contamination and ensures reproducibility.

Native WSL2 Communication

Direct command execution through WSL instead of SSH overhead. No SSH server setup required, better performance, simpler configuration.

Full Provisioning Support

  • Shell provisioners
  • File provisioners
  • Ansible local provisioning
  • Standard Vagrant user setup for ecosystem compatibility

Snapshot Support

Point-in-time snapshots using WSL2’s export/import functionality:

vagrant snapshot save baseline
vagrant snapshot restore baseline
vagrant snapshot list

Docker & Systemd Integration

Automatic systemd enablement and Docker/Podman installation across 8 different Linux distributions (Ubuntu, Debian, AlmaLinux, Fedora, openSUSE, Kali).

Current Status

Version: v0.2.0 Status: Active Development Tested Distributions: 8 (Ubuntu, Debian, AlmaLinux, Fedora, openSUSE, Kali, and more)

Tech Stack

  • Ruby (Vagrant plugin architecture)
  • WSL2 (Windows Subsystem for Linux)
  • PowerShell (Integration testing)
  • Ansible (Provisioning)

Use Cases

Ideal For:

  • Enterprise Windows environments with VBS/Device Guard
  • Security-constrained environments where VMs are blocked
  • Resource-limited machines where VMs are too heavy
  • Teams needing consistent dev environments across Windows/Linux/macOS
  • Existing Vagrant workflows that need WSL2 support

Consider Alternatives When:

  • You have full OS choice (native Linux is better)
  • VirtualBox/VMware work fine (better isolation)
  • Heavy virtualization needs (multiple concurrent VMs)
  • Kernel development requiring hardware access

Quick Start 

# Install the plugin
vagrant plugin install vagrant-wsl2-provider

# Create a Vagrantfile
vagrant init ubuntu/jammy64
vagrant up --provider=wsl2

# Use it
vagrant ssh
vagrant snapshot save clean
vagrant destroy

Architecture Highlights

  • Clean cache system prevents dirty base distributions
  • Custom communicator for native WSL command execution
  • Vagrant user setup ensures provisioner compatibility
  • PowerShell integration tests validate real-world usage
  • Multi-distribution support with OS-specific provisioning playbooks

What’s Next

Future development focuses on:

  • VHD/VHDX mounting support
  • Network configuration improvements
  • Multi-machine support
  • Box conversion pipeline (VirtualBox → WSL2)