Hyperlight
-
Hyperlight is a lightweight Virtual Machine Manager (VMM) designed to be embedded within applications. It enables safe execution of untrusted code within micro virtual machines with very low latency and minimal overhead.
We are a Cloud Native Computing Foundation sandbox project.
+
+ A lightweight VMM for running untrusted code in micro VMs with minimal overhead.
+ A Cloud Native Computing Foundation sandbox project.
+
-> 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.
+> **Status:** Hyperlight is pre-1.0. The API may change between releases, and upgrading will sometimes require code changes.
----
-
-## 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](https://docs.microsoft.com/en-us/virtualization/api/#windows-hypervisor-platform)
-on Windows, and either Microsoft Hypervisor (mshv) or [KVM](https://linux-kvm.org/page/Main_Page) on Linux.
+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.
-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:
+- Supports [KVM](https://linux-kvm.org/page/Main_Page), [MSHV](https://github.com/rust-vmm/mshv), and [Windows Hypervisor Platform](https://docs.microsoft.com/en-us/virtualization/api/#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.
-- 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_).
+## How it works
-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
+**Host** - create a sandbox, register a host function, and call into the guest:
```rust
-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::