A minimal tool to declaratively create and manage WSL instances.
✨ A clean, declarative way to create WSL instances from a single YAML config, with a focus on clarity and repeatability.
wslforge does two things:
- Manages WSL instances — creates, configures, and optionally replaces instances from a YAML config.
- Automates instance setup — drives cloud-init for automation and templating.
Status: early/in-development. Some operations are still mock.
Optional: install the latest PowerShell via winget if you prefer a newer shell experience:
winget install --id Microsoft.PowerShell --source wingetWSL must be enabled on Windows before you can create instances. Run this once in an elevated PowerShell:
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-LinuxIf you run into issues, a WSL update may be needed:
wsl --update
Download the latest release binary from the Releases page 📦
Invoke-WebRequest -Uri https://github.com/mirai-toto/wslforge/releases/download/v1.21.0/wslforge.exe -OutFile wslforge.exeRun wslforge with no arguments and the interactive wizard will guide you through creating one instance. It covers the essentials — instance name, user, image, proxy, and cloud-init. For advanced options like file transfers, scripts, or multi-instance setups, use a config file. 🧙
.\wslforge.exeLooking for inspiration? Check out the ready-to-use examples.
Run it directly:
.\wslforge.exe --config config.yamlValidate your config without provisioning anything:
.\wslforge.exe --config config.yaml --validatePreview what will happen without making changes:
.\wslforge.exe --config config.yaml --dry-runWrite a detailed log to a file for troubleshooting:
.\wslforge.exe --config config.yaml --log-file wslforge.log| Flag | Description | Default |
|---|---|---|
--config |
Path to YAML config file (optional, defaults to config.yaml) |
config.yaml |
--dry-run |
Show what would be done without changes | false |
--validate |
Parse and validate the config file without provisioning | false |
--debug |
Enable extra debug output and write artifacts | false |
--log-file |
Write debug logs with timestamps to a file | — |
--force, -f |
Skip confirmation prompt and proceed automatically | false |
--print-example-config |
Print a minimal example config and exit | false |
--generate-completion |
Print a shell completion script and exit (powershell) |
— |
If --config is omitted and no config.yaml is found in the current directory, an interactive wizard launches to build a config on the fly.
The --debug flag writes the rendered cloud-init user-data to the current directory as cloud-init.<name>.user-data.
.\wslforge.exe --print-example-configGenerate and install a completion script for your shell:
# PowerShell — load for the current session only
.\wslforge.exe --generate-completion powershell | Out-String | Invoke-Expression
# To persist across sessions, save to a separate file and dot-source it from your profile
.\wslforge.exe --generate-completion powershell | Out-File "$HOME\wslforge_completion.ps1"
Add-Content $PROFILE ". `"$HOME\wslforge_completion.ps1`""- 🧩 Configuration — config schema, all fields, proxy, cloud-init, image sources, file transfers, post-create scripts
- 📋 Examples — ready-to-use configs for common setups
- 🧱 Architecture — how the CLI, provisioner, and engine fit together
- 💡 Rationale — why this project exists and the design decisions behind it
- 🛠 Development — building locally, git hooks, and running CI checks
MIT — see LICENSE.
Open an issue at GitHub Issues with your logs and config details if possible.
- Cloud-init WSL datasource for user-data behavior and file locations
- WSL documentation for setup, commands, and troubleshooting