GuestKit

Offline VM intelligence. Migration assurance you can prove.
Score boot readiness before power-on · repair disks offline · certify cutover with a Passport

Product · Demos · Suite path · Quick start · h2kvm · FluxVM · Wiki · Open source vs Enterprise · 30-day Enterprise trial · Book a demo

---

The cutover problem — solved offline

Every hypervisor exit fails the same way: you discover the disk was broken at 2am, in the cutover window, after power-on.

GuestKit reads the disk while the guest is off, scores first-boot probability 0–100, and emits a reviewable fix plan — no appliance daemon, no “just try it and hope.”

  disk.qcow2 / .vmdk / .vhdx / .vhd / .vdi / .raw
                    │
                    ▼
         ┌──────────────────────┐
         │  Pure-Rust engine    │──►  doctor 0–100 + blockers
         │  NBD / loop mount    │──►  migrate-plan YAML
         └──────────────────────┘──►  Passport · repair · CI gate
                    │                 guestkit-qemu (assured launch)
      CLI · TUI · QEMU · Python · Web · Agent · GitHub Action

70+ commands	6 disk formats
**0 appliance daemons	8 migration targets
Apache-2.0	Used in CI, labs, and hypervisor-exit programs

Certify with GuestKit → run & manage with FluxVM → convert & deploy with h2kvm → operate on Zeus OS.

---

Who does what (users)

You need…	Use
Score / repair a disk before power-on	This repo (GuestKit)
Boot the qcow2, give it a network, SSH, TTL, pause/resume	FluxVM
Hypervisor → KVM convert + import	h2kvm

GuestKit does not own production networking (TAP/bridge/netns/DHCP) or disposable fleet lifecycle. That is FluxVM. Keep GuestKit focused on offline intelligence.

End-to-end: certify → run → manage

# ── 1. Certify & repair (GuestKit) ─────────────────────────────
guestkit doctor disk.qcow2 --target kvm --explain
guestkit plan generate disk.qcow2 -p virtio-initramfs -o virtio.yaml
guestkit plan apply virtio.yaml --vm disk.qcow2 --yes   # as needed
guestkit gate --image disk.qcow2 --fail-below 80        # CI / cutover gate
guestkit passport emit disk.qcow2 --target kvm -o passport.json

# ── 2. Run & manage (FluxVM) ─────────────────────────────────
# Point FluxVM at the same (or repaired) qcow2 — see FluxVM README.
# Overlay keeps the base disk untouched; pick a network mode:
#
#   user     — lab SSH via hostfwd (simplest)
#   tap      — join existing bridge (LAN DHCP)
#   tap+netns— known guest IP + NAT (isolated)
#
#   fluxvm create --spec my-vm.json
#   fluxvm get <id>          # status + guest_ip when netns
#   fluxvm exec <id> -- uptime
#   fluxvm delete <id>

Docs: VM lifecycle / suite split · FluxVM · Passport handoff

Libvirt / virsh → suite map

Old habit	Replacement
virsh define / start / destroy (host-local QEMU)	FluxVM create / get / delete
libvirt NAT / bridge DHCP / guest IP	FluxVM user / tap+bridge / tap+netns (guest_ip)
virsh qemu-agent-command	guestkit qga (or fluxvm exec with vsock agent)
“Will it boot?” by virsh start	guestkit doctor / passport / gate before FluxVM create
KubeVirt / OpenShift domains	virtctl / Machina (unchanged)

Full map: virsh-to-guestkit.md.

---

See it in action

▶ CLI & TUI Offline VM intelligence, explained	▶ Web Dashboard — Overview Server Image Vault, live KubeVirt cluster
▶ Web Dashboard — Deep Dive Sources, live cluster, one-click intelligence	▶ Machina × GuestKit Live Linux guest agent — health, TRIM, netplan, services

Recorded live against real deployments — no staged screenshots.

---

Why teams switch

