How hyperlight-dev/hyperlight works
Project Purpose and Type
• This project is a VMM library (and related toolchain) for embedding micro VMs into applications.
• Its purpose is to securely execute untrusted guest code using low-overhead virtualization. It targets both Windows (using Windows Hypervisor Platform and mshv) and Linux (using KVM) environments.
• The architecture comprises multiple libraries: a host library (managing the underlying virtual machine/sandbox), guest libraries (to facilitate guest development), and a common library (with shared utilities like flatbuffer wrappers).
Main Components
a. Hyperlight Host Library:
• Located in src/hyperlight_host.
• Responsible for creating and managing the sandboxed micro VMs, managing memory, handling system calls and virtualization integration (KVM, MSHV, WHP).
• Contains examples and test binaries as well as integration with host function calls.
b. Hyperlight Guest Library:
• Two flavors exist:
• The primary guest library (src/hyperlight_guest) is written in Rust.
• The C-compatible version (src/hyperlight_guest_capi) is used for guest applications that need a C interface.
• Both libraries work in tandem with the host by registering guest functions and calling host installations.
c. Hyperlight Common:
• Located in src/hyperlight_common.
• Includes shared code such as flatbuffer wrappers (for guest-host call serialization), memory and other common utilities.
d. Test and Example Guest Applications:
• Found in src/tests (Rust and C guests) as well as example directories in the hyperlight_host component.
• These demonstrate how to use the host and guest APIs.
e. Build, Configuration, and Infrastructure Items:
• Workflow configurations are provided in the .github directory, various Docker and development container files in .devcontainer, and build scripts (Justfile, Cargo.toml, etc.).
• Documentation assets in the docs directory illustrate the intended usage scenarios (debugging, metrics, etc.).
f. Integration with Virtualization:
• Shared “Hyperlight Common” module, positioned such that both the host and guest modules depend upon it.
– From the Host to a Guest: host calls exposed guest functions (e.g., PrintOutput).
– From the Guest to the Host: guest calls host functions (e.g., HostPrint or any registered host function).
• External components such as the underlying hypervisor:
– On UNIX-like systems: KVM.
– On Windows: WHP or mshv.
• Additionally, demonstrate that the integration is achieved with low overhead—indicate the “micro VM” or “sandbox” boundary.
Architectural Patterns and Design Principles
• Layered scheme: the lower layer (virtualization/hypervisor interface), the middle layer (host management and sandboxing), and the upper layers (guest libraries and development tools).
• Modularity: separate repositories or directories for host functionality, guest functionality, and common infrastructure.
• Clear separation of concerns: the host provides sandboxing and the guest provides application-specific behavior with a minimal exposed API.
• The use of flatbuffers for communication suggests a protocol-driven design to serialize and decode function call parameters/results.