API Layer

src/libkrun/src/lib.rs — C-exported interface consumed by host applications

VM lifecycle — call order

Create
krun_create_ctx() lib.rs:517
Allocates a new ContextConfig and inserts it into CTX_MAP lib.rs:432. Returns an integer context ID. Thread-safe via Mutex.
Configure — VM resources
krun_set_vm_config(ctx_id, vcpu_count, mem_mib) lib.rs:551
Sets VmConfig inside VmResources. Controls how many vCPU threads to spawn and how much guest RAM to allocate.
Configure — devices
krun_set_root_disk · krun_add_vsock · krun_set_net_cfg · … lib.rs:836
Each call mutates the appropriate sub-config inside ContextConfig. No VM exists yet — these are pure configuration.
Configure — kernel / firmware
krun_set_kernel · krun_set_initrd · krun_set_root_path lib.rs:582
Point to the kernel bundle (from krunfw), an external vmlinux, or a firmware image. Architecture determines which paths are valid.
Launch
krun_start_enter(ctx_id) lib.rs:2632
Calls build_microvm(event_manager, &vmr) then enters the EventManager run loop. Does not return until the VM shuts down. Spawns vCPU OS threads internally.

ContextConfig — runtime state lib.rs:137

ContextConfig // global CTX_MAP[ctx_id]
vmr: VmResources // aggregates all device configs
vm_config: VmConfig // vcpu_count, mem_size_mib
block_config: Option<BlockConfig>
net_config: Option<NetConfig>
vsock_config: Option<VsockConfig>
gpu_config: Option<GpuConfig>
kernel_config: KernelConfig // path, cmdline
initrd_config: Option<InitrdConfig>
display_backend: DisplayBackend // X11 | Wayland | Off
env: Vec<CString> // environment variables
args: Vec<CString> // argv for guest process

API function reference

CREATE krun_create_ctx lib.rs:517 ›
pub extern "C" fn krun_create_ctx() -> i32
Allocates a new ContextConfig with default values and inserts it into CTX_MAP. Returns the ctx_id on success, -errno on failure.
Effect: CTX_MAP.insert(id, ContextConfig::default())
CONFIG krun_set_vm_config lib.rs:551 ›
pub extern "C" fn krun_set_vm_config(ctx_id: u32, vcpu_count: u8, mem_size_mib: u32) -> i32
Sets the number of vCPU threads and the amount of guest RAM. Must be called before krun_start_enter.
Effect: ctx.vmr.vm_config = VmConfig { vcpu_count, mem_size_mib }
CONFIG krun_set_root_disk lib.rs:836 ›
pub unsafe extern "C" fn krun_set_root_disk(ctx_id: u32, c_disk_path: *const c_char) -> i32
Registers a virtio-blk device backed by a disk image file. The guest sees it as /dev/vda.
Effect: ctx.vmr.block_config = Some(BlockConfig { path, is_root: true })
CONFIG krun_add_vsock lib.rs:2438 ›
pub extern "C" fn krun_add_vsock(ctx_id: u32, tsi_features: u32) -> i32
Adds a vsock device with TSI (Transparent Socket Impersonation) flags. tsi_features controls which socket families are hijacked (INET, UNIX).
Effect: ctx.vmr.vsock_config = Some(VsockConfig { tsi_features })
CONFIG krun_set_display_backend lib.rs:1517 ›
pub extern "C" fn krun_set_display_backend(ctx_id: u32, backend: u32) -> i32
Selects the host-side display output: X11, Wayland, or offscreen rendering. Used together with the gpu feature flag.
Effect: ctx.display_backend = DisplayBackend::from(backend)
LAUNCH krun_start_enter lib.rs:2632 ›
pub extern "C" fn krun_start_enter(ctx_id: u32) -> i32
Builds the microVM, spawns vCPU threads, and enters the EventManager polling loop. This function does not return until the guest shuts down or an unrecoverable error occurs.
Effect: build_microvm() → event_manager.run() [blocking]
DESTROY krun_free_ctx lib.rs:543 ›
pub extern "C" fn krun_free_ctx(ctx_id: u32) -> i32
Removes the ContextConfig from CTX_MAP, allowing all resources to be dropped. Should be called after krun_start_enter returns.
Effect: CTX_MAP.remove(ctx_id)
flows into → VMM Builder