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

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 "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/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:

Download the trial asset from GitHub Releases (guestkit-enterprise-*-trial-linux-amd64.tar.gz)
Verify the .sha256, extract, run ./install.sh
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	hypersdk-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.

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.github		.github
benches		benches
crates		crates
deploy		deploy
docs		docs
examples		examples
integration		integration
k8s		k8s
node_modules		node_modules
packaging/vmtools		packaging/vmtools
policies		policies
presentations		presentations
proptest-regressions/core		proptest-regressions/core
scripts		scripts
src		src
templates		templates
tests		tests
website		website
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Cargo.toml.workspace		Cargo.toml.workspace
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
Makefile.docker		Makefile.docker
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
action.yml		action.yml
build_python.sh		build_python.sh
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
guestkit-full.spec		guestkit-full.spec
guestkit.pyi		guestkit.pyi
guestkit.spec		guestkit.spec
install.sh		install.sh
pyproject.toml		pyproject.toml
test_colors_demo.sh		test_colors_demo.sh
test_results.txt		test_results.txt

Navigation Menu

Repository files navigation

GuestKit

The cutover problem — solved offline

Who does what (users)

End-to-end: certify → run → manage

Libvirt / virsh → suite map

See it in action

Why teams switch

60-second quick start

Python (v1.1.0+)

h2kvm integration

What you can do

Assure · plan · certify · launch

Repair offline (no boot required)

Local VM lifecycle, disk tools, and cutover

Live control · platform · AI

Run the free web stack (GHCR)

Open source vs Enterprise

Open source — free under Apache-2.0

Enterprise — buy for programs

30-day Enterprise trial (binary)

Platform layout

Documentation

Development

License

Open source (Apache-2.0)

Enterprise

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

GuestKit

The cutover problem — solved offline

Who does what (users)

End-to-end: certify → run → manage

Libvirt / virsh → suite map

See it in action

Why teams switch

60-second quick start

Python (v1.1.0+)

h2kvm integration

What you can do

Assure · plan · certify · launch

Repair offline (no boot required)

Local VM lifecycle, disk tools, and cutover

Live control · platform · AI

Run the free web stack (GHCR)

Open source vs Enterprise

Open source — free under Apache-2.0

Enterprise — buy for programs

30-day Enterprise trial (binary)

Platform layout

Documentation

Development

License

Open source (Apache-2.0)

Enterprise

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages