Hyperlight

<div align="center"> <h1>Hyperlight</h1> <img src="https://raw.githubusercontent.com/hyperlight-dev/hyperlight/refs/heads/main/docs/assets/hyperlight-logo.png" width="150px" alt="hyperlight logo"/> <p><strong>Hyperlight is a lightweight Virtual Machine Manager (VMM) designed to be embedded within applications. It enables safe execution of untrusted code within <i>micro virtual machines</i> with very low latency and minimal overhead.</strong> <br> We are a <a href="https://cncf.io/">Cloud Native Computing Foundation</a> sandbox project. </p> </div>

Note: Hyperlight is a nascent project with an evolving API and no guaranteed support. Assistance is provided on a best-effort basis by the developers.

---

Overview

Hyperlight is a library for creating micro virtual machines — or sandboxes — specifically optimized for securely running untrusted code with minimal impact. It supports both Windows and Linux, utilizing Windows Hypervisor Platform on Windows, and either Microsoft Hypervisor (mshv) or KVM on Linux.

These micro VMs operate without a kernel or operating system, keeping overhead low. Instead, guests are built specifically for Hyperlight using the Hyperlight Guest library, which provides a controlled set of APIs that facilitate interaction between host and guest:

• The host can call functions implemented and exposed by the guest (known as guest functions).
• Once running, the guest can call functions implemented and exposed by the host (known as host functions).

By default, Hyperlight restricts guest access to a minimal API. The only host function available by default allows the guest to print messages, which are displayed on the host console or redirected to stdout, as configured. Hosts can choose to expose additional host functions, expanding the guest’s capabilities as needed.

Below is an example demonstrating the use of the Hyperlight host library in Rust to execute a simple guest application. It is followed by an example of a simple guest application using the Hyperlight guest library, also written in Rust.

Host

use std::thread;

use hyperlight_host::{MultiUseSandbox, UninitializedSandbox};

fn main() -> hyperlight_host::Result<()> {
    // Create an uninitialized sandbox with a guest binary
    let mut uninitialized_sandbox = UninitializedSandbox::new(
        hyperlight_host::GuestBinary::FilePath("path/to/your/guest/binary".to_string()),
        None // default configuration
    )?;

    // Registering a host function makes it available to be called by the guest
    uninitialized_sandbox.register("Sleep5Secs", || {
        thread::sleep(std::time::Duration::from_secs(5));
        Ok(())
    })?;
    // Note: This function is unused by the guest code below, it's just here for demonstration purposes

    // Initialize sandbox to be able to call host functions
    let mut multi_use_sandbox: MultiUseSandbox = uninitialized_sandbox.evolve()?;

    // Call a function in the guest
    let message = "Hello, World! I am executing inside of a VM :)\n".to_string();
    // in order to call a function it first must be defined in the guest and exposed so that
    // the host can call it
    multi_use_sandbox.call::<i32>(
        "PrintOutput",
        message,
    )?;

    Ok(())
}

Guest

First, create a Cargo.toml with the required dependencies:

[package]
name = "my-hyperlight-guest"
version = "0.1.0"
edition = "2024"

[dependencies]
hyperlight-guest = "0.12"
hyperlight-guest-bin = "0.12"
hyperlight-common = { version = "0.12", default-features = false }

Important: The hyperlight-common crate must have default-features = false to avoid pulling in the standard library, which conflicts with the no_std requirement for guests.

Then, create src/main.rs:

#![no_std]
#![no_main]
extern crate alloc;
extern crate hyperlight_guest_bin;

use alloc::vec::Vec;
use alloc::string::String;
use hyperlight_common::flatbuffer_wrappers::function_call::FunctionCall;
use hyperlight_common::flatbuffer_wrappers::guest_error::ErrorCode;

use hyperlight_guest::bail;
use hyperlight_guest::error::Result;
use hyperlight_guest_bin::{guest_function, host_function};

#[host_function("HostPrint")]
fn host_print(message: String) -> Result<i32>;

#[guest_function("PrintOutput")]
fn print_output(message: String) -> Result<i32> {
    let result = host_print(message)?;
    Ok(result)
}

#[no_mangle]
pub extern "C" fn hyperlight_main() {
    // any initialization code goes here
}

