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.