GuestKit

Offline VM intelligence and migration assurance.

📖 Feature Guide

GuestKit — Customer Feature Guide — a complete, customer-facing reference covering all 63 features across 10 areas, grounded in the product's actual capabilities. Also available as a print-ready PDF.

Customer manual (page-by-page) — getting started, admin basics, and a guide for every product surface (PDFs under docs/customer/pdf/).

Inspect QCOW2, VMDK, and RAW images without powering them on. Score boot readiness, generate hypervisor-aware fix plans, and explore disks from a carbon-themed TUI — Rust control plane, no libguestfs appliance (uses host NBD/loop for mount).

┌──────────────────────────────────────────────────────────────┐
│  Interfaces   guestkit CLI · guestctl TUI · Python bindings  │
├──────────────────────────────────────────────────────────────┤
│  Engine       Rust parsers + boot scoring · NBD/loop mount layer   │
├──────────────────────────────────────────────────────────────┤
│  Outputs      JSON · YAML · HTML · PDF · CI gate artifacts   │
└──────────────────────────────────────────────────────────────┘

Why GuestKit

Pairs with: hyper2kvm for VMware → KVM pipelines.

🆕 What's New — In-Guest Agent

GuestKit now runs inside the guest too, not just offline against the disk — same evidence schema, same fix-plan format, over the existing virtio-serial QGA channel.

• Offline Windows install, no boot required — agent-inject --windows writes the GuestKitAgent service and the virtio-serial (vioser) driver straight into the SYSTEM hive via hivex.
• Stock qemu-guest-agent gets out of the way automatically — any QEMU-GA/qemu-ga/QEMUGuestAgent service found is disabled so GuestKit answers the channel uncontended, while still speaking QGA-compatible commands so KubeVirt/libvirt notice nothing.
• Converted-image driver fix — deletes the stale cached PCI devnode so Windows re-detects the virtio-serial device and runs a full driver install on next boot, instead of staying stuck on "no driver."
• Generic QGA passthrough — guestkit-rpc exposes every agent RPC method through the standard QGA channel, so host-side automation needs only virsh qemu-agent-command.

Details, protocol reference, and the Linux path: docs/features/guest-agent.md · Protocol 1.3

Platform at a Glance

Quick Start

cargo install guestkit   # guestkit + guestctl

guestkit doctor vm.qcow2 --target proxmox --explain
# → boot assurance score · blockers · root-cause chain

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

guestctl tui vm.qcow2
# → carbon TUI · Assurance · fix-plan preview

Web console: self-hosted via GHCR or Helm. First-login credentials for packaged installs are documented in remote deploy — change defaults before exposing to a network.

Run from GHCR (prebuilt images)

The web stack is published to the GitHub Container Registry under ghcr.io/hypersdk — public images, no docker login required.

Tags: latest, vX.Y.Z (e.g. v0.3.13), per-commit SHA. Bring the whole stack up straight from GHCR:

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

Eval only: this stack runs without authentication. Do not expose it beyond localhost. For production, use deploy/docker-compose.prod.example.yml — see Docker guide.

For clusters, use the Helm chart. Full details: docs/guides/DOCKER.md → Published images.

Three Commands Before Cutover

Documentation

→ zyvor.dev/guestkit · Demo video · Full Zyvor platform

Development

See project docs for CI, testing, and contribution guidelines. Historical build summaries in the repo root are snapshots — docs/ and this README are authoritative.

License

See LICENSE or project-specific licensing files in docs/legal/.