holos

Docker Compose für KVM. Definiere Multi-VM-Stacks in einer YAML-Datei. Kein libvirt, kein XML, keine verteilte Control Plane.

Website und Dokumentation: https://zeroecco.github.io/holos/

Die primitive Einheit ist eine VM, kein Container. Jede Workload-Instanz erhält ihre eigene Kernel-Grenze, qcow2-Overlay, cloud-init-Seed und generierten SSH-Zugang.

Schnellstart

Erfordert Linux + /dev/kvm. macOS-Builds führen Offline-Befehle wie validate, import, images und pull aus, aber up und run benötigen einen KVM-Host.

Eine wegwerfbare VM, keine Compose-Datei:

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

Ein Single-Service-Stack, den du mit curl erreichen kannst. Speichere ihn als 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

Das ist eine echte VM, die ein Cloud-Image bootet, ein Paket installiert, Konfiguration schreibt und einen Host-Port weiterleitet.

Installation

Vorgefertigte Binärdateien sind an jedes GitHub-Release angehängt:

TAG=v0.6.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

Die Release-Seiten enthalten SHA-256-Prüfsummen und GitHub-Artefakt-Attestierungen für signierte Provenienz. Verifiziere beide, bevor du Binärdateien auf Produktionshosts installierst.

Oder baue aus dem Quellcode:

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

CLI

holos up [-f holos.yaml] [--locked] [--lockfile path] [--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 (--capacity/--network)
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|list|rm|restore|export} ... manage root snapshots
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 snapshots <project> <volume>
                                     list volume snapshots
holos volumes snapshot-rm <project> <volume> <snapshot>
                                     remove a volume snapshot
holos volumes snapshot-restore <project> <volume> <snapshot>
                                     restore a volume snapshot
holos volumes snapshot-export <project> <volume> <snapshot> <path>
                                     export a volume snapshot
holos volumes resize [--shrink] <project> <volume> <size>
                                     resize a detached named volume
holos devices [--gpu]                list PCI devices and IOMMU groups
holos completion <bash|zsh|fish>      print shell completion script
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

Dokumentation

• Website: Landingpage und gerenderte Dokumentation.
• CLI-Anleitung: Ad-hoc-VMs, exec, systemd-Installation, virsh-Import und doctor.
• Compose-Datei: Services, Volumes, Healthchecks, Netzwerk, PCI-Passthrough, Dockerfile-Provisionierung und Standardwerte.
• JSON-Schema: Editor-Vervollständigung und Validierung für holos.yaml.
• Beispiele: ausführbare und Template-Stacks mit Erklärungen im README-Stil.
• Fehlende Funktionen: priorisierte Lücken, die zum Single-Host-KVM-Compose-Ziel von holos passen.
• Entwicklung: Build, Test, Host-Anforderungen und Release-Prozess.
• Sicherheitsrichtlinie: unterstützte Versionen und private Meldung.
• Bedrohungsmodell / Härtung: Image-Verifizierung, State-Berechtigungen, Locks und Betriebshinweise.
• Mitwirken: Build-, Test-, Style- und PR-Konventionen.

Beispiele

Beginne mit dem kleinen nginx-Beispiel:

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

Das Beispiele-Verzeichnis enthält außerdem Dockerfile-Provisionierung, GPU-Passthrough und einen Multi-Service-Stack, der depends_on, generierte Konfiguration und Replicas zeigt.

Host-Anforderungen

• Linux mit /dev/kvm
• qemu-system-x86_64
• qemu-img
• Eines von cloud-localds, genisoimage, mkisofs oder xorriso
• OVMF / edk2-ovmf-Firmware für UEFI oder PCI-Passthrough
• ssh für holos exec und Healthchecks

Führe holos doctor aus, um den Host zu prüfen.

Fehlerbehebung

SSH setzt beim ersten Boot zurück

kex_exchange_identification: read: Connection reset by peer bedeutet meist, dass cloud-init noch Host-Schlüssel neu generiert und sshd neu startet. holos exec wartet standardmäßig bis zu 60s, aber sehr langsame erste Boots können einen weiteren Versuch oder holos exec -w 5m <project> erfordern.

Konsole zeigt Login incorrect

Die serielle Konsole versucht möglicherweise einen Autologin, bevor cloud-init den Benutzer erstellt. Warte auf cloud-init ... finished im Konsolen-Log und verwende dann holos exec. Cloud-Images werden im Allgemeinen ohne Konsolen-Passwort ausgeliefert, und holos fügt keines hinzu.

up schlägt auf macOS fehl