zeroecco/holosDeklaratives KVM/QEMU VM-Orchestrierungstool, das YAML-Compose-Dateien verwendet. Verwaltet Multi-VM-Stacks mit cloud-init, SSH, PCI-Durchleitung und Image-Verifikation ohne libvirt oder XML.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./docs/holos-lockup-dark.svg">
<img alt="holos" src="https://raw.githubusercontent.com/zeroecco/holos/HEAD/docs/holos-lockup-light.svg" width="340">
</picture>
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:
```bash
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`:
```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
```
```bash
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](https://github.com/zeroecco/holos/releases) angehängt:
```bash
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:
```bash
go build -o bin/holos ./cmd/holos
go test ./...
bin/holos doctor
```
## CLI
```text
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](https://zeroecco.github.io/holos/): Landingpage und gerenderte Dokumentation.
- [CLI-Anleitung](https://github.com/zeroecco/holos/blob/main/docs/cli.md): Ad-hoc-VMs, `exec`, systemd-Installation, virsh-Import
und `doctor`.
- [Compose-Datei](https://github.com/zeroecco/holos/blob/main/docs/compose.md): Services, Volumes, Healthchecks,
Netzwerk, PCI-Passthrough, Dockerfile-Provisionierung und Standardwerte.
- [JSON-Schema](https://github.com/zeroecco/holos/blob/main/docs/holos.schema.json): Editor-Vervollständigung und Validierung für
`holos.yaml`.
- [Beispiele](https://github.com/zeroecco/holos/blob/main/examples/README.md): ausführbare und Template-Stacks mit
Erklärungen im README-Stil.
- [Fehlende Funktionen](https://github.com/zeroecco/holos/blob/main/docs/missing-features.md): priorisierte Lücken, die zum
Single-Host-KVM-Compose-Ziel von holos passen.
- [Entwicklung](https://github.com/zeroecco/holos/blob/main/docs/development.md): Build, Test, Host-Anforderungen und
Release-Prozess.
- [Sicherheitsrichtlinie](https://github.com/zeroecco/holos/blob/main/SECURITY.md): unterstützte Versionen und private Meldung.
- [Bedrohungsmodell / Härtung](https://github.com/zeroecco/holos/blob/main/docs/threat-model.md):
Image-Verifizierung, State-Berechtigungen, Locks und Betriebshinweise.
- [Mitwirken](https://github.com/zeroecco/holos/blob/main/CONTRIBUTING.md): Build-, Test-, Style- und PR-Konventionen.
## Beispiele
Beginne mit dem kleinen nginx-Beispiel:
```bash
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
KVM ist eine Linux-Kernel-Funktion. macOS-Binärdateien sind nützlich zum Verfassen und für
Offline-Befehle, aber `holos up` und `holos run` müssen auf einem Linux-KVM-
Host ausgeführt werden.
## Nicht-Ziele
holos ist nicht Kubernetes. Es versucht nicht, Multi-Host-Clustering, Live-
Migration, Service Meshes, Overlay-Netzwerke, Scheduler, CRDs oder Control-Plane-
Quorum zu lösen.
Das Ziel ist es, KVM für Single-Host-Stacks nutzbar zu machen, ohne die
Betriebsform von Kubernetes zu übernehmen.
## Lizenz
Lizenziert unter der [Apache License, Version 2.0](https://github.com/zeroecco/holos/blob/main/LICENSE). Siehe
[`NOTICE`](https://github.com/zeroecco/holos/blob/main/NOTICE) für die Namensnennung.