CLI Guide
Everyday development
From the directory containing holos.yaml:
holos up
holos exec web # shell into the web service
holos exec web -- uname -a # run a guest command
holos logs # boot logs for this project
holos logs web # just web
holos stop web
holos start web
holos down # delete this project's instance disks
exec and console accept a service name when it has one instance. For a
replicated service, choose an instance such as web-0; Holos lists the choices
instead of guessing. Explicit project forms such as holos exec demo web
continue to work outside the project directory. If a name matches a saved
project, that project takes precedence; use -f holos.yaml to select the local
file explicitly.
logs, stop, down, and ps -f holos.yaml read project identity without
resolving images. They remain usable if an image is missing or unavailable.
exec and console also use saved instance state and login users for current
projects. Starting or changing VMs still resolves their configuration.
Use holos help exec for a command’s syntax and options. Flags go before the
target: holos exec -w 2m web -- uname -a.
Shell completion
Choose the block for your shell. Create the destination directory first:
mkdir -p ~/.local/share/bash-completion/completions
holos completion bash > ~/.local/share/bash-completion/completions/holos
mkdir -p ~/.zfunc
holos completion zsh > ~/.zfunc/_holos
mkdir -p ~/.config/fish/completions
holos completion fish > ~/.config/fish/completions/holos.fish
For zsh, add ~/.zfunc to fpath before running compinit in your shell
configuration. Restart your shell after installing completion.
The scripts complete top-level commands and subcommands for snapshots,
volumes, and completion.
Image locks
Run holos images lock -f holos.yaml to write a project image lockfile. Use
holos up --locked in CI or deployment scripts to require the adjacent
lockfile and reject changed image bytes or service entries. If you generated a
custom lockfile with images lock -o, pass the same path to up --lockfile.
Previewing and applying configuration changes
holos up compares resolved service configurations with saved service
fingerprints. Unchanged services keep their running processes and root disks;
stopped instances are started using their existing disks. Changed services are
replaced individually, and removed services are deleted. Replacement or removal
requires explicit --recreate because it discards the affected root disks,
including snapshots stored inside those disks. Named volumes survive.
holos up --dry-run -f holos.yaml
holos up --recreate -f holos.yaml
The preview prints create, keep, replace, or remove for each service.
Without --recreate, any destructive change refuses the entire update before
changing VMs. --recreate authorizes only the changes shown by the plan; it does
not force replacement of unchanged services. Planning and application use the
same project lock. Preview does not modify VM state, but compose resolution may
populate the image cache and lock acquisition may create state directories.
Fingerprints include resolved provisioning contents, hardware, ports, storage, replica counts, and generated networking. A replica-count change currently replaces that service. Network topology changes can also affect other services’ addresses or generated host mappings; those services appear as replacements in the preview. Labels, healthchecks, dependency ordering, and pre-stop hooks alone do not require replacing disks.
Older project records without service fingerprints cannot reliably identify
unchanged guests. They are conservatively shown as replacements and require
--recreate for the first update. Export any valuable root-disk data before
applying that migration; stop, exec, and inspection remain available.
Compose compatibility diagnostics
Configuration validation and launch commands warn on stderr about supplied settings that Holos accepts but ignores, including nested build/deploy options and unsupported volume/device forms. Diagnostics identify field paths without printing values. Included files follow the same checks; overridden definitions do not generate stale warnings.
holos validate --strict -f holos.yaml
holos up --strict -f holos.yaml
Strict mode rejects ignored settings before resolving images or changing VMs.
Use it in CI to prevent a valid Compose file from silently requesting behavior
that Holos does not implement. Ordinary mode retains compatibility and prints
warnings. For example, restart: always, profiles, and service-level
read_only do not implement restart policies, profile selection, or a read-only
VM root disk.
Capacity preflight
holos validate --capacity checks aggregate replica CPU and memory requests
against the current host and the process’s cgroup limits before launch.
--network checks that configured
bridge/tap networks refer to bridges that already exist. Both checks are
optional; use them in deployment scripts when host overcommit or missing host
network setup is not desired.
Ad Hoc VMs
holos run launches a one-off VM without a compose file:
holos run ubuntu:noble
holos run --vcpu 4 --memory 4G ubuntu:noble
holos run -p 8080:80 --pkg nginx \
--runcmd 'rc-update add nginx default && rc-service nginx start' alpine
holos run -v ./code:/srv:ro ubuntu:noble
holos run --device 0000:01:00.0 ubuntu:noble
holos run --image-os openrc ./custom-alpine.qcow2
holos run alpine -- echo hello world
The synthesized compose file is stored at
state_dir/runs/<name>/holos.yaml. The project name includes the image name
and a random suffix. Pass --name try-holos when you want predictable
follow-up commands.
Follow-up commands use the project name printed by holos run:
holos exec <name>
holos console <name>
holos logs <name>
holos down <name>
holos run exits once the VM is started. VMs are always detached. Use
holos exec for an interactive shell and holos console for serial boot logs.
SSH With holos exec
Every holos up creates a project SSH key under state_dir/ssh/<project>/ and
injects the public key with cloud-init. Each instance gets a host port forwarded
to guest port 22.
holos exec web-0
holos exec db-0 -- pg_isready
holos exec my-project -- uname -a
-u <user> overrides the login user. Otherwise holos uses the service’s
resolved cloud_init.user, then the image convention (alpine, arch,
debian, fedora, ubuntu, almalinux, rocky, cloud-user), then
ubuntu.
On a fresh VM, holos exec waits up to 60s for sshd to be ready. Use -w 0 to
disable that wait or -w 5m for slow first boots.
Project Locks
Lifecycle commands take a per-project lock before reading or writing runtime
state. holos up, run, down, start, stop, and ps -f wait up to
--lock-timeout (default 5m) when another holos process is already operating
on the same project. Use --no-wait when automation should fail fast instead
of waiting:
holos up --lock-timeout 30s
holos down --no-wait demo
Lock errors include the lock path and last recorded holder metadata when available.
Inspection
holos inspect emits JSON for a project or instance:
holos inspect demo
holos inspect web-0
holos inspect -f holos.yaml
holos inspect -f holos.yaml web-0
Without -f, inspect reads runtime state: services, instances, host forwards,
generated SSH endpoint, logs, QMP socket, and named-volume inventory. With
-f, inspect also includes the resolved service manifest; instance inspection
adds the QEMU argument vector reconstructed from the resolved manifest and saved
instance paths. It does not read or print generated private key files.
Snapshots
Stopped instances can snapshot their root overlay with qemu-img. This example
uses a project named demo with a service named web:
holos stop -f holos.yaml web
holos snapshots create demo web-0 before-upgrade
holos snapshots list demo web-0
holos snapshots restore demo web-0 before-upgrade
holos snapshots export demo web-0 before-upgrade ./web-before-upgrade.qcow2
holos snapshots rm demo web-0 before-upgrade
Snapshot export creates a standalone qcow2 image; it can be copied to another
host or used as a local image. Volume snapshots have equivalent
snapshot-restore and snapshot-export commands under holos volumes.
The command refuses running instances because mutating an active qcow2 overlay outside QEMU is unsafe.
Image Verification
Built-in images carry checksum metadata. holos pull, holos up, and
holos run verify downloads before promoting them into the cache and re-check a
cached file before reuse. To audit the cache explicitly:
holos verify alpine
holos verify --all
On the first pull into a cache, Ubuntu aliases select the newest released
amd64 server image from Ubuntu’s simplestreams feed. The dated download URL and
SHA-256 come from the same feed entry. Holos saves that selection only after
verifying the download, and later pulls and verify reuse it without contacting
Ubuntu. A cached Ubuntu image stays on its selected build when upstream
publishes a newer one. A fresh cache (or a missing cached artifact) resolves
the release again. Existing VM backing images are not replaced by newer builds.
ubuntu still defaults to noble (24.04); ubuntu:26 and ubuntu:26.04 select
resolute. The jammy and 22.04 aliases remain available. Caches created by
older holos versions remain on disk; the first pull with this resolver selects
a released image into a separate cache path.
Other built-in distributions currently use build URLs shipped with holos;
pull does not discover their newest upstream build. There is no image-refresh
command yet. Do not delete cached base images while VM disks depend on them.
holos images shows the guest OS metadata and hash algorithm used for each
built-in entry. holos images lock -f holos.yaml writes holos.images.lock
next to the compose file with each service’s resolved image path, format, size,
and SHA-256 digest. Use -o <path> to choose a different lockfile path.
When holos.images.lock exists next to the compose file, holos up verifies
the current resolved images against it before launching anything.
Local image paths are not trusted by name; set image_format and image_os in
compose, or --image-os with holos run, when a custom image does not match
the defaults. For private qcow2 images, keep the generated project lockfile in
source control; the threat model has a fuller checklist.
Reboot Survival
Install a systemd unit so a project comes back after host reboot:
holos install --enable
holos install --system --enable
holos install --dry-run
holos uninstall
User units go under ~/.config/systemd/user/holos-<project>.service; system
units go under /etc/systemd/system/.
If you use holos install --system --user <name>, also pass an explicit
--state-dir that the target user owns. holos keeps state directories
owner-only.
Import From virsh
holos import reads libvirt domain XML and emits a starting holos.yaml:
holos import web-prod db-prod
holos import --all -o holos.yaml
holos import --xml ./web.xml
holos import --connect qemu:///system api
It maps vCPU, memory, machine type, host CPU mode, UEFI loader, the first file
disk, extra qcow2 file disks, PCI host devices, bridged NIC intent, and USB
hostdev metadata. Unsupported or review-needed parts are reported as warnings
so you can edit the generated compose file before holos up.
Doctor
holos doctor checks the host without launching a VM:
holos doctor
holos doctor --json
It verifies Linux/KVM availability, QEMU tools, a cloud-init seed builder, SSH, optional OVMF firmware for UEFI and PCI passthrough, and state-dir writability.
Devices
holos devices --gpu lists VGA and 3D PCI devices with passthrough diagnostics:
holos devices --gpu
The output includes current driver binding, IOMMU group peers, same-slot audio
pairing, NVIDIA UEFI/ROM hints, and suggested vfio-pci setup commands. It does
not apply host changes.