Before GuestKit	With GuestKit
“Will it boot?” answered at power-on	Offline doctor score + root-cause chain
guestkit scripts and tribal knowledge	Structured plans, JSON/YAML, CI gates
Surprises on cutover weekend	Hypervisor-aware migrate-plan + day-0 packs
No audit trail MTV / virt-v2v can skip	Signed Cutover Passport
Fleet drift invisible until outage	fleet analyze / watch, forensic diff, policy-as-code
Migration order guessed by hand	fleet wave-plan — dependency-aware waves
Deep inspect needs a running guest	Carbon TUI + in-guest agent over QGA
Assured first boot still means hand-built QEMU argv	guestkit-qemu plans/runs from the same evidence gate
Live guest ops still mean virsh qemu-agent-command	guestkit qga / agent-call speak the QGA socket directly

---

60-second quick start

cargo install guestkit          # guestkit + guestctl + guestkit-qemu

guestkit doctor vm.qcow2 --target proxmox --explain
guestkit migrate-plan vm.vmdk --target kvm --export plan.yaml
guestkit passport emit vm.qcow2 --target kvm -o passport.json
guestctl tui vm.qcow2           # Assurance · preview · export
guestkit-qemu plan vm.qcow2 --json   # assurance → QEMU definition

# Shrink an oversized-but-mostly-empty disk to its real footprint before import
guestkit shrink disk.qcow2 --dry-run                     # report only
guestkit shrink disk.qcow2 --min-ratio 3 --headroom-pct 20

CI gate — same score, no CLI install step:

- uses: zyvorai/guestkit@v1
  with:
    disk: vm.qcow2
    target: kvm
    fail-below: '80'

Targets: kvm · proxmox · qemu · kubevirt · aws · azure · gcp · hyperv

Host needs: Linux with qemu-img, losetup, and qemu-nbd (mount/repair may need root).

Python (v1.1.0+)

Same assurance engine as the CLI — on PyPI and used by h2kvm offline fixer:

pip install "zyvor-guestkit>=1.1.0"

import guestkit

guestkit.run_doctor("vm.qcow2", target="kvm", explain=True)
guestkit.run_migrate_repair("vm.qcow2", target="kvm", apply=False)  # dry-run
guestkit.run_migrate_repair("vm.qcow2", target="kvm", apply=True)   # apply fixes

See python-bindings.md and examples/python/assurance_doctor.py.

You want…	Go here
First hour	Getting started
Python assurance APIs	python-bindings.md
Assured QEMU launch	qemu-runtime.md
h2kvm pipeline	hyper2kvm-integration.md
Remote SSH deploy	DEPLOY-REMOTE.md
Cheat sheet	Quick reference
Full feature map	User feature guide
Open source vs Enterprise	ce-vs-enterprise.md

---

h2kvm integration

GuestKit provides offline disk intelligence; h2kvm provides hypervisor-to-KVM conversion and deploy.

  guestkit doctor / migrate-plan     ← pre-flight score + fix plan
              │
              ▼
  h2kvmctl local --backend guestkit  ← convert + run_migrate_repair
              │
              ▼
  libvirt · KubeVirt · OpenStack

# GuestKit from PyPI; h2kvm from GitHub Release
pip install "zyvor-guestkit>=1.1.0"
pip install https://github.com/zyvorai/h2kvm/releases/download/v1.1.0/h2kvm-1.1.0-py3-none-any.whl

# Pre-flight
guestkit doctor source.vmdk --target kvm --explain

# Convert + offline repair
h2kvmctl local --vmdk source.vmdk --to-output out.qcow2 --backend guestkit

Deploy both to a lab host:

GUESTKIT_ZYVOR_ACCEPT=1 ./scripts/deploy-remote.sh HOST user --quick --key   # GuestKit CLI
cd /path/to/h2kvm && ./scripts/deploy-remote.sh HOST user --keep-sources      # h2kvm

Full guide: hyper2kvm-integration.md · h2kvm README

