---
title: Linux
description: Diagnose KVM, permissions, and host runtime setup on Linux
icon: "linux"
---

microsandbox local sandboxes use hardware virtualization. On Linux, confirm that the host has a glibc-based Linux userland and that KVM is available through `/dev/kvm`.

## Quick checks

Start with the doctor command for the local setup checks:

```bash
msb doctor
```

If sandbox startup still fails with a KVM-related error, check the KVM module and device:

```bash
lsmod | grep kvm
ls -l /dev/kvm
```

An enabled Intel host usually shows `kvm_intel` and `kvm`; an enabled AMD host usually shows `kvm_amd` and `kvm`.

Then confirm that your current user can read and write the KVM device:

```bash
[ -r /dev/kvm ] && [ -w /dev/kvm ] && echo "OK" || echo "FAIL"
```

## Missing `/dev/kvm`

If `/dev/kvm` is missing, make sure CPU virtualization is enabled in firmware/UEFI and visible to Linux:

```bash
grep -E -c '(vmx|svm)' /proc/cpuinfo
```

A `0` result usually means virtualization is disabled in firmware, unavailable on the machine, or hidden by an outer VM. After enabling virtualization in firmware, reboot and check the KVM module again.

You can also try loading the host-specific KVM module:

```bash
sudo modprobe kvm_intel  # Intel
sudo modprobe kvm_amd    # AMD
```

If you are inside a cloud VM, CI runner, or another hypervisor, the outer environment must expose nested virtualization before `/dev/kvm` can appear.

## Permission denied

If `/dev/kvm` exists but sandbox startup fails with a permission error, your user probably cannot open the device. Check the device owner and group:

```bash
stat -c '%U %G %a %n' /dev/kvm
```

Many distributions grant access through the `kvm` group. Check whether the group exists, whether `/dev/kvm` uses it, and whether your shell is already in that group:

```bash
getent group kvm
ls -l /dev/kvm
groups
```

If `/dev/kvm` belongs to `kvm`, add your user to the group:

```bash
sudo usermod -aG kvm "$USER"
```

Log out and back in after changing group membership. If you want to refresh the current shell only, `newgrp kvm` may work, but opening a new login session is the least surprising path.

Some distributions use access control lists instead of group membership. If `setfacl` is available, you can grant your user read/write access directly:

```bash
sudo setfacl -m "u:$USER:rw" /dev/kvm
```

Re-run the read/write check after changing group membership or ACLs:

```bash
[ -r /dev/kvm ] && [ -w /dev/kvm ] && echo "OK" || echo "FAIL"
```

If your distribution uses a different group, udev rule, or enterprise policy for `/dev/kvm`, follow that local policy instead.

## Containers and VMs

When running microsandbox inside another VM or container, the outer environment must expose hardware virtualization. Many hosted CI runners and cloud VMs do not expose nested virtualization by default.

For Docker-based workflows, pass `/dev/kvm` into the container. See [Docker on Linux](/recipes/docker/docker) for the container flags.

## Interrupt acceleration

On Linux x86 hosts, `msb doctor` reports AMD AVIC or Intel APICv when the applicable KVM capability can be inspected:

```text
KVM AVIC   enabled (x2AVIC available)
KVM APICv  enabled by KVM policy
```

Doctor reports host policy and advertised capability, not proof that one running sandbox used hardware acceleration. An outer hypervisor may hide the capability on nested or cloud VMs.

If the capability is available but disabled, doctor prints the current-boot module reload command. Stop every KVM user before unloading either module; reloading it affects every VM on the host.

<Accordion title="Current-boot KVM policy commands">

AMD:

```bash
sudo modprobe -r kvm_amd && sudo modprobe kvm_amd avic=1
cat /sys/module/kvm_amd/parameters/avic
```

Intel:

```bash
sudo modprobe -r kvm_intel && sudo modprobe kvm_intel enable_apicv=1
cat /sys/module/kvm_intel/parameters/enable_apicv
```

Do not run either command while `/dev/kvm` has users. A distribution may build KVM into the kernel, prevent module removal, or require the setting in its boot configuration instead.

</Accordion>

Microsandbox never changes this host-wide policy automatically. See [Optimization](/sandboxes/optimization#host-interrupt-acceleration) for when interrupt acceleration matters.

## Linux userland

Use a normal glibc-based Linux host for the local runtime. Minimal or musl-only environments, such as a bare Alpine host image, are not the tested path for running local microsandbox sandboxes.