---
title: Windows troubleshooting
description: Diagnose Windows Hypervisor Platform, runtime, terminal, and networking setup issues
icon: "screwdriver-wrench"
---

<Note>
  Windows support is currently in preview. A Windows MSI or winget package is not published yet; use the PowerShell installer from the latest GitHub release.
</Note>

## Quick checks

Install microsandbox with:

```powershell
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:

```powershell
msb doctor
```

If the only failure is Windows Hypervisor Platform setup, let `msb` open the elevated fix prompt:

```powershell
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.

## Runtime files

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:

```powershell
$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:

```powershell
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`.

## Windows Hypervisor Platform

microsandbox uses Windows Hypervisor Platform through libkrun. Enable the `HypervisorPlatform` optional feature from an elevated PowerShell:

```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:

```powershell
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:

```powershell
bcdedit /enum "{current}"
```

The `hypervisorlaunchtype` setting should be `Auto` or absent. To set it explicitly, run this from an elevated terminal and reboot:

```powershell
bcdedit /set hypervisorlaunchtype auto
```

## Source-build toolchain

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:

```powershell
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.

## Networking and firewall prompts

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.

## Interactive terminals

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:

```powershell
msb run --name win-shell --replace -t alpine -- /bin/sh
```

Then type `echo hi`, press Enter, and exit with `exit`.

## winget status

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.