Hyperlight

A lightweight VMM for running untrusted code in micro VMs with minimal overhead.
A Cloud Native Computing Foundation sandbox project.

Status: Hyperlight is pre-1.0. The API may change between releases, and upgrading will sometimes require code changes.

Hyperlight lets you safely run untrusted code inside hypervisor-isolated micro VMs that spin up in milliseconds, with guest function calls completing in microseconds. You embed it as a library in your Rust application, hand it a guest binary, and call functions across the VM boundary as naturally as calling a local function. To minimize startup time and memory footprint, there's no guest kernel or OS. Guests are purpose-built using the Hyperlight guest library.

• Supports KVM, MSHV, and Windows Hypervisor Platform
• No kernel or OS in the VM. Guests are regular ELF binaries written in no_std Rust or C
• Host and guest communicate through typed function calls
• Guests are sandboxed by default with no access to the host filesystem, network, etc.

Example

Host - create a sandbox, register a host function, and call into the guest:

// Create an uninitialized sandbox by giving it the path to a guest binary.
// Allocates memory but does not yet run a VM.
let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(guest_path), None)?;

// Register a host function that the guest can call. In a real app this
// might query a database, read a config, or call an external API.
// By default, guests can only print to the host.
sandbox.register("GetWeekday", || Ok("Monday".to_string()))?;

// Initialize the sandbox. Starts the VM and runs guest setup code.
let mut sandbox: MultiUseSandbox = sandbox.evolve()?;

// Call a function inside the VM
let greeting: String = sandbox.call("SayHello", "World".to_string())?;
println!("{greeting}"); // "Hello, World! Today is Monday."

Guest state persists across calls. Use snapshot() and restore() to save and reset VM memory. This avoids recreating the VM while ensuring each call starts from a clean state.

Guest (Rust) - declare host functions and expose guest functions with simple macros. Guests can also be written in C.

#[host_function("GetWeekday")]
fn get_weekday() -> Result<String>;

#[guest_function("SayHello")]
fn say_hello(name: String) -> Result<String> {
    let weekday = get_weekday()?;
    Ok(format!("Hello, {name}! Today is {weekday}."))
}

To get started, see the Getting Started guide. For more details on writing guests, see How to build a Hyperlight guest binary.

When to use Hyperlight

Hyperlight is a good fit when you need to:

• Run untrusted or third-party code with hypervisor-level isolation
• Create and tear down sandboxes in milliseconds
• Make guest function calls in microseconds
• Embed sandboxed execution directly in your application
• Build functions-as-a-service with hypervisor-level isolation
• Reuse sandboxes efficiently with snapshot and restore

Hyperlight is not designed for:

• General-purpose virtualization (use a full VMM instead)
• Running full-blown Linux guest workloads that need syscalls, networking, or filesystem access

Getting started

See docs/getting-started.md for detailed prerequisites and platform-specific setup for:

• Running Hyperlight
• Building guests

Or skip setup entirely with a codespace:

Repository Structure

Directory	Description
src/hyperlight_host	Host library - creates and manages micro VMs
src/hyperlight_guest	Core guest library - minimal building blocks for guest-host interaction
src/hyperlight_guest_bin	Extended guest library - entry point, panic handler, heap, logging, exceptions
src/hyperlight_guest_capi	C API wrapper around hyperlight_guest_bin for use via FFI
src/hyperlight_libc	C standard library for guests, built from picolibc
src/hyperlight_guest_macro	Macros for registering guest and host functions
src/hyperlight_guest_tracing	Tracing support for guests
src/hyperlight_common	Shared code used by both host and guest
src/hyperlight_component_macro	Proc macros for WIT-based host/guest bindings
src/hyperlight_component_util	Shared implementation for WIT binding generation
src/hyperlight_testing	Shared test utilities
src/schema	FlatBuffer schema definitions
src/trace_dump	Tool for dumping and visualizing trace data
src/tests	Test guest programs (Rust and C)

Related Projects

• cargo-hyperlight - Cargo subcommand for building and scaffolding Hyperlight guests
• hyperlight-wasm - Run WebAssembly modules inside Hyperlight micro VMs
• hyperlight-js - Run JavaScript inside Hyperlight micro VMs
• hyperlight-sandbox - Multi-backend sandboxing framework for running untrusted code with controlled host capabilities, with Python, .NET, and Rust SDKs
• hyperlight-unikraft - Run Linux applications (Python, Node.js, Go, Rust, C/C++) on Hyperlight micro VMs using Unikraft as the guest kernel

Contributing

See CONTRIBUTING.md.

Community

• Meetings: Every other Wednesday 09:00 PST/PDT (convert to your time). Agenda and join info in the Community Meeting Notes.
• Slack: #hyperlight on CNCF Slack (join here).
• Docs: docs/ directory
• Code of Conduct: CNCF Code of Conduct

---