How hyperlight-dev/hyperlight-wasm works
Project type and purpose
• This is a system‐level Rust library plus tools (“Hyperlight‑Wasm”) whose goal is to execute untrusted WebAssembly modules inside a lightweight VM‑backed sandbox. It provides:
• A core library crate (hyperlight_wasm) exposing APIs to create/run sandboxes
• An ahead‑of‑time compiler binary (hyperlight_wasm_aot)
• A macro crate (hyperlight_wasm_macro) for component‑model codegen
• A sample host runtime (wasm_runtime) and example modules
• Build scripts and helpers under Justfile and shell/PowerShell scripts
File structure
• Top‑level crates:
• src/hyperlight_wasm (core library)
• src/hyperlight_wasm_aot (AOT compiler)
• src/hyperlight_wasm_macro (macro & host‑bindgen)
• src/wasm_runtime (host application binary)
• src/examples_common, src/rust_wasm_samples, src/wasmsamples (example modules & helper code)
• Build & CI: .devcontainer/, .github/workflows/, Justfile, scripts under each crate
• Config & tooling: Cargo.toml, rust-toolchain.toml, rustfmt.toml
Key architectural patterns
• Layered crates: Host application → API library → sandbox internals → hypervisor interface
• Builder pattern: SandboxBuilder constructs VMs, loads modules, wires host functions
• Optional AOT: transforms Wasm to native code before sandbox load
• Macro integration: codegen for component‑model interfaces at compile time
Main components
a. Host Application Layer
• wasm_runtime binary or customer host app using hyperlight_wasm APIs
• Example binaries (helloworld, hostfuncs, metrics)
b. Library/API Layer
• hyperlight_wasm public modules (build_info, lib.rs)
• SandboxBuilder → config, metrics, hostfunc bindings
c. AOT Compiler
• hyperlight_wasm_aot converts .wasm → native
d. Macro Codegen
• hyperlight_wasm_macro → generates host‑side bindings for component model
e. Sandbox Runtime Internals
• Modules under src/sandbox/: loaded_wasm_sandbox, wasm_sandbox, metrics, proto_wasm_sandbox
f. Hypervisor Interfaces
• Platform abstraction layers: KVM (Linux), WHP (Windows), MSHV
• Underlying OS driver (/dev/kvm, HYPERVISOR_PLATFORM)
g. Guest Wasm Modules
• Prebuilt examples (.c, Rust, component model .wit)
h. Build & CI Tools (side notes)
• just build, scripts, GitHub Actions
Relationships & data flows
• At build time:
• Host code + macros → Rust compiler → host binary + generated bindings
• AOT compiler processes Wasm modules (optional)
• At runtime:
1. Host app calls SandboxBuilder::new() → config
2. Builder uses hypervisor interface to spin up VM
3. Wasm module bytes (or AOT image) loaded into sandbox process
4. Execution inside VM‑backed sandbox
5. Host ↔ guest communication via hostfunc bridges or component model
6. Metrics/events surfaced back through API
• CI and devcontainer are orthogonal but support reproducible builds/tests