> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Run microsandbox in Docker

> Run the microsandbox CLI from a Linux container with KVM access

Local-only (The container runs the local microsandbox backend and needs hardware virtualization from the environment running Docker. It is not a microsandbox cloud workflow.)

This guide runs the `msb` CLI inside Docker and starts an Alpine microVM from the container. It works in any Docker environment that can pass a usable `/dev/kvm` device into the container.

## Run microsandbox in Docker

**1. Check Docker support**

Pull the image, then run `msb doctor` inside it before starting a sandbox:

```bash Shell theme={null}
docker pull ghcr.io/superradcompany/microsandbox:latest
```

Run the preflight inside the container:

```bash macOS & Linux theme={null}
docker run --rm --device /dev/kvm \
  ghcr.io/superradcompany/microsandbox:latest \
  doctor
```

```powershell Windows theme={null}
docker run --rm --device /dev/kvm `
  ghcr.io/superradcompany/microsandbox:latest `
  doctor
```

A compatible Docker environment reports both checks as successful:

```text theme={null}
✓ KVM device   /dev/kvm
✓ KVM access   read/write
```

If both checks pass, continue with the example. If either fails, the Docker environment does not currently expose the virtualization support microsandbox needs. `/dev/kvm` is the authoritative compatibility check: Docker Engine can pass it through directly, while Docker Desktop depends on whether its Linux VM makes nested virtualization available.

If Docker rejects the device mapping or `msb doctor` reports that `/dev/kvm` is missing, consult the relevant setup guide:

* **Linux Docker Engine:** Follow the [`/dev/kvm` setup and permission checks](/troubleshooting/linux#missing-/dev/kvm).
* **Docker Desktop:** Review the [Mac virtual machine manager](https://docs.docker.com/desktop/features/vmm/) or [Windows backend](https://docs.docker.com/desktop/setup/install/windows-install/) documentation. Hardware virtualization on the physical machine does not by itself make `/dev/kvm` available to containers.
* **Docker Desktop inside another VM or VDI:** Follow Docker's [nested-virtualization guide](https://docs.docker.com/desktop/setup/vm-vdi/).

After changing the Docker or hypervisor configuration, rerun the preflight. Adding `--privileged` cannot create a KVM device that the Docker environment does not have.

**2. Open an interactive sandbox**

Run Alpine and attach your terminal to its shell:

```bash macOS & Linux theme={null}
docker run --rm -it \
  --device /dev/kvm \
  ghcr.io/superradcompany/microsandbox:latest \
  run alpine --name my-sandbox --replace
```

```powershell Windows theme={null}
docker run --rm -it `
  --device /dev/kvm `
  ghcr.io/superradcompany/microsandbox:latest `
  run alpine --name my-sandbox --replace
```

* `--rm` removes the outer container when it exits.
* `-it` carries your terminal through Docker and `msb` to the sandbox. Without it, the sandbox can be running with no usable prompt.
* `--device /dev/kvm` grants the specific hardware interface microsandbox needs. The container does not require Docker's blanket `--privileged` mode.

At the Alpine prompt, verify the guest and exit:

```sh Shell theme={null}
uname -a
exit
```

**3. Run one command**

For automation, pass a command instead of allocating a terminal:

```bash macOS & Linux theme={null}
docker run --rm --device /dev/kvm \
  ghcr.io/superradcompany/microsandbox:latest \
  run alpine --name my-sandbox --replace -- \
  echo "hello from a microVM"
```

```powershell Windows theme={null}
docker run --rm --device /dev/kvm `
  ghcr.io/superradcompany/microsandbox:latest `
  run alpine --name my-sandbox --replace -- `
  echo "hello from a microVM"
```

The command's output and exit code pass through both layers to the host.

**4. Persist images and sandboxes**

Without a volume, the outer container owns the microsandbox image cache and database. `--rm` deletes them with the container, so the next run downloads Alpine again. Mount a Docker volume when repeated runs should reuse that state:

```bash Shell theme={null}
docker volume create microsandbox-data
```

Mount it at microsandbox's data directory:

```bash macOS & Linux theme={null}
docker run --rm -it \
  --device /dev/kvm \
  --volume microsandbox-data:/root/.microsandbox \
  ghcr.io/superradcompany/microsandbox:latest \
  run alpine --name my-sandbox --replace
```

```powershell Windows theme={null}
docker run --rm -it `
  --device /dev/kvm `
  --volume microsandbox-data:/root/.microsandbox `
  ghcr.io/superradcompany/microsandbox:latest `
  run alpine --name my-sandbox --replace
```

The Docker volume preserves pulled images, stopped sandboxes, snapshots, and the microsandbox database. Remove it only when that state is no longer needed:

```bash Shell theme={null}
docker volume rm microsandbox-data
```

## Troubleshooting

> **The process exits with SIGABRT before the agent starts**
>
> Run the `msb doctor` preflight above. An early abort while entering the VM commonly means the outer Linux environment did not provide usable KVM access.

> **The command keeps running but shows no prompt**
>
> Check that the Docker command includes `-it`. From another terminal, `docker ps` may show that the outer container is running even though its standard input and terminal were not attached.

> **The guest image downloads on every run**
>
> Mount `microsandbox-data` at `/root/.microsandbox`. An ephemeral outer container otherwise starts with an empty microsandbox cache.

## Image tags

| Tag | Description |
| - | - |
| `latest` | Latest microsandbox release. |
| `x.y.z` | Exact release version. |
| `x.y` | Latest patch release in a minor series. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.