docs/getting-started/windows-troubleshooting.mdx
Install microsandbox with:
irm https://github.com/superradcompany/microsandbox/releases/latest/download/install.ps1 | iex
The installer downloads the matching microsandbox-windows-aarch64.zip or microsandbox-windows-x86_64.zip release bundle, verifies it against checksums.sha256, installs into %USERPROFILE%\.microsandbox unless MSB_HOME is set, adds the install bin directory to the current user's PATH when needed, and runs msb doctor. If the doctor check reports that Windows Hypervisor Platform is missing, the installer offers to run msb doctor --fix, which opens an elevated PowerShell prompt.
Start with the doctor command:
msb doctor
If the only failure is Windows Hypervisor Platform setup, let msb open the elevated fix prompt:
msb doctor --fix
msb doctor --fix keeps the normal doctor command read-only. The fix path opens an elevated PowerShell window and runs the Windows optional-feature command without forcing an immediate reboot.
On Windows, the default runtime layout is:
| File | Default location |
|---|---|
msb.exe | %USERPROFILE%\.microsandbox\bin\msb.exe |
libkrunfw.dll | %USERPROFILE%\.microsandbox\lib\libkrunfw.dll |
If you are using a custom location, set one or both path overrides:
$env:MSB_PATH = "C:\path\to\msb.exe"
$env:MSB_LIBKRUNFW_PATH = "C:\path\to\libkrunfw.dll"
For installer-specific overrides, use:
| Environment variable | Effect |
|---|---|
MSB_HOME | Install root; defaults to %USERPROFILE%\.microsandbox |
MSB_INSTALL_VERSION | Release tag to install, such as v0.5.7 |
MSB_INSTALL_BASE_URL | Release asset base URL for mirrors or local testing |
MSB_INSTALL_NO_PATH=1 | Skip user PATH update |
MSB_INSTALL_NO_DOCTOR=1 | Skip the post-install doctor check |
MSB_INSTALL_NO_FIX=1 | Do not offer the elevated setup fix after a failed doctor check |
MSB_INSTALL_ASSUME_YES=1 | Run the setup fix without prompting if the doctor check fails |
You can check what command is being run with:
where.exe msb
If a Windows error mentions libkrunfw.so or libkrunfw.dylib, the process is using a stale Unix/macOS path from MSB_LIBKRUNFW_PATH, config.json, or an old install. Clear the override or point it at libkrunfw.dll.
microsandbox uses Windows Hypervisor Platform through libkrun. Enable the HypervisorPlatform optional feature from an elevated PowerShell:
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All -NoRestart
Reboot after enabling it. Windows can report the feature as installed while the hypervisor is still unavailable in the current boot session.
HypervisorPlatform is not the same feature as VirtualMachinePlatform. Docker Desktop and WSL2 commonly enable VirtualMachinePlatform, but microsandbox needs HypervisorPlatform because that exposes the WHP API used by libkrun.
Check the feature states with:
Get-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform
Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
If HypervisorPlatform is enabled but msb doctor still says the hypervisor is not active, check that virtualization is enabled in firmware/UEFI, reboot once, and verify that Windows is allowed to launch the hypervisor:
bcdedit /enum "{current}"
The hypervisorlaunchtype setting should be Auto or absent. To set it explicitly, run this from an elevated terminal and reboot:
bcdedit /set hypervisorlaunchtype auto
If you are building the Windows preview locally, use a Visual Studio developer environment that exposes MSVC, the Windows SDK, and Clang/LLVM to Cargo build scripts. A missing toolchain usually appears as failed to find tool "clang", missing link.exe, or missing WindowsSdkDir.
From PowerShell, the .ps1 developer shell can be blocked by execution policy. The batch launcher avoids that policy for one-off commands:
cmd /c "call ""C:\Program Files\Microsoft Visual Studio\18\Community\Common7\Tools\VsDevCmd.bat"" -arch=arm64 -host_arch=arm64 >nul && cargo build -p microsandbox-cli --target aarch64-pc-windows-msvc"
Adjust the Visual Studio path if you installed Build Tools, Enterprise, or a different Visual Studio version. Use -arch=amd64 with --target x86_64-pc-windows-msvc for x64 builds.
Published ports open a listening socket on the Windows host. Windows Defender Firewall can prompt the first time msb.exe opens that listener.
For local development, keep published ports bound to 127.0.0.1. Only allow private or public network access in the firewall prompt when you intentionally bind a sandbox service beyond loopback.
Windows Terminal, PowerShell, and cmd are supported for normal interactive attach flows. Run interactive commands from a real console, not from a redirected CI shell or background task, so msb can read console input, enter terminal mode, forward resize events, and restore the console when the session exits.
For a quick smoke test:
msb run --name win-shell --replace -t alpine -- /bin/sh
Then type echo hi, press Enter, and exit with exit.
There is no official microsandbox winget package yet. When a Windows installer exists, winget will be a distribution entry that downloads and runs that installer; winget does not replace the MSI/EXE installer itself.