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 Run the preflight inside the container:A compatible Docker environment reports both checks as successful:If both checks pass, continue with the example. If either fails, the Docker environment does not currently expose the virtualization support microsandbox needs.
msb doctor inside it before starting a sandbox:/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/kvmsetup and permission checks. - Docker Desktop: Review the Mac virtual machine manager or Windows backend documentation. Hardware virtualization on the physical machine does not by itself make
/dev/kvmavailable to containers. - Docker Desktop inside another VM or VDI: Follow Docker’s nested-virtualization guide.
--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:
--rmremoves the outer container when it exits.-itcarries your terminal through Docker andmsbto the sandbox. Without it, the sandbox can be running with no usable prompt.--device /dev/kvmgrants the specific hardware interface microsandbox needs. The container does not require Docker’s blanket--privilegedmode.
3
Run one command
For automation, pass a command instead of allocating a terminal: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. Mount it at microsandbox’s data directory:The Docker volume preserves pulled images, stopped sandboxes, snapshots, and the microsandbox database. Remove it only when that state is no longer needed:
--rm deletes them with the container, so the next run downloads Alpine again. Mount a Docker volume when repeated runs should reuse that state:Troubleshooting
The process exits with SIGABRT before the agent starts
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
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
The guest image downloads on every run
Mount
microsandbox-data at /root/.microsandbox. An ephemeral outer container otherwise starts with an empty microsandbox cache.