How danieltangnes/hyperlight works
Hyperlight is a Rust library for running untrusted, purpose-built guest binaries in hypervisor-isolated micro VMs. The main workflow is an embedding host application building a sandbox from a guest binary, then making typed calls across the host/guest boundary; the guest can call registered host functions. The host manages VM execution, memory, and snapshots. Shared virtqueues and message codecs support transport, while guest tracing is relayed to host-side trace handling. The README documents the major capabilities; several subsystem links below are documented there because their implementation was not sampled.
Main entry points: initialized.rs Sandbox calls · lib.rs Default guest runtime · builder.rs Sandbox builder · mgr.rs Guest memory manager
Components 18
Host sandbox
- Sandbox builder
src/hyperlight_host/src/sandbox/builder.rs - Sandbox calls
src/hyperlight_host/src/sandbox/initialized.rs - Host functions
src/hyperlight_host/src/sandbox/host_funcs.rs - Snapshot restore
src/hyperlight_host/src/sandbox/snapshot/mod.rs
VM and memory
- Hypervisor backends
src/hyperlight_host/src/hypervisor/virtual_machine/mod.rs - Guest memory manager
src/hyperlight_host/src/mem/mgr.rs - Memory regions
src/hyperlight_host/src/mem/memory_region.rs - Shared memory
src/hyperlight_host/src/mem/shared_mem.rs
Guest runtime
- Default guest runtime
src/hyperlight_guest_bin/src/lib.rs - Guest primitives
src/hyperlight_guest/src/transport/context.rs
Shared transport
- Call message types
src/hyperlight_common/src/flatbuffer_wrappers/function_call.rs - Virtqueue API
src/hyperlight_common/src/virtq/mod.rs
Bindings and tracing
- Guest function macros
src/hyperlight_guest_macro/src/lib.rs - WIT bindings
src/hyperlight_component_util/src/emit.rs - Guest tracing
src/hyperlight_guest_tracing/src/lib.rs - Host trace handling
src/hyperlight_host/src/sandbox/trace/context.rs
Other components
- Host application
- Guest binary
Connections 18
- Host application → Sandbox builder: builds sandbox
README.md - Sandbox builder → Guest binary: loads guest
README.md - Sandbox builder → Sandbox calls: creates
- Sandbox calls → Hypervisor backends: runs guest
src/hyperlight_host/src/sandbox/initialized.rs - Sandbox calls → Guest memory manager: dispatches calls
src/hyperlight_host/src/sandbox/initialized.rs - Sandbox calls → Host functions: registers functions
README.md - Sandbox calls → Snapshot restore: snapshots state
README.md - Guest memory manager → Memory regions: manages regions
src/hyperlight_host/src/mem/mgr.rs - Guest memory manager → Shared memory: uses shared memory
src/hyperlight_host/src/mem/mgr.rs - Guest binary → Default guest runtime: runs with
README.md - Default guest runtime → Guest primitives: uses transport
- Guest primitives → Virtqueue API: submits messages
src/hyperlight_guest/src/transport/context.rs - Guest primitives → Call message types: encodes calls
- Sandbox calls → Call message types: exchanges typed calls
README.md - Guest function macros → Default guest runtime: exposes functions
README.md - WIT bindings → Default guest runtime: generates bindings
- Default guest runtime → Guest tracing: emits trace events
- Host trace handling → Guest tracing: receives trace data