Prerequisites and build
Part of the GuestKit README. Back to the documentation map.
Prerequisites
- Running GuestKit: Linux with
qemu-img,losetupandqemu-nbd(Debian/Ubuntu:qemu-utilsandutil-linux; Fedora/RHEL:qemu-imgandutil-linux). Attaching a disk needs root: GuestKit runslosetup,qemu-nbd,modprobe,mountandumountthroughsudowhen it is not already root. The web console and worker run anywhere Docker does — see Run the free web stack. - Kernel modules:
loop(raw, img, iso images) is built in or loaded on demand.nbd(qcow2, VMDK, VDI, VHD, VHDX) is loaded by GuestKit withmodprobe nbd max_part=16when it is missing; if that fails, load it yourself and make it persistent withecho nbd | sudo tee /etc/modules-load.d/nbd.conf. Containers need--privileged(orSYS_ADMINplus the loop/NBD devices). - Building from source: a stable Rust toolchain (edition 2021) and the libsystemd development headers, which the default
journal-nativefeature links. Optional features (ai,mcp,registry-write, the Windows agent) have extra requirements — see theMakefileand CONTRIBUTING. - Python bindings:
pip install zyvor-guestkitneeds nothing else; building them yourself usesbuild_python.sh. - Installing a release: the GitHub Release tarballs (
guestkit-<version>-linux-amd64.tar.gzand the static-muslbuild) holdguestkit, aguestctlsymlink,install.sh(installsqemu-utils/nbdthroughaptordnf, then verifies the binary), test scripts and legal files. There are no RPM or COPR packages and nodnf install guestkit.guestkit-qemuandvirtctl-guestkitare not in the tarball; theagent,ai,mcpandcloud-*features are not compiled into it either, see CLI reference.
Device-node permissions (Ubuntu 26.04 and other recent kernels)
On current kernels (for example Ubuntu 26.04, kernel 7.x) /dev/loopN and /dev/nbdN are created on demand and are root:disk mode 0660. A process that is not root and not in the disk group cannot open them, even though the device attached successfully. Since v1.2.10 GuestKit checks readiness through /sys/class/block/<dev>/size, which is world-readable, so the attach itself no longer times out. Reading or mounting the device still needs privilege:
-
run GuestKit as root (
sudo guestctl ...), or -
add your user to the
diskgroup (sudo usermod -aG disk $USER, then log in again), or -
install a udev rule that gives a group of your choice access, for example
/etc/udev/rules.d/99-guestkit-devices.rules:KERNEL=="loop[0-9]*", GROUP="disk", MODE="0660"KERNEL=="nbd[0-9]*", GROUP="disk", MODE="0660"then
sudo udevadm control --reload-rules. Disposable CI runners may useMODE="0666"; do not do that on a shared host, because it lets every local user read any attached disk.
What GuestKit does to the host (v1.2.11)
- Guest filesystems are mounted with
nodev,nosuidappended to the mount options, so device nodes inside an image cannot reach host devices and setuid bits are ignored. - The NBD allocation lock is
/run/lock/guestkit-nbd.lock(as root), elseguestkit-nbd.lockin$XDG_RUNTIME_DIRor/run/user/<uid>. It is never created in/tmp; if no candidate directory works, the attach fails withFailed to acquire NBD allocation lock. See Troubleshooting. - Image paths are made absolute before they reach
losetup,qemu-nbdandqemu-img. - Process disk images you do not trust in a container or VM; mounting always needs root.
Build
The .spec files in the repository (guestkit.spec, guestkit-full.spec) are for local RPM builds only; see RPM-BUILD.md. Releases do not ship RPMs.
cargo build --release # guestkit, guestctl, guestkit-qemu, virtctl-guestkit
cargo build --release --features agent,ai,mcp,cloud # optional: qga/agent-*, --ai, mcp-serve, S3/Azure/GCS sources
cargo test
make check # tests + clippy
make install # installs the guestkit binary (PREFIX=$HOME/.local to change the location)
See CONTRIBUTING and CI under .github/workflows/. docs/ and this README are authoritative.