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

• 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

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/hyperlightguest_bin | Extended guest library - entry point, panic handler, heap, logging, exceptions | | src/hyperlightguestcapi | C API wrapper around hyperlightguest_bin for use via FFI | | src/hyperlight_libc | C standard library for guests, built from picolibc | | src/hyperlightguest_macro | Macros for registering guest and host functions | | src/hyperlightguest_tracing | Tracing support for guests | | src/hyperlight_common | Shared code used by both host and guest | | src/hyperlightcomponent_macro | Proc macros for WIT-based host/guest bindings | | src/hyperlightcomponent_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