GitHub - zeroecco/holos: docker compose for kvm/qemu

Docker compose for KVM. Define multi-VM stacks in one YAML file. No libvirt, no XML, no distributed control plane.

Website and docs: https://zeroecco.github.io/holos/

The primitive is a VM, not a container. Every workload instance gets its own kernel boundary, qcow2 overlay, cloud-init seed, and generated SSH access.

Quick Start

Requires Linux + /dev/kvm. macOS builds run offline commands like validate, import, images, and pull, but up and run need a KVM host.

One disposable VM, no compose file:

holos run alpine
holos exec <printed-project-name>
holos down <printed-project-name>

A single-service stack you can curl. Save 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

holos up
curl localhost:8080
holos down hello

That is a real VM booting a cloud image, installing a package, writing config, and forwarding a host port.

Install

Pre-built binaries are attached to every GitHub release:

TAG=v0.2.3
ASSET=holos_${TAG#v}_Linux_x86_64.tar.gz
BASE=https://github.com/zeroecco/holos/releases/download/$TAG
curl -LO $BASE/$ASSET
curl -LO $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.

Or build from source:

go build -o bin/holos ./cmd/holos
go test ./...
bin/holos doctor

CLI

holos up [-f holos.yaml] [--lock-timeout 5m|--no-wait]
                                     start all services
holos run [flags] <image> [-- cmd...] launch a one-off VM
holos down <project>                 stop and remove a project
holos ps [-f holos.yaml]             list running projects
holos start [-f holos.yaml] [svc]    start a stopped service or all services
holos stop [-f holos.yaml] [svc]     stop a service or all services
holos console <project> [<inst>]     attach serial console
holos exec <project> [<inst>] [-- cmd...]
                                     SSH into an instance
holos logs <project> [<svc|inst>]    show console logs
holos inspect [-f holos.yaml] [project|instance]
                                     inspect state as JSON
holos validate [-f holos.yaml]       validate compose file
holos pull <image>                   pull a cloud image
holos verify <image>|--all           verify cached image checksums
holos images                         list available images
holos images lock -f holos.yaml [-o holos.images.lock]
                                     write project image lockfile
holos snapshots create <project> <instance> <snapshot>
                                     snapshot a stopped root overlay
holos volumes [-f holos.yaml] [--json]
                                     list named volumes
holos volumes rm <project> <volume>  remove a detached named volume
holos volumes export <project> <volume> <path>
                                     export a detached named volume
holos volumes snapshot <project> <volume> <snapshot>
                                     snapshot a detached named volume
holos volumes resize [--shrink] <project> <volume> <size>
                                     resize a detached named volume
holos devices [--gpu]                list PCI devices and IOMMU groups
holos doctor [--json]                check host dependencies
holos install [-f holos.yaml] [--system] [--enable]
                                     install a systemd unit
holos uninstall [-f holos.yaml] [--system]
                                     remove the systemd unit
holos import [vm...] [--all] [--xml file] [--connect uri] [-o file]
                                     convert virsh VMs into holos.yaml

Docs

Website: landing page and rendered docs.
CLI guide: ad hoc VMs, exec, systemd install, virsh import, and doctor.
Compose file: services, volumes, healthchecks, networking, PCI passthrough, Dockerfile provisioning, and defaults.
JSON Schema: editor completion and validation for holos.yaml.
Examples: runnable and template stacks with README-style explanations.
Missing features: prioritized gaps that fit holos' single-host KVM compose goal.
Development: build, test, host requirements, and release process.
Security policy: supported versions and private reporting.
Threat model / hardening: image verification, state permissions, locks, and operational guidance.
Contributing: build, test, style, and PR conventions.

Examples

Start with the small nginx example:

holos up -f examples/alpine-nginx/holos.yaml
curl localhost:8080
holos down alpine-nginx

The examples directory also includes Dockerfile provisioning, GPU passthrough, and a multi-service stack that shows depends_on, generated config, and replicas.

Host Requirements

Linux with /dev/kvm
qemu-system-x86_64
qemu-img
One of cloud-localds, genisoimage, mkisofs, or xorriso
OVMF / edk2-ovmf firmware for UEFI or PCI passthrough
ssh for holos exec and healthchecks

Run holos doctor to check the host.

Troubleshooting

SSH resets on first boot

kex_exchange_identification: read: Connection reset by peer usually means cloud-init is still regenerating host keys and restarting sshd. holos exec waits up to 60s by default, but very slow first boots may need another retry or holos exec -w 5m <project>.

Console shows `Login incorrect`

The serial console may attempt autologin before cloud-init creates the user. Wait for cloud-init ... finished in the console log, then use holos exec. Cloud images generally do not ship with a console password, and holos does not add one.

`up` fails on macOS

KVM is a Linux kernel feature. macOS binaries are useful for authoring and offline commands, but holos up and holos run must execute on a Linux KVM host.

Non-Goals

holos is not Kubernetes. It does not try to solve multi-host clustering, live migration, service meshes, overlay networks, schedulers, CRDs, or control plane quorum.

The goal is to make KVM workable for single-host stacks without importing the operational shape of Kubernetes.

License

Licensed under the Apache License, Version 2.0. See NOTICE for attribution.