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.