#[no_mangle]
pub fn guest_dispatch_function(function_call: FunctionCall) -> Result<Vec<u8>> {
    let function_name = function_call.function_name;
    bail!(ErrorCode::GuestFunctionNotFound => "{function_name}");
}

Build the guest using cargo-hyperlight:

cargo install --locked cargo-hyperlight
cargo hyperlight build

Note: You must use cargo hyperlight build instead of the regular cargo build command. The cargo-hyperlight tool sets up the required custom target, sysroot, and compiler flags that are necessary for building Hyperlight guests.

For additional examples of using the Hyperlight host Rust library, see the ./src/hyperlight_host/examples directory.

For examples of guest applications, see the ./src/tests/c_guests directory for C guests and the ./src/tests/rust_guests directory for Rust guests.

Note: Hyperlight guests can be written using the Hyperlight Rust or C Guest libraries.

Repository Structure

• Hyperlight Host Libraries (i.e., the ones that create and manage the VMs)

  • src/hyperlight_host - This is the Rust Hyperlight host library.

• Hyperlight Guest Libraries (i.e., the ones to make it easier to create guests that run inside the VMs)

  • src/hyperlight_guest - The core Rust library for Hyperlight guests. It provides only the essential building blocks for interacting with the host environment, including the VM exit mechanism (outb), abstractions for calling host functions and receiving return values, and the input/output stacks used for guest-host communication.
  • src/hyperlight_guest_bin - An extension to the core Rust library for Hyperlight guests. It contains more opinionated components (e.g., panic handler, heap initialization, musl-specific imports, logging, and exception handling).
  • src/hyperlight_guest_capi - A C-compatible wrapper around hyperlight_guest_bin, exposing its core functionality for use in C programs and other languages via FFI.

• Hyperlight Common (functionality used by both the host and the guest)

  • src/hyperlight_common

• Test Guest Applications:

  • src/tests/rust_guests - This directory contains three Hyperlight Guest programs written in Rust, which are intended to be launched within partitions as "guests".
  • src/tests/c_guests - This directory contains two Hyperlight Guest programs written in C, which are intended to be launched within partitions as "guests".

• Tests:

  • src/hyperlight-testing - Shared testing code for Hyperlight projects built in Rust.

Try it yourself!

You can run Hyperlight on:

• [Linux with KVM][kvm].
• [Windows with Windows Hypervisor Platform (WHP).][whp] - Note that you need Windows 11 / Windows Server 2022 or later to use hyperlight, if you are running on earlier versions of Windows then you should consider using our devcontainer on GitHub codespaces or WSL2.
• Windows Subsystem for Linux 2 (see instructions here for Windows client and here for Windows Server) with KVM.
• Azure Linux with mshv (note that you need mshv to be installed to use Hyperlight)

After having an environment with a hypervisor setup, running the example has the following pre-requisites:

1. On Linux or WSL, you'll most likely need build essential. For Ubuntu, run sudo apt install build-essential. For Azure Linux, run sudo dnf install build-essential.
2. Rust. Install toolchain v1.89 or later.
3. just. cargo install just On Windows you also need pwsh.
4. clang and LLVM.

   • On Ubuntu, run:

     wget https://apt.llvm.org/llvm.sh
     chmod +x ./llvm.sh
     sudo ./llvm.sh 18 clang clang-tools-extra
     sudo ln -s /usr/lib/llvm-18/bin/ld.lld /usr/bin/ld.lld
     sudo ln -s /usr/lib/llvm-18/bin/clang /usr/bin/clang
     

   • On Windows, see this.

   • On Azure Linux, run:

     if ! command -v clang > /dev/null 2>&1; then
         sudo dnf install clang -y
         sudo dnf install clang-tools-extra -y
     fi
     

Then, we are ready to build and run the example:

just build  # build the Hyperlight library
just rg     # build the rust test guest binaries
cargo run --example hello-world

If all worked as expected, you should see the following message in your console:

Hello, World! I am executing inside of a VM :)

If you get the error Error: NoHypervisorFound and KVM or mshv is set up then this may be a permissions issue. In bash, you can use ls -l /dev/kvm or ls -l /dev/mshv t