Welcome to WSL Manager 👋

Name: wsl2-distro-manager
Author: bostrot

WSL Distro Manager on Windows, dark theme

_{Shown on Windows · the same app runs native VMs on macOS — expand See it on macOS below}

Preview with light theme (Windows)

WSL Distro Manager on Windows, light theme

🍎 See it on macOS — native Linux and macOS virtual machines through Apple's Virtualization framework (beta)

WSL Manager on macOS, dark theme

WSL Manager on macOS, light theme, with the AI assistant open

WSL Distro Manager is a free, open source GUI for the Windows Subsystem
for Linux — and, on macOS, for native Linux VMs. Install, copy, rename,
move, back up and delete WSL distros without memorising a single wsl.exe
flag — plus templates, saved command snippets, disk mounting, .wslconfig
editing, remote WSL over SSH, and an MCP server that lets AI agents drive
your WSL environment. On a Mac the very same app manages virtual machines
through Apple's Virtualization framework instead.

🚀 Features

Manage distros

Install from a built-in catalogue, or bring your own rootfs
Copy, rename, move to another drive, back up and delete instances
Compact virtual disks to reclaim space WSL never gives back
Supports Ubuntu, Debian, Alpine, Kali Linux, openSUSE, SLES and anything else WSL accepts

Get instances running faster

Use any Docker image as a distro — Docker itself is not required
Package a configured distro as a portable .wsl file that installs on any machine (templates are deprecated in favour of these)
Turnkey Linux and other LXC containers (experimental)
Snippets: keep your setup commands in the app and run them on any instance
Point the app at your own repository of rootfs images

Configure without editing files by hand

systemd, automount, default user, start command and start path per distro
Memory, processors, swap, networking mode, DNS and the rest of .wslconfig
Mount a physical disk or a VHD into WSL, with partition and filesystem control

Work the way you already do

Open Windows Terminal, VS Code or Explorer straight inside a distro
Manage WSL on a different Windows machine over SSH
Sync a distro between two machines on your network
Dark and light themes, available in nine languages

On macOS: native virtual machines (beta)

The same app manages VMs through Apple's Virtualization framework instead of WSL
Create Linux VMs from an installer ISO, a cloud image or an exported template
Create macOS guest VMs from a restore image (Apple Silicon)
Start, stop, clone, export/import and template VMs like distros
Run commands inside VMs over auto-provisioned SSH (cloud-init), from the GUI, the AI chat or MCP clients
Build with scripts/build_macos.sh — bundles the signed vmctl helper

Pro (one-time purchase: Microsoft Store on Windows, licence key from wslmanager.com/buy on macOS and for non-Store installs — never a subscription)

AI Workspace — run Hermes Agent, OpenClaw and Open WebUI in a dedicated, isolated WSL distro
AI assistant with tools — the built-in chat can actually operate your WSL: it lists and inspects distros, runs commands, edits config, creates snippets, mounts disks and packages distros through the same tools the MCP server exposes
Sandboxed AI — spin up a throwaway Ubuntu distro and give an AI chat access to only the inside of that sandbox
Task queue — hand the assistant a checklist and let it work through it, ticking items off as it goes
MCP server — expose WSL to Claude Desktop, Claude Code, opencode and other MCP clients
Web dashboard — manage everything from your phone or another computer: scan a QR code, get the whole app in a browser, optionally published beyond your network through a Cloudflare tunnel

The AI features run on credentials you bring — your own OpenAI-compatible
API key. No AI service is hosted or included, there is no quota, and no
requests pass through anyone else's servers. Pro unlocks the features in the
app; it does not buy AI credits. See Free vs Pro.

Why is there a paid tier at all? WSL Manager has been a one-person,
spare-time project since 2021, and every feature above — the free ones
included — was built in evenings and weekends. Managing your distros and VMs
is free and stays free, and the whole app stays open source. Pro is the AI
layer on top, and what it earns is what lets maintenance and new features
become planned, regular work instead of whatever time is left over. Buy it
once, keep it forever, and you are directly funding the next release.

🤖 AI assistant & MCP (Pro)

Everything in this section is part of Pro; the free app has none of it.

The AI assistant is an agent, not just a chat box: it is given the same tool
set the MCP server exposes, so when you ask "what distros do I have?" or "install
Ubuntu and set my default user" it calls real tools against your WSL rather than
guessing. Tool calls are shown inline as it works.

Set up the provider in Settings → Bring Your Own AI Key: any
OpenAI-compatible endpoint works (OpenAI, Azure, a LiteLLM proxy, Ollama, LM
Studio, …). Enter the base URL, key and model. The Load model list button
fills an autocomplete from the provider's /models, and Test connection
proves the credentials work before you open the chat.

