hypersdk-guestkit 0.3.9

Pure Rust VM disk toolkit with beautiful output, Windows registry parsing, and VM migration support - Python bindings

GuestKit
_{Offline VM intelligence & migration assurance — powered on zyvor.dev}

▶ Watch demo  ·  zyvor.dev/demo  ·  Contact sales

---

GuestKit answers the question every migration team asks too late: will this VM actually boot on the target?

Inspect QCOW2, VMDK, or RAW images without powering them on — using GuestKit's pure Rust disk engine (not libguestfs). Score boot probability, generate hypervisor-aware migration plans, export executable fix plans, and explore disks from a carbon-themed TUI — all in Rust, with structured JSON/YAML/HTML/PDF for CI.

Part of the open-source stack on zyvor.dev · pairs with hyper2kvm for VMware → KVM pipelines.

Three commands before cutover

cargo install guestkit   # guestkit + guestctl

guestkit doctor vm.qcow2 --target proxmox --explain
# → 82% boot probability · blockers · root-cause chain

guestkit migrate-plan vm.vmdk --target proxmox --export plan.yaml
# → migration score · driver injections · executable fix plan

guestctl tui vm.qcow2
# → carbon TUI · Assurance (doctor) · fix-plan preview · offline files

Without GuestKit	With GuestKit
Boot every VM to “just check”	Inspect offline in place (pure Rust — no libguestfs appliance)
Shell scripts over guestfish	GuestKit assurance APIs + structured export
Migration surprises at power-on	doctor score before cutover
Manual runbooks for fleet drift	fleet analyze · forensic-diff

TUI — control plane in your terminal

guestctl tui is a multi-view dashboard for incident response and deep dives — no VM boot required.

Navigation	Two-tier tabs: Overview · System · Security + views in group · Ctrl+P jump menu
Keys	Tab · { } groups · : palette · Ctrl+Shift+P search · a → Assurance from dashboard
Assurance	d doctor · t target · p plan preview · e export YAML (Security group)
Views	Dashboard, issues, packages, services, files, storage, profiles, Assurance, topology, …
Fleet	guestctl tui img.qcow2 --fleet ./images/ — sidebar, N / P switch disks
Theme	Carbon graphite + orange accent — config in ~/.config/guestkit/tui.toml

→ TUI guide

Features

Doctor	Bootability % on KVM/Proxmox/cloud — blockers, warnings, --explain
Migrate-plan	Target-aware score, drivers, downtime · --export fix plan YAML/JSON
Inspect	OS, disks, network, packages, DBs, web servers, users, kernel, security
Windows	--profile windows-migration — BitLocker, VirtIO, hypervisor remnants
Policy	Expression DSL (bootability.score >= 80) · guestkit policy check
Fleet	Cluster identical VMs, snowflakes, migration blockers
Forensic diff	Security drift between two snapshots
Repair	guestkit repair --fix boot — plan apply + post-check
Fix plans	Preview → export bash/Ansible → apply with backup/rollback
Shell	REPL: ls, cat, grep, explore, upload/download, optional ai
Batch	inspect-batch --parallel 8 with cache
SBOM/CVE	SPDX/CycloneDX + OSV lookup (offline cache)
Cloud	S3/Azure/GCS sources (--features cloud-s3, …)
Python	PyO3 — same API in pipelines
AI (opt)	Narration on deterministic evidence (--features ai)

Aliases: guestkit (primary) · guestctl (kubectl-style) — same binary, your choice of name.

Quick start

# Install
cargo install guestkit
# pip install hypersdk-guestkit

# Assurance workflow
guestkit doctor disk.qcow2 --target kvm -o json
guestkit migrate-plan disk.vmdk --target proxmox --export migration.yaml
guestkit repair disk.qcow2 --fix boot --dry-run

# Inspect & report
guestkit inspect disk.qcow2 --profile security --export report.html
guestkit fleet analyze ./vms/ -o json

# Explore
guestctl tui disk.qcow2
guestkit interactive disk.qcow2
guestkit explore disk.qcow2 /etc

