Skip to content

Latest commit

 

History

History
108 lines (76 loc) · 4.94 KB

AGENTS.md

File metadata and controls

108 lines (76 loc) · 4.94 KB

Project description

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:

Build commands

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 install

Lint and format

The complete CI clippy matrix is documented in the testing skill. Rust formatting is checked with:

cargo fmt -- --check

Key code locations

  • API Entry Point & VMM Core: src/libkrun (Rust API in src/libkrun/src/api/, VMM engine in src/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)

Bindings & FFI (ffier)

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-bindings
  • make gen-init-blob-bindings

For more details see: docs/bindings-generation.md

How a VM starts

See: docs/vm-lifecycle.md

Pull Request expectations

  • 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).

Code Quality

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 use Co-authored-by.
  • Commit messages should be concise and written in the imperative mood. Small, focused commits are preferred.

Rust coding style

  • 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 use imports 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 like std::process::Command::new(...) or crate::foo::bar::baz() -- import with use instead.

Platform support

Host platforms (where libkrun runs as a library)

  • 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)

Guest platforms (what runs inside the VM)

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