docs/troubleshooting/windows.mdx
Windows support is currently in preview. Windows 11 is the tested path, and local sandboxes require Windows Hypervisor Platform.
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 free of host-configuration changes. The normal check may create and immediately remove a small clone-capability probe inside MSB_HOME. The fix path opens an elevated PowerShell window and applies the supported host setup change.
microsandbox uses Windows Hypervisor Platform through libkrun. If you prefer to enable it manually, run this from an elevated PowerShell and reboot after it completes:
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All -NoRestart
HypervisorPlatform is separate from VirtualMachinePlatform, which Docker Desktop and WSL2 commonly enable. microsandbox needs HypervisorPlatform because that exposes the WHP API used by libkrun.
You can check the feature state with:
Get-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform
If the feature is enabled but msb doctor still reports that the hypervisor is unavailable, confirm that virtualization is enabled in firmware/UEFI, then reboot once.
The default Windows runtime root is %USERPROFILE%\.microsandbox. The CLI binary lives under bin\msb.exe, and the runtime library lives under lib\libkrunfw.dll.
If Windows is finding a stale binary, check the command path:
where.exe msb
If an error mentions libkrunfw.so or libkrunfw.dylib, clear any old Unix/macOS override in MSB_LIBKRUNFW_PATH or config.json, or point it at libkrunfw.dll.
msb self update stages and verifies the new Windows release before scheduling the installed files for replacement. The command can exit while another msb or microsandbox process still has an executable locked; the background task keeps retrying and writes its progress to the log path printed by the command.
The PowerShell installer checks both public executable names before changing the installation. If it reports that an executable is still running, stop the listed process or its active sandbox, then rerun the installer.
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 when you intentionally bind 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. That lets msb read input, forward resize events, and restore the console when the session exits.