Docker-VM-Runner

Run lightweight QEMU/KVM virtual machines within Docker. Each container hosts a libvirt-managed VM with optional Redfish control and noVNC console support. Images are pulled automatically from upstream cloud sources or can be supplied locally.

docker-vm-runner.mp4

Background

I rely on containers to avoid polluting host machines while developing applications, but containerized environments have limits around systemd, networking, and kernel features. Docker-VM-Runner bridges that gap by making it just as easy to spin up a full virtual machine: a single docker run fetches the requested cloud image, boots it, and attaches your terminal to the VM console immediately.

Quick Start

docker run --rm -it \
  --name vm1 \
  -p 2222:2222 \
  --device /dev/kvm:/dev/kvm \
  ghcr.io/munenick/docker-vm-runner:latest

• SSH: ssh -p 2222 user@localhost (password: password).
• Optional Redfish API: add -e REDFISH_ENABLE=1 -p 8443:8443 and visit https://localhost:8443 (admin / password).
• Multi-arch images: published tags target both linux/amd64 and linux/arm64; with host KVM available the guest runs on its native architecture.

For persistence, GUI, ISO installs, and compose workflows see the documentation — start with Quick Start for additional docker run variants.

Highlights

• KVM acceleration with automatic fallback to TCG when /dev/kvm is unavailable.
• Libvirt manages lifecycle, with optional sushy-emulator (Redfish) power/boot control.
• Cloud-init injects default credentials and optional SSH keys.
• Run commands inside the guest with docker exec <container> guest-exec "command" — no SSH required.
• Bind-mount host directories into the guest via virtiofs or 9p for easy file sharing.
• Optional noVNC web console with TLS, local ISO/blank disk workflows, and docker-compose support.
• UEFI and Secure Boot support (OVMF) with software TPM emulation.
• Multiple disk support (up to 6 disks), block device passthrough, and multiple disk controllers (virtio, scsi, nvme, ide, usb).
• Auto-sizing resources with MEMORY=max, CPUS=half, DISK_SIZE=max.
• Hyper-V enlightenments for optimal Windows guest performance.
• Compressed image auto-extraction (.gz, .xz, .7z, .zip) and foreign format conversion (VHD, VMDK, VDI to qcow2).
• Host system info display at startup with filesystem compatibility warnings.

Documentation

• Quick Start
• GUI & Installation Media
• iPXE Boot Guide
• Configuration Reference
• Security Guide
• Troubleshooting & Operations
• Redfish Guide

Host Platform Support

• Linux (/dev/kvm available) — highest performance. Containers can pass through KVM directly on bare-metal hosts or inside nested environments that expose the KVM device. This is the primary development and validation target.
• Windows (Docker Desktop / WSL2) — supports /dev/kvm when the host provides nested virtualization (Windows 11+ with WSL2 + wsl --install --web-download, or Hyper-V with virtualization enabled). Performance matches the Linux case when KVM is available; otherwise the container falls back to TCG emulation.
• macOS (Docker Desktop) — functional with the TCG fallback. Apple’s Virtualization.framework cannot be accessed from Linux containers, so expect reduced performance compared to native macOS hypervisors.

License

MIT License