Docker: docker build -t guestkit . · Docker guide
Tarball: GitHub Releases or remote package script

Command cheat sheet

Goal	Command
Boot gate	guestkit doctor IMAGE --target kvm --explain
Migration + plan file	guestkit migrate-plan IMAGE --target proxmox --export plan.yaml
Policy	guestkit policy check IMAGE --policy policy.yaml
TUI	guestctl tui IMAGE
Security report	guestkit inspect IMAGE --profile security -o html
Fleet	guestkit inspect-batch ./vms/*.qcow2 --parallel 4

How it fits your stack

flowchart LR
  subgraph disks [Offline disks]
    IMG[QCOW2 / VMDK / RAW]
  end
  subgraph gk [GuestKit]
    DOC[doctor]
    MIG[migrate-plan]
    INS[inspect / repair]
    TUI[tui]
  end
  subgraph out [Outputs]
    PLN[fix plans]
    RPT[JSON HTML PDF]
    H2K[hyper2kvm]
  end
  IMG --> DOC --> MIG --> PLN
  IMG --> INS --> RPT
  IMG --> TUI
  PLN --> H2K
  RPT --> CI[CI / CMDB]

Typical flows

• Migration — doctor → migrate-plan --export → repair --fix boot → hyper2kvm
• Incident — guestctl tui on a clone; production stays off
• Compliance — profiles → HTML/PDF for auditors
• Automation — inspect -o json → jq → ticketing

Python (30 seconds)

from guestkit import Guestfs

with Guestfs() as g:
    g.add_drive_ro("vm.qcow2")
    g.launch()
    for root in g.inspect_os():
        print(g.inspect_get_distro(root), g.inspect_get_hostname(root))

→ examples/python/ · Python guide

Documentation

Topic	Link
Index	docs/INDEX.md
Migration assurance	migration-assurance.md
TUI	tui-enhancements.md
CLI reference	quick-reference.md · cli-guide.md
Quick reference	quick-reference.md
Fix plans	fix-plans.md
VM migration	vm-migration.md

Project layout

src/
├── cli/          # commands, TUI, shell, migrate/plan
├── evidence/     # EvidenceSnapshot (digital twin)
├── boot/         # bootability engine
├── fleet/        # clustering & snowflakes
├── guestfs/      # disk inspect & file ops
└── python.rs     # PyO3

Roadmap

• ✅ Migration assurance (doctor, migrate-plan, repair --fix boot)
• ✅ TUI Assurance view, fix-plan preview, palette & global search
• ✅ TUI two-tier navigation, scrollable jump menu & help
• ✅ Fix plan export & apply (CLI); TUI export + read-only preview
• 🔄 Windows EFI / boot diagnostics
• 🔮 Deeper cloud pull & plugin profiles

Full roadmap · Changelog

Contributing

git clone https://github.com/hypersdk/guestkit && cd guestkit
cargo test && cargo clippy && cargo fmt

Contributing guide · Issues · Discussions

License

Document	What it covers
LICENSE	Apache-2.0 — GuestKit source code (copyright ZyvorAI Labs Private Limited)
NOTICE	Copyright and attribution for Apache 2.0 distributions
ZYVOR-COMPANY-TERMS.md	Zyvor brand, binaries, and zyvor.dev distribution — accept on deploy/install

Apache 2.0 is permissive with a patent grant. ZyvorAI Labs Private Limited owns GuestKit.

Zyvor company terms apply when you use Zyvor-built customer bundles or ./scripts/deploy-remote.sh / ./scripts/package-binary-remote.sh (type ACCEPT or set GUESTKIT_ZYVOR_ACCEPT=1). Enterprise: [e-mail] · General: [e-mail].

Company reference: docs/legal/CORPORATE.md.

---

GuestKit is the open-source guest-disk layer of the HyperSDK Platform from Zyvor AI Labs.

Demo · Contact · [e-mail] · [e-mail] · CE vs Enterprise · Enterprise guide

_{HyperSDK · hyper2kvm · GuestKit · v9s · PacketWolf — full suite}