Sandboxes (AI Workspace → Add sandbox distro) create a throwaway distro
from any catalog image (newest Ubuntu by default). Its chat is handed only the
sandbox_* tools, which are locked to that one distro — the model can run
anything inside the sandbox and can never see your Windows host or any other
distro. One honest caveat: the sandbox distro itself has normal outbound
internet access, like any WSL distro. Sandbox chats use the same docked panel
as the assistant (task queue included), their transcripts persist, and the
history button in the chat header switches between the assistant and any
sandbox session.

Task queue — open the Tasks section at the top of the chat, add items, and
press ▶. The assistant works through them with its tools and checks each off as
it finishes; you can keep adding tasks while it runs.

Connecting external AI clients (MCP)

Turn on Settings → MCP Server (Pro). It serves the MCP protocol at
http://127.0.0.1:59133/mcp, loopback-only, guarded by a bearer token shown in
the same panel. The tools cover the full lifecycle — create, import, configure,
run, package and (with a confirm flag) unregister distros, plus snippets, disk
mounting and persistent terminal sessions.

Claude Desktop — click Connect Claude Desktop in the MCP panel. It writes
the entry below into claude_desktop_config.json for you (needs Node.js);
restart Claude Desktop afterwards. To do it by hand, or for any other stdio MCP
client, bridge the HTTP endpoint with mcp-remote:

// claude_desktop_config.json  (%APPDATA%\Claude\)
{
  "mcpServers": {
    "wsl-manager": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://127.0.0.1:59133/mcp",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer <TOKEN FROM THE MCP PANEL>" }
    }
  }
}

Claude Code — same bridge, one command:

claude mcp add wsl-manager -- npx -y mcp-remote http://127.0.0.1:59133/mcp \
  --header "Authorization: Bearer <TOKEN>"

opencode — add it under mcp in your opencode.json (or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "wsl-manager": {
      "type": "local",
      "command": ["npx", "-y", "mcp-remote", "http://127.0.0.1:59133/mcp",
                  "--header", "Authorization: Bearer <TOKEN>"]
    }
  }
}

Any MCP client that speaks streamable HTTP can also point straight at the
endpoint with an Authorization: Bearer <TOKEN> header, skipping mcp-remote.
To reach it from another machine, enable the built-in Cloudflare tunnel
toggle in the same panel and use the public URL it prints.

📱 Web dashboard (Pro)

Turn on Settings → Web Dashboard (Pro) and the app serves a browser
dashboard on port 59134 for every device on your network — Windows and macOS
alike. Scan the QR code the panel shows with your phone (or copy the link) and
you get the whole app in a browser: start, stop, duplicate and delete instances,
run commands, open persistent terminal sessions, run your saved snippets, and
drive every other tool (import, export, packaging, .wslconfig, disks, VM
creation) through generated forms. It is the same tool set the AI assistant
and the MCP server use.

Access is guarded by a token that is part of the link (?token=…), so a
scanned QR code is all a device needs — and regenerating the token in the
panel revokes every link handed out so far. The dashboard binds to all
interfaces on purpose; flip Publish via Cloudflare Tunnel in the same panel
to get a temporary public HTTPS link (the QR code switches to it) when you need
it away from home. Once published, the token is the only thing protecting a
surface that can run commands, so share that link with care.

📦 Install

Microsoft Store

This app is available on the Microsoft Store.

macOS via Homebrew

brew tap bostrot/tap
brew install --cask wsl-manager

Apple silicon, macOS 11 or newer. The cask lives in bostrot/homebrew-tap; brew upgrade --cask wsl-manager picks up new releases.

Direct download

You can get this app with a direct download from the Releases page. Windows ships as a setup .exe, an .msix and a portable .zip; macOS as a .dmg.

Install via Winget

winget install Bostrot.WSLManager

Install via Scoop

scoop install extras/wsl2-distro-manager

Install via Chocolatey

This package is maintained by the community (@mikeee). It is not an official package.

choco install wsl2-distro-manager

Install a nightly build

The latest nightly build is available as an artifact in the "releaser" workflow or via this link.

⚙️ Build

Make sure flutter is installed:

flutter config --enable-windows-desktop
flutter upgrade

flutter build windows # build it
flutter run -d windows # run it

Author

👤 Eric Trenkel

Website: erictrenkel.com
GitHub: @bostrot
LinkedIn: @erictrenkel

👥 Contributors

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check the issues page.
You can also take a look at the contributing guide.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Not found what you were looking for? Check out the Wiki