Skip to content

v2 macOS

Jump to bottom Edit New page
Eric Trenkel edited this page Sep 4, 2026 · 1 revision

WSL Manager on macOS

BETA. The macOS build is new. It is the same app, but there is no WSL on a Mac: the instances it manages are native Linux (and, on Apple Silicon, macOS) virtual machines running through Apple's Virtualization framework. Please report anything odd.

WSL Manager on macOS, dark theme

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

Requirements

  • Apple Silicon Mac. The bundled vmctl helper is built for arm64 and every catalogue image is an arm64 build. Intel Macs are not supported by this build.
  • macOS 13 (Ventura) or newer — the version the virtualization helper targets. macOS guest VMs need Apple Silicon and a recent macOS.
  • Enough disk space: VM disks default to a sparse image, but installer ISOs and cloud images are cached locally, and the AI Workspace VM alone downloads about 3 GB.

Install

  1. Download wsl2-distro-manager-v<version>-macos.dmg (or the .zip) from the Releases page. Nightly builds are attached to the macOS workflow as the macos-app artifact.
  2. Open the DMG and drag WSL Manager to Applications.
  3. First launch: the beta builds are ad-hoc signed and not notarized, so Gatekeeper refuses a double-click. Right-click (Control-click) the app → Open → Open once; afterwards it opens normally.

The app bundles vmctl, the small helper that talks to Virtualization.framework, inside its own bundle — nothing else has to be installed.

What is the same, what is different

Windows macOS
What a row on Home is a WSL distro a Linux or macOS VM, with its guest IP and real disk usage
Create rootfs catalogue, Docker image, Turnkey, local rootfs, VHDX installer ISO catalogue, cloud image catalogue, local ISO/disk image, macOS restore image
Terminal Windows Terminal into the distro Terminal.app on the VM's serial console, or SSH once a cloud image is up
Explorer / Finder opens the distro's filesystem attaches the VM's disk image and opens whatever mounts (Linux ext4 disks can't be read by macOS — the VM folder opens instead)
Templates deprecated in favour of .wsl packages first-class: saved VM disk images
Distro packages, Mount disk, .wslconfig, Sync, Turnkey, Docker images ✅ — (WSL-only, hidden)
Snippets, service recipes, community snippets ✅ ✅ (run over SSH inside the VM)
Remote WSL over SSH ✅ ✅ — a configured remote Windows host takes over the whole app, see Remote WSL
AI assistant, sandboxes, task queue ✅ (Pro) ✅ (Pro) — tools operate on VMs
AI Workspace dedicated ai-workspace WSL distro dedicated ai-workspace Linux VM with guided setup
MCP server MCP Server (WSL API) MCP Server (VM API) — same endpoint, plus the vm_* tools
Pro Microsoft Store purchase licence key from wslmanager.com

Creating a Linux VM

Add an instance opens the Create VM page. Set a name, processors, memory and disk size, then choose what the VM boots from — a VM with neither has nothing to boot and stops immediately, so the page refuses to create one:

  • Cloud image — ready to use (recommended). Boots straight into a system that is reachable over SSH, no manual install: the app seeds the disk with a cloud-init configuration that creates the user, installs an SSH key and grows the root partition. Catalogue entries:

    • Debian 13 (cloud image) — the genericcloud arm64 raw image
    • Alpine Linux (cloud image) — the uefi-cloudinit qcow2 image, converted on the fly; boots and answers SSH in about 15 seconds

    A local .raw, .img or .qcow2 file works too, e.g. an exported template.

  • Installer ISO — manual install. The VM window walks you through a normal installation; the guest is not reachable from the app until the install is finished. Catalogue entries resolve against the vendor's own listing so point releases never go stale: Alpine Linux (virt / standard), Ubuntu Server LTS, Debian (netinst), Fedora Server (netinst). A local ISO path works as well.

Downloads show progress, can be cancelled, are cached under the app's data folder and are verified against the announced size, so a partial file never poisons the cache.

Optionally pick a service recipe to preinstall (Postgres, Redis, MinIO, …) — it installs the first time the VM runs. See Features → Service recipes.

Creating a macOS VM

Choose macOS as the guest operating system (Apple Silicon only). Either point the page at a local .ipsw restore image or leave the field empty to download the latest supported version automatically (several GB). Installation takes many minutes; the VM then opens with its display.

Working with a VM

Every row shows the VM's state, its IP address while running (read from its DHCP lease) and actual disk blocks used over the allocated size. The row buttons:

  • ▶ / ⏹ — start (headless) or stop.
  • Open serial console in Terminal — starts the VM headless if needed and bridges Terminal.app to its virtio serial port. Press Ctrl-] to detach. This works even for a VM with no SSH and no window.
  • Show screen — summons the VM's display window on demand; a headless VM can grow a screen later and a closed window can come back.
  • Open with Finder — attaches the raw disk image via hdiutil and opens whatever mounts. A running VM never attaches (a mounted disk under a running guest means data corruption), and the app refuses to start a VM whose disk is still mounted in Finder — eject it first.
  • Copy, Rename, Save as template, Run a snippet, Delete — as on Windows.

Commands from snippets, recipes, the AI assistant and MCP clients run inside the VM over SSH, which cloud images provision automatically. A VM created from an installer ISO needs a running SSH server and a reachable IP before those work.

Templates, export and import

Save as template stores the VM's disk image; Templates stamps new VMs from it. A template image can also be chosen directly as the cloud image of a new VM, and MCP clients can do the same with vm_import_image.

Pro on macOS

There is no Store install to detect on a Mac, so Pro is a licence key:

  1. Buy on wslmanager.com (one-time; see Free vs Pro for plans and prices).
  2. The success page hands the key to the app through a wslmanager://license?key=… link — click Activate in WSL Manager and Pro is on. If the link doesn't open the app, paste the key under License → Already have a licence key?
  3. The key is validated once online, rechecked every 14 days, and keeps working for 60 days without a connection. It can be cleared from the License page.

Debug builds you compile yourself run as Pro.

Building from source

Needs a full Xcode install and Flutter (the CI pin is 3.41.6):

flutter config --enable-macos-desktop
flutter pub get
./scripts/build_macos.sh          # builds + signs vmctl, then the app, and bundles them

scripts/build_macos.sh also installs a copy of vmctl under ~/Library/Application Support/WSLManager/bin/ so that flutter run -d macos finds it during development. Set CODESIGN_IDENTITY to sign with a real Developer ID instead of ad-hoc. scripts/test_vmctl.sh runs the helper's Swift tests and works with the Command Line Tools alone.

Troubleshooting

"The list of virtual machines could not be read" / vmctl could not be reached In a release build the helper ships inside the app bundle; in a development run execute scripts/build_macos.sh once to install it (or point VMCTL_PATH at a build).

The VM stopped right after starting Most likely nothing bootable was found. Attach an installer ISO or create the VM from a cloud image.

The app won't open ("cannot be opened because the developer cannot be verified") Expected for the ad-hoc-signed beta: right-click → Open once.

A VM has no IP / SSH-based actions fail Only cloud images provision SSH automatically. For an ISO-installed guest, install and start sshd inside it; the IP appears in the row once the guest has a DHCP lease. Use the serial console to get in meanwhile.

Finder shows the VM folder instead of the disk macOS cannot read ext4; the folder is the fallback. Use SSH or the console to reach files inside a Linux guest.

Add a custom footer
Add a custom sidebar

Clone this wiki locally