holos

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.

Quick Start Read The Docs Install 
$ holos run alpine
$ holos exec alpine
$ holos down alpine

$ holos up
$ curl localhost:8080
hello from 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

Runtime commands require Linux with /dev/kvm. macOS binaries are still useful for authoring and offline commands such as validate, images, pull, and import.

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 doctor

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

Then launch it:

holos up
curl localhost:8080
holos down hello

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.