zeroecco/holosHerramienta declarativa de orquestación de máquinas virtuales KVM/QEMU que utiliza archivos de composición YAML. Gestiona pilas de múltiples VMs con cloud-init, SSH, paso PCI y verificación de imágenes sin libvirt ni 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 para KVM. Define stacks multi-VM en un solo archivo YAML. Sin libvirt, sin
XML, sin plano de control distribuido.
Sitio web y documentación: <https://zeroecco.github.io/holos/>
La primitiva es una VM, no un contenedor. Cada instancia de carga de trabajo obtiene su propia
frontera de kernel, overlay qcow2, seed de cloud-init y acceso SSH generado.
## Inicio Rápido
> Requiere Linux + `/dev/kvm`. Las compilaciones para macOS ejecutan comandos sin conexión como
> `validate`, `import`, `images` y `pull`, pero `up` y `run` necesitan un host
> KVM.
Una VM desechable, sin archivo compose:
```bash
holos run alpine
holos exec <printed-project-name>
holos down <printed-project-name>
```
Un stack de un solo servicio que puedes `curl`. Guarda como `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
```
Eso es una VM real arrancando una imagen cloud, instalando un paquete, escribiendo configuración
y reenviando un puerto del host.
## Instalación
Los binarios precompilados se adjuntan a cada
[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
```
Las páginas de release incluyen checksums SHA-256 y atestaciones de artefactos de GitHub para
procedencia firmada. Verifica ambos antes de instalar binarios en hosts de producción.
O compila desde el código fuente:
```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
```
## Documentación
- [Sitio web](https://zeroecco.github.io/holos/): página de inicio y documentación renderizada.
- [Guía de CLI](https://github.com/zeroecco/holos/blob/main/docs/cli.md): VMs ad hoc, `exec`, instalación con systemd, importación de virsh
y `doctor`.
- [Archivo Compose](https://github.com/zeroecco/holos/blob/main/docs/compose.md): servicios, volúmenes, healthchecks,
redes, PCI passthrough, aprovisionamiento con Dockerfile y valores predeterminados.
- [JSON Schema](https://github.com/zeroecco/holos/blob/main/docs/holos.schema.json): autocompletado y validación en el editor para
`holos.yaml`.
- [Ejemplos](https://github.com/zeroecco/holos/blob/main/examples/README.md): stacks ejecutables y plantillas con
explicaciones al estilo README.
- [Funciones faltantes](https://github.com/zeroecco/holos/blob/main/docs/missing-features.md): brechas priorizadas que encajan con
el objetivo de compose KVM de un solo host de holos.
- [Desarrollo](https://github.com/zeroecco/holos/blob/main/docs/development.md): compilación, pruebas, requisitos del host y
proceso de release.
- [Política de seguridad](https://github.com/zeroecco/holos/blob/main/SECURITY.md): versiones soportadas y reporte privado.
- [Modelo de amenazas / hardening](https://github.com/zeroecco/holos/blob/main/docs/threat-model.md):
verificación de imágenes, permisos de estado, locks y guía operativa.
- [Contribuir](https://github.com/zeroecco/holos/blob/main/CONTRIBUTING.md): compilación, pruebas, estilo y convenciones de PR.
## Ejemplos
Comienza con el pequeño ejemplo de nginx:
```bash
holos up -f examples/alpine-nginx/holos.yaml
curl localhost:8080
holos down alpine-nginx
```
El directorio de ejemplos también incluye aprovisionamiento con Dockerfile, GPU passthrough
y un stack multiservicio que muestra `depends_on`, configuración generada y
réplicas.
## Requisitos del Host
- Linux con `/dev/kvm`
- `qemu-system-x86_64`
- `qemu-img`
- Uno de `cloud-localds`, `genisoimage`, `mkisofs` o `xorriso`
- Firmware OVMF / edk2-ovmf para UEFI o PCI passthrough
- `ssh` para `holos exec` y healthchecks
Ejecuta `holos doctor` para verificar el host.
## Solución de Problemas
### SSH se reinicia en el primer arranque
`kex_exchange_identification: read: Connection reset by peer` generalmente significa
que cloud-init todavía está regenerando las claves del host y reiniciando sshd. `holos exec`
espera hasta 60s por defecto, pero los primeros arranques muy lentos pueden necesitar otro reintento o
`holos exec -w 5m <project>`.
### La consola muestra `Login incorrect`
La consola serie puede intentar autologin antes de que cloud-init cree el usuario.
Espera a `cloud-init ... finished` en el log de la consola, luego usa `holos exec`.
Las imágenes cloud generalmente no incluyen una contraseña de consola, y holos no
agrega una.
### `up` falla en macOS
KVM es una característica del kernel de Linux. Los binarios de macOS son útiles para autoría y
comandos sin conexión, pero `holos up` y `holos run` deben ejecutarse en un host
Linux KVM.
## No Objetivos
holos no es Kubernetes. No intenta resolver clustering multi-host, migración en vivo,
service meshes, redes overlay, schedulers, CRDs ni quórum de plano de control.
El objetivo es hacer que KVM sea viable para stacks de un solo host sin importar la
forma operativa de Kubernetes.
## Licencia
Licenciado bajo la [Apache License, Version 2.0](https://github.com/zeroecco/holos/blob/main/LICENSE). Consulta
[`NOTICE`](https://github.com/zeroecco/holos/blob/main/NOTICE) para atribución.