libkrun

Executive Summary

libkrun embeds a virtual machine monitor in the process that links it. Written in Rust, it exposes a C interface for configuring and launching workloads. It is a building block for a runtime, rather than a hosted sandbox service.^[1][2]

The important design constraint is resource authority. The project treats guest and VMM as the same security context: virtual devices can proxy access to the host. Embedders must constrain the VMM's host permissions and choose which devices to expose. A separate guest kernel does not automatically make a shared directory or GPU interface safe for a hostile guest.^[3][4]

See the container-to-VM runtimes comparison for category context. This profile distinguishes the latest tagged release from ongoing main-branch development.

---

Product Overview

The API configures VM resources, disks, shared filesystems, environment, executable, and kernel. The companion libkrunfw supplies a Linux kernel as a dynamic library; the API also accepts an external kernel and initramfs. Callers still need a guest filesystem and an update strategy.^[2][6]

These establish integrations, not deployment counts or a universal production certification.

What an embedding application must implement

The v1.19.4 C API makes the integration sequence concrete:^[2]

Passing a null environment pointer to krun_set_exec() imports the host process's environment. An agent host should deliberately construct the guest environment rather than accidentally handing it inherited API tokens. That is an integration decision, not a default credential broker supplied by libkrun.^[2]

krun_start_enter() is also not a normal function that returns after a successful job. It assumes control of the process and exits it when the VM shuts down, using the workload's exit status. A long-running application therefore needs an appropriate worker-process lifecycle around that API, including startup errors and cancellation. Check every configuration call, and free unused contexts with krun_free_ctx().^[2]

Before entering the VM, the surrounding runtime must constrain the host resources that the VMM can reach. A root_path parameter alone does not create the documented host mount boundary. This is why crun's retained container restrictions and a carefully chosen device set matter as much as the small embedding API.^[4][3]

---

Technical Architecture

Devices and networking

The v1.19.4 library includes configurable virtio devices for storage, shared files, networking, sockets, graphics, and other guest services. Its TSI socket transport and conventional virtio-net networking are alternative paths.^[4]

GPU performance and risk

The macOS stack forwards Vulkan work through virtio-gpu/Venus and host graphics libraries. Kevin Pouget's June 2025 Red Hat benchmark reported 0.52 tokens/second for a CPU configuration versus 20.84 for an updated Vulkan configuration: roughly 40× for that comparison, not a general libkrun speedup.^[11]

The test used a 48GB M4 Pro MacBook, macOS 15.5, krunkit 0.1.4, RamaLama 0.7.0/0.9.0, and primarily Llama 3.1 8B. It combined GPU enablement with llama.cpp backend changes. This review did not reproduce it, and it does not establish superiority over every other VM runtime.^[11]

Performance also does not establish security. Maintainer Sergio López's July 17, 2026 clarification identifies GPU command protocols as unsuitable for untrusted workloads, except the restricted DRM native-context path. Evaluate the specific graphics transport rather than treating all GPU support as equivalent.^[3]

Confidential-computing variants

The tagged README documents AMD SEV variants, including SEV-ES/SNP and remote attestation, and Intel TDX. It also lists a macOS EFI flavor for distribution-provided kernels. Hardware and firmware requirements differ; the released TDX documentation limits guests to one vCPU and 3,072 MiB.^[4]

Current main-branch documentation describes a newer TD-Shim path that lifts the legacy qboot limit. That should not be silently substituted for the v1.19.4 support contract.^[1]

---

Strengths

• Embedding gives the caller direct control. A C API exposes the VM configuration without requiring a separate service interface.^[2]
• Existing runtimes demonstrate composition. crun combines the VM with its container setup, and OpenShell offers it behind a compute driver.^[7][10]
• macOS acceleration has published evidence. The Red Hat experiment provides versions, hardware, workload, and test artifacts rather than only an unqualified speed claim.^[11]
• Maintenance is visible. June and July releases include filesystem identity/permission fixes; v1.19.4 specifically adjusts macOS virtio-fs security-context behavior.^[5]

---

Cautions

• Host policy remains the caller's job. Shared-file and socket interfaces must be contained by the host context; filesystem space and inode exhaustion also need host controls.^[4]
• Devices change the threat model. The maintainer recommends additional host isolation or a restricted device set for fully untrusted guests. A guest compromise does not automatically yield host root, but can expose the privileges of the linking process.^[3]
• Image handling is security-sensitive. Explicitly preserve known disk formats and trust requirements across guest writes and restarts.^[2]
• Published performance is workload-specific. A downstream startup claim cannot serve as a measured boot guarantee for every libkrun integration.
• Released and development behavior differ. Pin the library, kernel bundle, device configuration, and downstream runtime together; a main-branch feature is not necessarily in the latest tag.^[5][1]

---

What Developers Say

In discussion #538, opened February 9, 2026, developer codethief asks whether libkrun alone meets an untrusted-workload threat model. López explains that crun retains its normal container isolation before entering libkrun, combining both boundaries. Follow-up questions in July focus on deliberately exposed device interfaces. This is useful primary maintainer clarification prompted by a prospective user's concern; it is not an independent penetration test.^[3]

The current security-model documentation incorporates the underlying caution. This review did not run a VM, reproduce the GPU benchmark, or test escapes.

---

Pricing & Licensing

The firmware project's README describes source-distribution requirements for its binary package. Its licensing is distinct from the library that consumes it. There is no usage charge for the source code; compute, packaging, lifecycle management, and support are separate engineering and operating costs.^[6][1]

---

Competitive Positioning

The relevant choice is whether an application needs an embedded VM component and can own the surrounding policy. Teams seeking a complete execution service should evaluate that service's actual implementation; the presence of libkrun underneath it does not prove its isolation configuration.

Compare the profiles for Firecracker, Cloud Hypervisor, and Apple Containerization when selecting a VM stack. Microsandbox and OpenShell are useful higher-level evaluation contexts. This report does not rank their security from architecture labels alone.

---

Ideal Customer Profile

Best fit: runtime and developer-tool authors who want VM configuration in their application and can review device exposure, host restrictions, image trust, and guest updates.

Poor fit: teams expecting the library itself to supply a sandbox API, fleet operations, or a complete policy for mutually untrusted tenants.

---

Viability Assessment

The July release, September repository activity, and documented downstream integrations support an active-project assessment. Red Hat's technical articles establish engineering involvement, but do not establish a guaranteed funding level or support contract. Repository popularity also does not measure escape resistance.^{[5][1][9][10]}

---

Bottom Line

libkrun is a practical building block when VM configuration belongs inside an application. Evaluate the complete host-and-guest design, especially shared files, disk formats, network proxying, and GPU transport.

Recommended for: builders able to maintain the policy and lifecycle around an embedded VMM.

Not recommended for: assuming hardware virtualization alone limits every host resource exposed through a device.

Outlook: follow tagged releases and downstream configurations; assess emerging features against a pinned, tested deployment.

---

Research by Ry Walker Research • methodology