Guide
Docker Images
Build VM root filesystems from Docker or OCI images
vmsan can build a root filesystem from any Docker or OCI image, letting you use familiar container images as the base for your microVMs.
Built-in runtimes such as
node22, node24, and python3.13 are installed separately as prebuilt artifacts. --from-image still builds a rootfs locally and requires Docker.Create a VM from a Docker image
Use the --from-image flag:
vmsan create --from-image node:22-alpine
This pulls the image, extracts its filesystem layers, and converts them into an ext4 rootfs for Firecracker.
Use any OCI image
Any image reference supported by Docker works:
# Official images
vmsan create --from-image python:3.13-slim
# Custom registry images
vmsan create --from-image ghcr.io/myorg/myapp:latest
Limitations
Custom images do not include the vmsan agent. VMs created with
--from-image cannot use connect, exec, upload, or download commands. Use port forwarding (--publish-port) to access services running inside the VM.--from-image and --connect are mutually exclusive. The CLI will reject a command that uses both flags together.Combine with other flags
Docker images work with most other create flags:
vmsan create \
--from-image node:22-alpine \
--memory 512 \
--vcpus 2 \
--publish-port 3000 \
--network-policy custom \
--allowed-domain "*.npmjs.org"
Extracted image rootfs files are cached in
~/.vmsan/registry/ to speed up subsequent VM creation with the same image.