Docker compose for KVM
Real VMs, compose-shaped workflows.
holos launches cloud-image VMs with generated disks, cloud-init, SSH access, port forwards, healthchecks, volumes, and PCI passthrough from one readable YAML file.
$ holos run --name try-holos alpine
$ holos exec -w 5m try-holos
# In the guest: explore, then exit.
$ holos stop try-holos
$ holos start try-holos
$ holos down try-holos
Why holos
VMs As The Primitive
Every workload gets its own kernel boundary, qcow2 overlay, cloud-init seed, and generated SSH access.
No Control Plane
Run multi-VM stacks on one Linux KVM host without libvirt XML, clusters, schedulers, or service meshes.
Hardware Friendly
Use UEFI, volumes, healthchecks, Dockerfile-shaped provisioning, and VFIO PCI passthrough when the stack needs them.
Quick Start
Run VMs on a Linux host with /dev/kvm, QEMU, and a cloud-init seed builder.
See host requirements. macOS builds support authoring,
image downloads, and validation; they cannot run KVM VMs.
Install
Pre-built binaries are attached to every GitHub release:
This example installs the Linux x86-64 build. It uses curl, tar,
sha256sum, and the GitHub CLI (gh) for provenance verification. For other
platforms, choose the matching archive on the release page.
(
set -e
TAG=v0.7.1
ASSET=holos_${TAG#v}_Linux_x86_64.tar.gz
BASE=https://github.com/zeroecco/holos/releases/download/$TAG
curl -fLO $BASE/$ASSET
curl -fLO $BASE/checksums.txt
grep " $ASSET$" checksums.txt | sha256sum -c -
gh attestation verify $ASSET --repo zeroecco/holos
sudo tar -xz -C /usr/local/bin -f $ASSET holos
holos version
holos doctor
)
Release pages include SHA-256 checksums and GitHub artifact attestations for signed provenance. Verify both before installing binaries on production hosts.
Try one VM
Use a fixed name so every command below works as written:
holos run --name try-holos alpine
holos exec -w 5m try-holos
You are now in the guest. Run cat /etc/os-release, then exit to return to
the host. From the host:
holos stop try-holos # keep the guest disk
holos start try-holos
holos exec try-holos
Exit the guest again, then remove the disposable VM:
holos down try-holos # deletes its guest disk
Run a web service
Create an empty directory and save this as holos.yaml:
name: hello
services:
web:
image: ubuntu:noble
ports:
- "8080:80"
cloud_init:
packages: [nginx]
write_files:
- path: /var/www/html/index.html
content: "hello from holos\n"
runcmd:
- systemctl restart nginx
From that directory:
holos up
holos exec -w 5m web -- sudo cloud-init status --wait
curl --fail localhost:8080
Expect hello from holos. The wait matters: up starts the VM, but nginx is
installed during first boot. If provisioning fails, read holos logs web.
When finished, run holos down hello to delete this stack’s instance disks.
Use holos stop web instead when you want to keep the disk and resume later.
Next: daily commands and safe updates or the Compose file reference.
Documentation
Compose File
Services, networking, volumes, healthchecks, Dockerfile provisioning, PCI passthrough, and defaults.
CLI Guide
Ad hoc VMs, SSH with holos exec, reboot survival, virsh import, and host diagnostics.
Examples
Small runnable stacks and templates for nginx, Dockerfile provisioning, GPU passthrough, and multi-service demos.
Threat Model
Security boundaries, lock behavior, image verification, private qcow2 guidance, and hardening checklists.
Missing Features
Prioritized gaps that still fit holos' single-host KVM compose goal.