---

What you can do

Assure · plan · certify · launch

guestkit doctor vm.qcow2 --target proxmox --explain
guestkit migrate-plan vm.vmdk --target proxmox --export plan.yaml
guestkit passport emit vm.qcow2 --target kvm -o passport.json
guestkit passport verify passport.json --fail-below 80
guestkit-qemu run vm.qcow2 --min-boot-score 80 --qmp-socket /run/guestkit/vm.qmp

Repair offline (no boot required)

guestkit plan generate disk.qcow2 -p linux-ssh --user ubuntu --key-file ~/.ssh/id_ed25519.pub
guestkit rescue disk.qcow2 -o enable-ssh
guestkit rescue disk.qcow2 -o fix-grub --force
guestkit rescue win.qcow2 -o reset-password --user Administrator --password '…'
guestkit plan apply plan.yaml --vm disk.qcow2 --yes     # backups + rollback

Local VM lifecycle, disk tools, and cutover

guestkit vm define demo disk.qcow2 --memory-mb 4096 --vcpus 2
guestkit vm start demo && guestkit vm status demo
guestkit img check disk.qcow2 --repair
guestkit domain-disks /etc/libvirt/qemu/web01.xml
guestkit firstboot win.qcow2 --hostname web01 --run 'echo hi'
guestkit gate --image disk.qcow2 --fail-below 80 --rego policies/cutover.rego
guestkit sbom-diff before.spdx.json after.spdx.json --fail-on-drift
virtctl-guestkit guestfs -n ns pvc

• guestkit vm — local QEMU lifecycle (define/start/pause/resume/destroy) for a lab or single box; production run/network/TTL is FluxVM's job — features/vm-runtime.md
• guestkit img / domain-disks / firstboot — qemu-img wrapper, libvirt/YAML domain disk parsing, virtio-win plan, first-boot gate — user-guides/img-firstboot.md
• Cutover bundle — gate + SELinux/sysprep/BitLocker prep + cloud cutover profiles/Rego policy checks — user-guides/cutover-bundle.md, user-guides/cutover-prep.md
• Passport handoff / fleet quarantine — hand a passport to an h2kvmctl job, quarantine a fleet — user-guides/handoff-quarantine.md
• Rescue dry-run Action + sbom-diff — forensic-diff SBOM attach, CI extras — devops/10-rescue-sbom-ci.md
• virtctl-guestkit guestfs — drop-in for virtctl guestfs on a PVC, backed by GuestKit not libguestfs — features/virtctl-guestkit.md

Live control · platform · AI

• In-guest agent (Linux + Windows) over virtio-serial / QGA — inject offline, then agent-proxy / agent-call
• guestkit qga — drop-in for virsh qemu-agent-command (direct unix socket; no virsh by default) — virsh-to-guestkit.md
• Optional AI (--features ai) — read-only tool-calling over the offline evidence snapshot; MCP server via --features mcp
• KubeVirt boot-inspect hooks and Guest Control Fabric
• Web console + worker on GHCR · Helm under deploy/helm/zyvor
• Python: pip install zyvor-guestkit → import guestkit + run_doctor / run_migrate_repair (v1.1.0+)

---

Run the free web stack (GHCR)

Public images under ghcr.io/zyvorai — no docker login required.

Image	Role
ghcr.io/zyvorai/zyvor-ui	Web console — Image Vault, KubeVirt cluster
ghcr.io/zyvorai/zyvor-api	API
ghcr.io/zyvorai/guestkit-worker	Disk-inspection worker

docker compose -f deploy/docker-compose.ghcr.yml pull
docker compose -f deploy/docker-compose.ghcr.yml up -d
open http://localhost:8088

Eval only — unauthenticated stack. Do not expose beyond localhost.
Production: deploy/docker-compose.prod.example.yml · Docker guide · Helm

---

Open source vs Enterprise

