zeroecco/holosDeclarative KVM/QEMU VM orchestration tool using YAML compose files. Manages multi-VM stacks with cloud-init, SSH, PCI passthrough, and image verification without libvirt or 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 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:
```bash
holos run alpine
holos exec <printed-project-name>
holos down <printed-project-name>
```
A single-service stack you can `curl`. Save as `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
```
That is a real VM booting a cloud image, installing a package, writing config,
and forwarding a host port.
## Daily use
Inside a project directory:
```bash
holos exec web # open a guest shell
holos logs # read project boot logs
holos stop web # keep its disk
holos start web
holos up --dry-run # preview configuration changes
holos help exec # command syntax and options
```
Use an instance name such as `web-0` when a service has multiple replicas.
## Install
Pre-built binaries are attached to every
[GitHub release](https://github.com/zeroecco/holos/releases):
```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
```
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:
```bash
go build -o bin/holos ./cmd/holos
go test ./...
bin/holos doctor
```
## CLI
```text
holos up [-f holos.yaml] [--dry-run] [--recreate] [--strict] [--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] [--strict]
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
```
## Docs
- [Website](https://zeroecco.github.io/holos/): landing page and rendered docs.
- [CLI guide](https://github.com/zeroecco/holos/blob/main/docs/cli.md): ad hoc VMs, `exec`, systemd install, virsh import,
and `doctor`.
- [Compose file](https://github.com/zeroecco/holos/blob/main/docs/compose.md): services, volumes, healthchecks,
networking, PCI passthrough, Dockerfile provisioning, and defaults.
- [JSON Schema](https://github.com/zeroecco/holos/blob/main/docs/holos.schema.json): editor completion and validation for
`holos.yaml`.
- [Examples](https://github.com/zeroecco/holos/blob/main/examples/README.md): runnable and template stacks with
README-style explanations.
- [Missing features](https://github.com/zeroecco/holos/blob/main/docs/missing-features.md): prioritized gaps that fit
holos' single-host KVM compose goal.
- [Development](https://github.com/zeroecco/holos/blob/main/docs/development.md): build, test, host requirements, and
release process.
- [Security policy](https://github.com/zeroecco/holos/blob/main/SECURITY.md): supported versions and private reporting.
- [Threat model / hardening](https://github.com/zeroecco/holos/blob/main/docs/threat-model.md):
image verification, state permissions, locks, and operational guidance.
- [Contributing](https://github.com/zeroecco/holos/blob/main/CONTRIBUTING.md): build, test, style, and PR conventions.
## Examples
Start with the small nginx example:
```bash
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
### Permission denied opening /dev/kvm
Check `id -nG` and `ls -l /dev/kvm`. On hosts where the device belongs to the
`kvm` group, add your user with `sudo usermod -aG kvm "$USER"`, then log out
and reconnect. Existing shells keep their old group membership. Run
`holos doctor` again from the new session.
### 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](https://github.com/zeroecco/holos/blob/main/LICENSE). See
[`NOTICE`](https://github.com/zeroecco/holos/blob/main/NOTICE) for attribution.