zeroecco/holosFerramenta declarativa de orquestração de VMs KVM/QEMU usando arquivos de composição YAML. Gerencia stacks de múltiplas VMs com cloud-init, SSH, PCI passthrough e verificação de imagens sem libvirt ou 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. Defina stacks multi-VM em um único arquivo YAML. Sem libvirt, sem
XML, sem plano de controle distribuído.
Site e documentação: <https://zeroecco.github.io/holos/>
A primitiva é uma VM, não um contêiner. Cada instância de workload recebe seu próprio
limite de kernel, overlay qcow2, seed cloud-init e acesso SSH gerado.
## Início Rápido
> Requer Linux + `/dev/kvm`. Builds para macOS executam comandos offline como
> `validate`, `import`, `images` e `pull`, mas `up` e `run` precisam de um host
> KVM.
Uma VM descartável, sem arquivo compose:
```bash
holos run alpine
holos exec <printed-project-name>
holos down <printed-project-name>
```
Um stack de serviço único que você pode acessar com `curl`. Salve 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
```
Isso é uma VM real inicializando uma imagem cloud, instalando um pacote, escrevendo configuração
e encaminhando uma porta do host.
## Instalação
Binários pré-compilados estão anexados 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
```
As páginas de release incluem checksums SHA-256 e atestados de artefatos do GitHub para
proveniência assinada. Verifique ambos antes de instalar binários em hosts de produção.
Ou compile a partir do código-fonte:
```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]
inicia todos os serviços
holos run [flags] <image> [-- cmd...] inicia uma VM avulsa
holos down <project> para e remove um projeto
holos ps [-f holos.yaml] lista projetos em execução
holos start [-f holos.yaml] [svc] inicia um serviço parado ou todos os serviços
holos stop [-f holos.yaml] [svc] para um serviço ou todos os serviços
holos console <project> [<inst>] conecta ao console serial
holos exec <project> [<inst>] [-- cmd...]
acessa uma instância via SSH
holos logs <project> [<svc|inst>] mostra logs do console
holos inspect [-f holos.yaml] [project|instance]
inspeciona o estado como JSON
holos validate [-f holos.yaml] valida o arquivo compose (--capacity/--network)
holos pull <image> baixa uma imagem cloud
holos verify <image>|--all verifica checksums de imagens em cache
holos images lista imagens disponíveis
holos images lock -f holos.yaml [-o holos.images.lock]
escreve o lockfile de imagens do projeto
holos snapshots {create|list|rm|restore|export} ... gerencia snapshots de root
holos volumes [-f holos.yaml] [--json]
lista volumes nomeados
holos volumes rm <project> <volume> remove um volume nomeado desanexado
holos volumes export <project> <volume> <path>
exporta um volume nomeado desanexado
holos volumes snapshot <project> <volume> <snapshot>
cria snapshot de um volume nomeado desanexado
holos volumes snapshots <project> <volume>
lista snapshots de volume
holos volumes snapshot-rm <project> <volume> <snapshot>
remove um snapshot de volume
holos volumes snapshot-restore <project> <volume> <snapshot>
restaura um snapshot de volume
holos volumes snapshot-export <project> <volume> <snapshot> <path>
exporta um snapshot de volume
holos volumes resize [--shrink] <project> <volume> <size>
redimensiona um volume nomeado desanexado
holos devices [--gpu] lista dispositivos PCI e grupos IOMMU
holos completion <bash|zsh|fish> imprime o script de autocompletar do shell
holos doctor [--json] verifica dependências do host
holos install [-f holos.yaml] [--system] [--enable]
instala uma unit systemd
holos uninstall [-f holos.yaml] [--system]
remove a unit systemd
holos import [vm...] [--all] [--xml file] [--connect uri] [-o file]
converte VMs virsh em holos.yaml
```
## Documentação
- [Site](https://zeroecco.github.io/holos/): página inicial e documentação renderizada.
- [Guia da CLI](https://github.com/zeroecco/holos/blob/main/docs/cli.md): VMs avulsas, `exec`, instalação systemd, importação virsh
e `doctor`.
- [Arquivo Compose](https://github.com/zeroecco/holos/blob/main/docs/compose.md): serviços, volumes, healthchecks,
rede, passthrough PCI, provisionamento via Dockerfile e padrões.
- [JSON Schema](https://github.com/zeroecco/holos/blob/main/docs/holos.schema.json): autocompletar e validação no editor para
`holos.yaml`.
- [Exemplos](https://github.com/zeroecco/holos/blob/main/examples/README.md): stacks executáveis e templates com
explicações no estilo README.
- [Recursos ausentes](https://github.com/zeroecco/holos/blob/main/docs/missing-features.md): lacunas priorizadas que se encaixam
no objetivo de compose KVM de host único do holos.
- [Desenvolvimento](https://github.com/zeroecco/holos/blob/main/docs/development.md): build, testes, requisitos de host e
processo de release.
- [Política de segurança](https://github.com/zeroecco/holos/blob/main/SECURITY.md): versões suportadas e relato privado.
- [Modelo de ameaças / hardening](https://github.com/zeroecco/holos/blob/main/docs/threat-model.md):
verificação de imagens, permissões de estado, locks e orientações operacionais.
- [Contribuindo](https://github.com/zeroecco/holos/blob/main/CONTRIBUTING.md): build, testes, estilo e convenções de PR.
## Exemplos
Comece com o pequeno exemplo nginx:
```bash
holos up -f examples/alpine-nginx/holos.yaml
curl localhost:8080
holos down alpine-nginx
```
O diretório de exemplos também inclui provisionamento via Dockerfile, passthrough de GPU
e um stack multi-serviço que demonstra `depends_on`, configuração gerada e
réplicas.
## Requisitos do Host
- Linux com `/dev/kvm`
- `qemu-system-x86_64`
- `qemu-img`
- Um dos seguintes: `cloud-localds`, `genisoimage`, `mkisofs` ou `xorriso`
- Firmware OVMF / edk2-ovmf para UEFI ou passthrough PCI
- `ssh` para `holos exec` e healthchecks
Execute `holos doctor` para verificar o host.
## Solução de Problemas
### SSH reinicia no primeiro boot
`kex_exchange_identification: read: Connection reset by peer` geralmente significa
que o cloud-init ainda está regenerando as chaves de host e reiniciando o sshd. `holos exec`
aguarda até 60s por padrão, mas primeiros boots muito lentos podem precisar de outra tentativa ou
`holos exec -w 5m <project>`.
### Console mostra `Login incorrect`
O console serial pode tentar autologin antes do cloud-init criar o usuário.
Aguarde `cloud-init ... finished` no log do console e então use `holos exec`.
Imagens cloud geralmente não vêm com senha de console, e o holos não
adiciona uma.
### `up` falha no macOS
KVM é um recurso do kernel Linux. Binários para macOS são úteis para autoria e
comandos offline, mas `holos up` e `holos run` devem ser executados em um host
Linux com KVM.
## Não-Objetivos
holos não é Kubernetes. Ele não tenta resolver clustering multi-host, migração ao vivo,
service meshes, redes overlay, schedulers, CRDs ou quórum de plano de controle.
O objetivo é tornar o KVM viável para stacks de host único sem importar a
forma operacional do Kubernetes.
## Licença
Licenciado sob a [Apache License, Version 2.0](https://github.com/zeroecco/holos/blob/main/LICENSE). Consulte
[`NOTICE`](https://github.com/zeroecco/holos/blob/main/NOTICE) para atribuição.