$ show hyperlight-dev/hyperlight
Hyperlight is a production-grade library for safely executing untrusted code inside hypervisor-isolated micro virtual machines. It spins up lightweight VMs in milliseconds without requiring a guest kernel or operating system, making it suitable for sandboxing plugins, serverless functions, and other untrusted workloads. The system supports multiple hypervisor backends (KVM on Linux, MSHV on Windows, WHP on Windows, HVF on macOS) and architectures (x86_64, aarch64), with guest binaries compiled as no_std Rust or C ELF files using a custom libc (picolibc). Communication between host and guest is performed via typed function calls serialized with FlatBuffers over VM exits, and the library provides snapshot/restore capabilities using an OCI-compatible image layout for state persistence. The architecture is centered around a host-side Rust library (`hyperlight_host`) that exposes a builder pattern (`SandboxBuilder`) to configure and create sandboxes. The guest runtime (`hyperlight_guest_bin`) handles initialization, page tables, exception handling, and function dispatch. A component model integration (`hyperlight_component_util`) generates Rust bindings from WIT (WebAssembly Interface Types) for higher-level interfaces. The system also includes guest tracing with OpenTelemetry, metrics collection, crash dump generation, and GDB debugging support. External dependencies include hypervisor-specific APIs (KVM ioctls, WHP, HVF), the FlatBuffers serialization library, and the OCI image layout specification for snapshot storage. Key data flows involve the host loading a guest binary, setting up memory regions (code, heap, stack, scratch), registering host functions, and then executing guest functions via VM entries. The guest can call back into the host through registered host functions. Snapshots capture the full guest state (memory, registers, MSRs) and can be saved to disk as OCI-compatible blobs, then restored to create new sandboxes or recover from failures. The library is extensively tested with unit tests, integration tests, fuzz targets, and concurrency stress tests, and is maintained as a CNCF sandbox project with active development and frequent releases.
The LLM identified 3 files worth highlighting for reuse:
Implements a custom packed virtqueue (VIRTIO 1.1+) for efficient host-guest I/O. Provides a `VirtqProducer` with a `ChainBuilder` pattern for building scatter-gather chains, batch submission, and event suppression. The `BufferPool` and `RecyclePool` offer two-tier allocation strategies. This module is self-contained, uses a `MemOps` trait for abstract memory access, and can be extracted for any project needing a high-performance ring buffer with producer-consumer semantics.
Provides an OCI-compatible snapshot storage layer for persisting and restoring sandbox state. Uses content-addressed blobs with digest verification (blake3), atomic writes, and sparse file support. The `Snapshot::save` and `Snapshot::load` methods handle config, manifest, and index rewriting. This module is isolated from the rest of the sandbox logic and could be reused as a general-purpose content-addressable blob store with OCI layout compliance.
Defines a `SharedMemory` trait with implementations for exclusive, host-shared, guest-shared, and read-only shared memory. Each region is protected by guard pages (RAII `HostMapping`, `Placeholder`, `MappedView`) to prevent buffer overflows. Provides safe concurrent access patterns with `with_exclusivity` and `with_contents` methods. The pattern is self-contained and demonstrates a robust approach to sharing memory between a host and an untrusted guest with minimal risk of corruption.