KUHBS Kuh Build System Qubes OS KUHBS Kuh Build System
English KUHBS Qubes OS website
Menu

Documentation

How KUHBS Automates Qubes OS Applications

Learn the exact KUHB and KUH model, four Qubes OS topologies, lifecycle gates, configured launchers, selective backups, GUI tabs, and rebuild behavior.

KUHBS automates the creation and lifecycle management of Qubes OS applications from operator-reviewed definitions. KUHBS means Kuh Build System. Kuh is German for cow. Its operating idea is “stop treating Qubes OS VMs like pets; start treating them like cattle.” Keep operator-reviewed definitions and necessary data, then replace generated VMs instead of depending on undocumented history.

KUHB, KUH, and repository

A KUHB is one trusted definition directory centered on kuhb.yml. It can describe an application, a service, infrastructure, or several related instances. Its hooks, setup fragments, templates, launchers, icons, and firewall rules are trusted local code. KUHBS validates their shape and relationships; it does not decide whether they are safe.

A KUH is one named Qubes resource managed by that KUHB. Concrete KUHs use tpl, app, ndp, or sta names. A fresh unnamed DisposableVM launched later with qvm-run --dispvm is not a managed KUH.

A repository is a trusted Git catalog of KUHB directories. Enable links one definition under /home/user/.kuhbs/my-kuhbs; it does not copy the checkout or create Qubes OS VMs.

Four topology types

A type defines the minimum topology. Advanced definitions may explicitly add compatible extra kinds.

  • AppVM (app) — a managed TemplateVM cloned from the configured external base, plus one or more persistent AppVMs based on that managed template.
  • Unnamed DisposableVM (udp) — a managed TemplateVM and one or more AppVM providers. Configured launchers create fresh unnamed runtime DisposableVMs on demand; there is no persistent udp KUH.
  • Named DisposableVM (ndp) — a managed TemplateVM, exactly one default AppVM provider, and one or more named DispVM resources. Named DispVMs do not receive setup scripts or own KUHBS path backups.
  • StandaloneVM (sta) — a temporary setup TemplateVM is prepared once, then used to create one or more StandaloneVMs. It is removed after every final VM succeeds and remains after failure for debugging.

External base TemplateVMs such as debian-13-minimal are clone sources only. Managed AppVMs depend on the KUHB-owned tpl-<id> clone, not directly on the external base.

volume_ephemeral: True resets only a VM’s volatile volume on start. It does not make persistent AppVM private data or StandaloneVM root/private data disposable.

Lifecycle

  1. Enable links an operator-reviewed definition into the active set.
  2. Create refuses pre-existing target VMs, creates resources in dependency order, applies settings, restores an available configured archive before setup, runs trusted scripts and hooks, and generates only launchers listed in the definition.
  3. Upgrade updates managed TemplateVMs and StandaloneVMs and runs explicit update hooks. It does not rerun Create-time setup scripts or regenerate launchers.
  4. Backup archives only configured absolute paths from participating tpl, app, and sta KUHs.
  5. Restore preflights the complete explicit request and overlays archives onto existing halted targets. It is not an exact whole-disk snapshot.
  6. Remove deletes managed resources and generated launchers in reverse dependency order. It does not delete backup archives. Disable then removes the active symlink.

Repository or YAML changes do not automatically change existing Qubes OS VMs. Apply Create-time setup or launcher changes through Remove and Create after reviewing and backing up what is needed.

Lifecycle admission comes from plain files under /home/user/.kuhbs/states, not from inferred live Qubes state. KUHBS has no dry run, transaction, automatic rollback, or self-healing reconciliation. Hard interruption or unsupported manual VM changes can require inspection and manual state repair.

GUI and CLI

The GUI has four tabs:

  • My KUHBS and System KUHBS show enabled definitions divided by order. They provide Edit, Create, Upgrade, Backup, Restore, and Remove actions plus applicable *-all operations.
  • Qubes OS VMs shows dom0 and referenced external base TemplateVMs. Dom0 supports KUHBS Backup/Restore; base templates participate in Upgrade.
  • Repos provides Add repo, Update repo, Edit, Enable, and Disable. Repository removal is CLI-only.

The GUI displays cached snapshots and does not continuously poll files, repositories, Qubes state, or backup storage. Restart it after out-of-band changes. Every mutating GUI action still starts a fresh CLI process that validates current configuration.

Useful commands include:

kuhbs list
kuhbs check
kuhbs create demo-app
kuhbs upgrade demo-app
kuhbs backup demo-app
kuhbs restore demo-app
kuhbs remove demo-app

Next: Installing the System KUHBs .