ZyvorAI Labs · Customer Documentation

GuestKit

Getting Started
2026-08-29
zyvor.dev · Confidential — for licensed customers

Offline VM intelligence — inspect disks without booting, score boot readiness, and produce hypervisor-aware fix plans.

What you need

Requirement Notes
Linux host qemu-img / losetup / qemu-nbd (qemu-utils)
Disk image qcow2 / vmdk / raw (guest shut down for writes)
Optional UI :8088 zyvor-ui via GHCR compose

1. Install

cargo install guestkit
# or install the release binary for your OS
qemu-img --version
guestkit version

2. First doctor run

guestkit doctor /path/to/disk.qcow2 --target kvm --explain

Optional TUI: guestctl tui /path/to/disk.qcow2.

3. Orient yourself

  1. Onboarding — Getting Started, CLI Guide, Interactive Mode, TUI
  2. Inspection — Inspect, Filesystems, Packages, Network, Files
  3. Assurance — Doctor, Migration Plan, Policy, Passport, Fleet
  4. Fix — Fix Plans, Repair / Rescue

Next steps

GuestKit is primarily CLI + TUI, with an optional web Image Vault.

Surfaces

Surface How to open
CLI guestkit <cmd> / guestctl <cmd>
TUI guestctl tui IMAGE (aliases: guestkit tui, guestkit ui)
Interactive REPL guestkit interactive IMAGE
File explorer guestkit explore IMAGE [/path]
Optional web GHCR compose → http://<host>:8088

TUI keys (Assurance)

Key Action
d Doctor
t Cycle migration target
p Preview plan
e Export plan
: Command palette
h / ? Help

Browse vs act

Inspect / doctor / export are safe. Repair, plan apply, and rescue mutate disks — shut down the guest, dry-run first, keep a backup.

Related

End-to-end GuestKit jobs. Prefer CLI; optional TUI / web where noted.

First-hour assurance

  1. Install CLI (cargo install guestkit or release binary); confirm qemu-img
  2. Doctor — guestkit doctor IMAGE --target kvm --explain
  3. Migration Plan — export a FixPlan YAML
  4. Optional: TUI — guestctl tui IMAGE

Inspect without booting

  1. Inspect
  2. Filesystems → mount in Interactive Mode if needed
  3. Packages / Network / Guest Files

Repair then re-score

  1. Doctor blockers
  2. Repair dry-run → apply (guest shut down)
  3. Or Fix Plans — preview → apply
  4. Re-run Doctor / passport verify

Fleet wave

  1. Fleet — fleet analyze / wave-plan
  2. Forensic Diff or fleet watch for drift
  3. Policy Gate before cutover

Related