gregewing/any-vm-runner repository overview

This image is intended as a means for running virtual machines created elsewhere, such as using my any-vm-creator docker image. Though, it will run any VM image that is in .qcow2 format and mounted into the container as described below. This means that it will boot any VM that you give it in qcow2 format, regardless of the Operating Stystem installed therein. (e.g. a full windows virtual PC in a docker container, or an instance of Android_x86, whatever floats yur boat really...)

⁠Update 21 August 2025

• I've made some changes to thsi project recently as I need to make more use of it. It now fully supports UEFI and Legacy BIOS operating systems, though you need to specify which you want to use in the ENV variables when creating the container, see below.
• There are ew BIOS firmware files for both Seabios Legacy Boot and also for UEFI boot, giving flexability and greater support for a wide variety of Operating Systems.
• The container now uses qemu directly instead of beig dependent on 'virsh install' for managing the guest VM images.
• The majority of the updates are in the startup.sh that is started with the container, which has been completely re-written.

⁠To get started you will need

• a .qcow2 file with your chosen OS installed
• this container

⁠What happens when you run this container

Start the conatiner with the following, or something similar:

docker run -d --privileged \
--name any-vm-runner \
--cgroupns host \
--device=/dev/kvm \
--device=/dev/net/tun \
-e MEMORY=4096 \
-e CPU=4 \
-e OS_VARIANT=windows11 \
-v /sys/fs/cgroup:/sys/fs/cgroup:rw \
-v any-vm-creator:/guestVMdata \
-v scripts:/scripts \
-p 0.0.0.0:5910:5910/tcp \
-p 0.0.0.0:3389:3389/tcp \
--cap-add=NET_ADMIN \
--cap-add=SYS_ADMIN \
gregewing/any-vm-runner:latest

When the container starts for the first time, it will look for a virtual disk image file mounted at /guestVMdata/guestVM.qcow2. If it finds one then it will attempt to boot the OS installed in that virtual disk file.

You may have to specify a few things to get your image to boot, such as the BIOS Type and the guest VM OS type, see Environment Variables below.

⁠Ports

I assume you understand enough about port mappings in docker to set this up how you need it without me having to tell you how to do it. Map the ports you need based on your requirements.

⁠Volumes

There are a couple of key volume or bind-mount used by this container image:

• -v any-vm-creator:/guestVMdata replace -v any-vm-creator with the name of a volume that you created beforehand. This is a very important step, as this is where the guest VM .qcow2 disk needs to be stored, so teh container can boot it.
• -v scripts:/scripts (optional) this mount, if you chose to use it enables you to run scripts inside the docker container immediately after it is started. The container will execute any .sh scripts it finds in /scripts before starting the nested VM. Use this to make any customisations that you require to the container or its nested VM, perhaps by waiting for the VM to boot and then interacting with it. (for example, applying firewall rules, routing configurations or customising the guestVM) If no scrits mount is provided, then this will be ignored.

⁠Environment Variables

The above docker run command makes use of the following environment variables, which you may want to alter to suit your requirements:

• MEMORY - this is the RAM that will be allocated to the guest VM that you are creating, this is used for the OS install and build only.
• CPU - this is the number of vCPU cores to allocate to the guest VM during the install and build phase.
• OS_VARIANT - this is where we specify the operating system that we are installing. I have included this so that you can explicitly tell the container if you are installing windows in your VM, and it will mount the current version of virtio-win.iso driver CD (bundled in the container) into the VM so that you can install drivers. This is not necessary for non-windows VMs. any value that starts with "win" here will mount the driver CD when creating the VM. If you don't provide a value in your docker command, it will default to 'win11'
• BIOS_TYPE - this is where you specify 'UEFI' or 'BIOS' for Legacy boot mode. This will cause the container to start up the embedded qemu-kvm hypervisor with the right bios image for your ISO image to boot properly. Most OSs now use UEFI, but you might have some specific requirements. The image includes the necessary BIOS and UEFI files, so you dont need to mount them in manually.

⁠Tested and working with

• Win11_24H2_EnglishInternational_x64.iso
• Rocky-9.6-x86_64-dvd.iso
• ubuntu-24.10-live-server-amd64.iso
• Win10_22H2_EnglishInternational_x64v1.iso
• WinSrv2025.iso
• WinSrv2022.iso
• android-x86_64-9.0-r2.iso
• debian-13.0.0-amd64-DVD-1.iso
• debian-12.11.0-amd64-DVD-1.iso
• debian-12.11.0-amd64-netinst.iso
• proxmox-ve_9.0-1.iso

Yes using Legacy BIOS, and specifically no virtio-win.iso cd mounted.

• archlinux-x86_64.iso
• kali-linux-2025.2-installer-amd64.iso

⁠Issues and Support

I have created a github repository⁠ for this project, please raise any comments, suggestions or issues there.