Open source — free under Apache-2.0 This repo · personal, lab, and commercial production Full offline doctor, migrate-plan, repair, fleet, policy CLI · TUI · Python · self-hosted web/workers GitHub Action Passport gate Free zyvor-ui Image Vault dock Best for labs, CI, small fleets, and production without Enterprise extras

Enterprise — buy for programs zyvor.dev/guestkit Same engine — not a locked doctor Command Center · Portfolio · Assurance Image Vault (inspect/doctor/repair/migrate-plan, sources, batch, launch YAML, agent) Migration Factory · Passport Authority (+ JSON download) Dependencies · Policies · Compliance · Reports (JSON/CSV) Sites & Workers · KubeVirt · Integrations · Copilot · Admin OIDC / RBAC / audit · mobile console · command palette SLA · air-gap · hypervisor exit workshops Pipeline: HyperSDK → h2kvm → GuestKit → Zeus OS → PacketWolf

One failed first-boot weekend costs more than the license.
Enterprise turns offline scores into shared, gated decisions your board can fund.

30-day Enterprise trial (binary)

Try the control plane before you buy — same packaging pattern as Veyron:

1. Download the trial asset from GitHub Releases (guestkit-enterprise-*-trial-linux-amd64.tar.gz)
2. Verify the .sha256, extract, run ./install.sh
3. Keep bundled trial.token next to the install — after 30 days email sales@zyvor.dev

Full install instructions →

Full feature matrix (every screen) → · What Zyvor sells → · Book a demo · Pricing · sales@zyvor.dev

---

Platform layout

┌────────────────────────────────────────────────────────────┐
│  guestkit CLI · guestctl TUI · guestkit-qemu · Python · Web │
├────────────────────────────────────────────────────────────┤
│  Rust evidence · boot scoring · fix-plan · QEMU/VirtIO plan │
├────────────────────────────────────────────────────────────┤
│  JSON · YAML · HTML · PDF · Passport · CI exit codes       │
└────────────────────────────────────────────────────────────┘

Layer	In this repo
Engine	Pure-Rust parsers + evidence schema · NBD/loop (src/, crates/)
CLI / TUI	guestkit · guestctl — doctor, passport, fleet, rescue
QEMU runtime	guestkit-qemu — assured plan/run + QMP (qemu-runtime.md)
Agent / QGA	Linux + Windows · agent-inject / agent-proxy / guestkit qga (virsh-to-guestkit.md)
Python	zyvor-guestkit — run_doctor, run_migrate_repair (v1.1.0+)
h2kvm	hyper2kvm-integration.md — convert/deploy partner
FluxVM	zyvorai/fluxvm — run/manage certified qcow2s (network, TTL)
K8s	KubeVirt hooks · k8s/
Web / worker	GHCR images · deploy/

---

Documentation

Goal	Document
Operator wiki	zyvorai/guestkit/wiki
Docs home	docs/README.md · INDEX
DevOps runbooks	docs/devops
Feature guide	guestkit-user-feature-guide.md
Docker / GHCR	DOCKER.md
Remote deploy	DEPLOY-REMOTE.md
h2kvm integration	hyper2kvm-integration.md
QEMU / VirtIO runtime	qemu-runtime.md
Dump virsh → GuestKit	virsh-to-guestkit.md
Architecture	overview
Changelog / roadmap	CHANGELOG · roadmap

→ zyvor.dev/guestkit · docs · blog

---

Development

cargo build --release
cargo test

See CONTRIBUTING and CI under .github/workflows/. docs/ and this README are authoritative.

---

License

Open source (Apache-2.0)

This repository is licensed under the Apache License, Version 2.0. You may use, modify, and run it for personal, lab, and commercial production use at no charge, subject to Apache-2.0 (preserve notices / NOTICE where required). See NOTICE and docs/legal/ where applicable.

Enterprise

Production support, SLAs, and Zyvor Enterprise products are licensed separately. Contact sales@zyvor.dev or see zyvor.dev.