libkrun is a Rust dynamic library that provides virtualization-based process isolation via KVM (Linux), HVF (macOS), and WHP (Windows). The 2.0 version exposes a native Rust API and an autogenerated C API (include/libkrun.h and include/libkrun_init.h) to run lightweight microVMs with configurable vCPUs, RAM, and virtio devices.
krun-init (libkrun_init, in init/) provides the guest init system (embedded PID 1 binary, OCI container config builder, and filesystem overlay injection) used for container isolation workloads.
For more details see:
- Building & Installation:
docs/building.md - Common Workload Models & Use Cases:
docs/workloads.md - VM Lifecycle & Execution:
docs/vm-lifecycle.md - Guest Init Subsystem:
docs/init.md - Networking Architecture:
docs/networking.md - Security Model:
docs/security-model.md - Bindings Generation (ffier):
docs/bindings-generation.md
All builds go through the Makefile, which handles feature flags, platform detection, and sysroot management for cross-compilation. Direct cargo build skips that plumbing.
# Release build (minimal — no optional devices)
make
# Release build with common optional devices
make BLK=1 NET=1 GPU=1 INPUT=1
# Debug build
make debug
# TEE variants (mutually exclusive with each other and GPU/INPUT)
make SEV=1 # AMD SEV — produces libkrun-sev.so
make TDX=1 # Intel TDX — produces libkrun-tdx.so
# Other optional features
make VHOST_USER=1
make VIRGL_RESOURCE_MAP2=1
# After building, install to /usr/local (or PREFIX=...) with matching feature options
make install
make PREFIX=$HOME/.local installThe complete CI clippy matrix is documented in the testing skill. Rust formatting is checked with:
cargo fmt -- --check- API Entry Point & VMM Core:
src/libkrun(Rust API insrc/libkrun/src/api/, VMM engine insrc/libkrun/src/vmm/) - Virtio Device Models:
src/devices(console, block, fs, net, vsock, gpu, input, vhost-user) - Guest Init Subsystem:
init/(init-binary,init-blob,init-blob-via-cdylib) - Hypervisor Backends: Linux KVM (
src/libkrun/src/vmm/linux/), macOS HVF (src/hvf), Windows WHP (src/whp)
C headers (include/) and JSON schemas are autogenerated from Rust source annotation. Never hand-edit generated C headers or JSON schemas.
Regenerate after modifying exported APIs:
make gen-libkrun-bindingsmake gen-init-blob-bindings
For more details see: docs/bindings-generation.md
See: docs/vm-lifecycle.md
- New tests are added when necessary.
- Documentation is added or updated when necessary.
- Linting and formatting has been done.
- All of the tests pass.
- The commit structure follows what's described in [Commit structure](### Commit structure).
- Format:
<subsystem>: <title>— e.g.,virtio/blk: add print_text() function - Commits must be self-contained, compile, and pass tests independently
- Sign all commits with
git commit -s(DCO requirement) - Agent attribution format:
Assisted-by: <Agent-tool>: <model-name>- e.g.,Assisted-by: Claude Code: sonnet-4.6,Assisted-by: Cursor: codex-5.3. Do not useCo-authored-by. - Commit messages should be concise and written in the imperative mood. Small, focused commits are preferred.
- Code must be self-explanatory and the main source of reference. Do not write comments unless the code is counter-intuitive and cannot be clarified through better naming or structure. When a comment is necessary, it must explain why, never what.
- No error handling for impossible scenarios.
- Avoid checking for empty input when calling a function if the function already handles the base case well (e.g. empty input is noop).
- Use
useimports instead of inline full paths. One level of qualitifation is fine when it clarifies what something is (e.g.,log::trace!,fs::read_to_string()), but don't use longer paths likestd::process::Command::new(...)orcrate::foo::bar::baz()-- import withuseinstead.
- Linux x86_64 / aarch64: primary targets, full feature support (KVM)
- Linux riscv64: experimental (KVM)
- macOS aarch64: supported (HVF), GPU works
- Windows x86_64: upcoming (WHP)
The guest ISA always matches the host ISA — KVM, HVF, and WHP use hardware virtualization, not emulation.
- Linux (x86_64, aarch64, riscv64): primary guest OS
- FreeBSD (same arch as host): experimental; requires building the FreeBSD init with
make BUILD_BSD_INIT=1