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 \
  --hostname vm1 \
  -p 2222:2222 \
  --device /dev/kvm:/dev/kvm \
  ghcr.io/munenick/docker-vm-runner:latest

• SSH: ssh -p 2222 <user>@localhost (user depends on the distro).
• 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.
• 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.

Documentation

• Quick Start
• GUI & Installation Media
• iPXE Boot Guide
• Configuration Reference
• 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