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

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

Who does what (customers)

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

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

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 "hypersdk-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.

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 "hypersdk-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 hypersdk-guestkit → import guestkit + run_doctor / run_migrate_repair (v1.1.0+)

Run the free web stack (GHCR)

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

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

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       │
└────────────────────────────────────────────────────────────┘

Documentation

→ 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

Apache-2.0 · additional notes in docs/legal/ where applicable.