Skip to main content

60-second quick start

Part of the GuestKit README. Back to the documentation map.

# v1.3.0 GitHub Release (tar.gz only, no RPM/COPR) — crates.io `guestkit` is still 0.3.2
curl -fsSL -O https://github.com/zyvorai/zyvor-guestkit/releases/download/v1.3.0/guestkit-1.3.0-linux-amd64.tar.gz
tar xzf guestkit-1.3.0-linux-amd64.tar.gz && cd guestkit-1.3.0-linux-amd64
./install.sh # host deps (qemu-utils, nbd); run ./guestkit in place or add it to PATH
export PATH="$PWD:$PATH"

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 (build from source: not in the tarball)

# 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 (Debian/Ubuntu qemu-utils), plus the loop and nbd kernel modules. Attaching and mounting a disk needs root (run as root, or GuestKit uses sudo). On Ubuntu 26.04 device nodes are created on demand and are root:disk 0660; see device-node permissions.

Python (v1.1.0+)​

Same assurance engine as the CLI — on PyPI and used by h2kvm offline fixer:

pip install zyvor-guestkit
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
# Optional inject_json= (hostname, network, users, first-boot). CLI has no inject flag.

See python-bindings.md and examples/python/assurance_doctor.py.

You want…Go here
First hourGetting started
Python assurance APIspython-bindings.md
Assured QEMU launchqemu-runtime.md
h2kvm pipelinehyper2kvm-integration.md
Remote SSH deployDEPLOY-REMOTE.md
Cheat sheetQuick reference
Full feature mapUser feature guide
Open source vs Enterprisece-vs-enterprise.md