hyperlight-dev/hyperlight
68.8
Adequate · 14 November 2026
83.2k
lines of production code
Rust
primary language
5
measurements over time
What this system is
Features
AMD64 guest adds hardware exception handling and copy-on-write memory support
The AMD64 guest now implements a full hardware exception handling subsystem, including an Interrupt Descriptor Table (IDT), Task State Segment (TSS) with an exception stack, and assembly-level entry code that saves CPU context (general-purpose and FPU/SSE registers) before invoking Rust handlers. This enables the guest to manage its own stack dynamically by handling page faults to grow the stack and supports Copy-on-Write (CoW) memory semantics for snapshot regions, allowing safe modification of shared pages. Additionally, the entry point initializes processor control structures (GDT, IDT, TSS) and performs TLB flushing on dispatch to ensure memory consistency after snapshot restores.
_src/hyperlight\_guest\bin/src/arch/amd64 · high confidence
Add ELF core dump generation and hardware interrupt support for x86-64 guests
The hypervisor module now supports generating ELF core dumps when a guest crashes, capturing memory regions, registers, and XSAVE state for post-mortem debugging. Additionally, x86-64 guests can now receive hardware interrupts (such as timer interrupts) via a new interrupt handling subsystem that manages LAPIC and legacy PIC/PIT ports, improving compatibility with guest operating systems expecting standard hardware behavior.
_src/hyperlight\host/src/hypervisor · high confidence
Add OpenTelemetry tracing example for Hyperlight
A new example application (\tracing-otlp\) demonstrates how to integrate Hyperlight with OpenTelemetry for distributed tracing. The example configures an OTLP HTTP exporter to send trace data to a collector and shows how to capture spans from guest function executions, including scenarios involving concurrent threads and call cancellations.
_src/hyperlight\host/examples/tracing-otlp · high confidence
Add aarch64 architecture support for Hyperlight VMs
Hyperlight now supports running sandboxes on aarch64 processors. This change introduces the \aarch64.rs\ module implementing the \HyperlightVm\ interface, enabling the creation and initialization of virtual machines on Apple Silicon (via HVF) and Linux (via KVM). The implementation handles architecture-specific register setup, memory mapping, and interrupt handling, allowing the host to dispatch guest calls and manage execution on ARM64 targets.
_src/hyperlight\_host/src/hypervisor/hyperlight\vm · high confidence
Add aarch64 exception handling infrastructure
The aarch64 guest now includes the core machinery to catch and manage CPU exceptions. This change adds assembly-level entry points that save and restore the full processor context (general-purpose registers, floating-point, and SIMD state) when an exception occurs, and introduces Rust handlers for page faults (including stack expansion and copy-on-write support) and undefined instructions, allowing the guest to respond to these events rather than aborting immediately.
_src/hyperlight\_guest\bin/src/arch/aarch64/exception · high confidence
Add component model elaboration and bindgen utilities
The \hyperlight\_component\_util\ crate now includes utilities to parse WebAssembly Component Model binaries (WIT) and generate Rust bindings. This adds support for reading component type exports, elaborating component types according to the specification, and emitting Rust code for both host and guest implementations of component interfaces, including resource management and type marshalling.
_src/hyperlight\_component\util · high confidence
Add guest debugging example with GDB integration
The \src/hyperlight\_host/examples/guest-debugging\ directory now contains a new example demonstrating how to enable GDB debugging for Hyperlight guests. The example shows how to configure a \SandboxBuilder\ with \DebugInfo\ to expose a debug port (default 8080) and includes tests that spawn a GDB client to connect to the guest, set breakpoints, and verify execution flow. This provides a concrete reference for users who need to debug guest code using GDB.
_src/hyperlight\host/examples/guest-debugging · high confidence
Add initial MSHV hypervisor support for aarch64
The MSHV hypervisor backend now includes an aarch64 implementation, allowing the host to run on ARM64 systems when the MSHV API is available. This change adds the \aarch64.rs\ module with a placeholder \MshvVm\ structure and an \is\_hypervisor\_present\ check (currently returning false pending full implementation), while updating \mod.rs\ to conditionally compile the aarch64 module alongside the existing x86\_64 support.
_src/hyperlight\_host/src/hypervisor/virtual\machine/mshv · high confidence
Add initial aarch64 guest runtime entrypoint and dispatch stubs
The aarch64 guest binary now includes the foundational assembly stubs required to start execution on ARM64 hardware. This change introduces the \entrypoint\ function, which initializes the Vector Base Address Register (VBAR\_EL1) and manages stack pivoting before calling the generic initialization logic. It also defines the \dispatch\_function\ assembly stub, which handles TLB invalidation and branches to the internal dispatch handler, along with the necessary memory layout constants for I/O pages and halt addresses.
_src/hyperlight\_guest\bin/src/arch/aarch64 · high confidence
Add initial aarch64 register handling for KVM
This change introduces the foundational register management infrastructure for aarch64 virtualization via KVM. It adds data structures for common CPU registers (general purpose, stack pointer, program counter, PSTATE) and FPU registers (V registers, FPSR, FPCR), alongside definitions for key system registers (TTBR0\_EL1, TCR\_EL1, MAIR\_EL1, SCTLR\_EL1, CPACR\_EL1, VBAR\_EL1). The implementation includes KVM-specific bindings to get and set these registers on a vCPU file descriptor, enabling the host to save and restore the architectural state of aarch64 guests.
_src/hyperlight\host/src/hypervisor/regs/aarch64 · high confidence
Add macros for type-safe guest entry points and function registration
The \hyperlight\_guest\_macro\ crate introduces \\#\[main\]\, \\#\[dispatch\]\, and \\#\[guest\_function\]\ attribute macros to simplify guest code development. The \\#\[main\]\ macro generates a C-compatible entry point (\hyperlight\_main\) that calls the user's function, while \\#\[dispatch\]\ allows defining a fallback handler for unregistered function calls. The \\#\[guest\_function\]\ macro registers functions with the host at initialization, supporting custom names and error-returning signatures, and enforces constraints such as prohibiting async functions and receiver arguments.
_src/hyperlight\_guest\macro · high confidence
Add trace\_dump utility for visualizing execution traces
A new \src/trace\_dump\ binary has been added to parse and visualize execution traces. It reads trace data files to display memory allocation and deallocation events, stack unwinding information, and binary hashes. The tool includes a symbol cache to resolve memory addresses to human-readable function names and line numbers, and supports generating visual outputs (bar charts and flame graphs) using the \piet\_common\ rendering library.
_src/trace\dump · high confidence
Add x86\_64 GDB stub for sandbox debugging
A new GDB debugging interface is now available for Hyperlight sandboxes on x86\_64. This change introduces the \gdb\ module containing an architecture-specific implementation (\arch.rs\) that interprets vCPU stop reasons (such as software/hardware breakpoints and single-stepping) via the DR6 register, and an event loop (\event\_loop.rs\) that manages the GDB protocol connection. The \x864\_target.rs\ file implements the \gdbstub\ target traits, allowing debuggers to read/write guest memory and registers, while \mod.rs\ defines the internal communication channels and error types. This enables external tools like GDB to attach to and debug running Hyperlight guests.
_src/hyperlight\host/src/hypervisor/gdb · high confidence
Added KVM performance mitigation and sandbox crashdump scripts
Two new scripts are now available in the host tools. The \apply-kvm-perf-mitigation.sh\ script addresses performance issues on Linux kernel 6.x by adjusting KVM module parameters (specifically \nx\_huge\_pages\) and cgroup mount options when the system is not affected by the ITLB multihit vulnerability. Additionally, \dump\_all\_sandboxes.gdb\ provides a GDB macro to generate crashdumps for all active sandboxes across multiple threads, aiding in debugging by iterating through threads and invoking the sandbox's crashdump generation function.
_src/hyperlight\host/scripts · high confidence
Added ballast example to maintain sandbox residency for benchmarking
A new example program has been added to keep a Hyperlight sandbox alive and idle, designed to stabilize benchmarking conditions by preventing kernel text patching overhead associated with frequent sandbox creation and teardown. The program initializes a sandbox, prints a readiness signal, and then waits for standard input to close, ensuring it remains resident without consuming CPU resources while a benchmark is running.
_src/hyperlight\host/examples/ballast · high confidence
Added benchmarks and architecture-specific virtual memory implementations for Hyperlight
This change introduces performance benchmarks for the \SlotPool\ and \virtq\_api\ components in \src/hyperlight\_common/benches\, allowing users to measure allocation and round-trip throughput. It also adds architecture-specific virtual memory management code for aarch64 and amd64 in \src/hyperlight\_common/src/arch\, including page table manipulation, memory layout definitions, and exception syndrome decoding, which are required for proper guest memory handling on these platforms.
_src/hyperlight\common · high confidence
Added copy-on-write file mapping example for Windows
A new example, map-file-cow-test, demonstrates end-to-end copy-on-write file mapping using the SandboxBuilder. It creates both page-aligned and intentionally unaligned temporary files to verify that the Windows surrogate process can correctly map file-backed sections, specifically addressing previous failures where unaligned files caused access-denied errors during MapViewOfFileNuma2 calls.
_src/hyperlight\host/examples/map-file-cow-test · high confidence
Added crash dump example demonstrating automatic and on-demand core dump generation
A new example at src/hyperlight\_host/examples/crashdump demonstrates how to use Hyperlight's crash dump feature, which generates ELF core dump files containing vCPU state and guest memory for post-mortem debugging. The example illustrates automatic crash dumps triggered by VM-level faults (such as memory access violations) and on-demand dumps via the generate\_crashdump() API for guest-caught exceptions. It also shows how to disable crash dumps per sandbox and configure the output directory via the HYPERLIGHT\_CORE\_DUMP\_DIR environment variable.
_src/hyperlight\host/examples/crashdump · high confidence
Initial Hypervisor.framework (HVF) support for macOS
Adds the initial implementation of the Hypervisor.framework backend, enabling Hyperlight to run virtual machines on macOS. This change introduces the core Rust bindings and C helper functions for managing vCPU SIMD/FPU registers, along with the main module logic that handles the specific constraints of HVF (such as single-address-space and thread-affinity limitations) to allow sandbox execution.
_src/hyperlight\_host/src/hypervisor/virtual\machine/hvf · high confidence
Initial KVM hypervisor implementation for aarch64
This change introduces the first KVM backend support for aarch64 architectures. The new \aarch64.rs\ module implements the \VirtualMachine\ trait, providing core capabilities such as VM creation, vCPU initialization, memory mapping/unmapping, and vCPU execution. It includes specific handling for ARM-specific KVM capabilities, such as \KVM\_CAP\_ARM\_NISV\_TO\_USER\, to mitigate issues with cache maintenance operations and self-modifying code that could otherwise poison the sandbox. The \mod.rs\ file now conditionally exports this aarch64 implementation alongside the existing x86\_64 backend, enabling Hyperlight to run on ARM64 Linux hosts using KVM.
_src/hyperlight\_host/src/hypervisor/virtual\machine/kvm · high confidence
Initial devcontainer configuration for Hyperlight development
The project now includes a pre-configured development environment using VS Code Dev Containers. This setup provides a consistent workspace with Rust 1.94, LLVM 18, and necessary build tools (cmake, gdb, musl-tools). It automatically configures the container for KVM access, installs essential VS Code extensions (C/C++, CMake Tools, Rust Analyzer, LLDB), and sets up the nightly toolchain required for specific formatting features.
.devcontainer · high confidence
Introduce GuestHandle for safe user memory access
Added a new GuestHandle struct that provides a controlled interface for the guest to access user memory regions defined by the HyperlightPEB. This component exposes methods to initialize the handle with a PEB pointer and to safely read a specified number of bytes from user memory, including validation to ensure the requested size does not exceed the available data.
_src/hyperlight\_guest/src/guest\handle · high confidence
Introduction of VirtualMachine module with hypervisor detection and error handling
The new \src/hyperlight\_host/src/hypervisor/virtual\_machine/mod.rs\ file introduces the core \VirtualMachine\ module, which provides runtime detection of available hypervisors (KVM, MSHV, WHP, HVF) via \get\_available\_hypervisor\ and \is\_hypervisor\_present\. It defines the \HypervisorType\ enum, platform-specific constants for XSAVE buffer sizes, and structured error types (\VmError\, \CreateVmError\, etc.) using \thiserror\ for richer error reporting. The module also establishes the \VmExit\ enum to categorize vCPU exit reasons and includes compile-time checks to ensure a suitable hypervisor is available on supported platforms.
_src/hyperlight\_host/src/hypervisor/virtual\machine · high confidence
New AMD64 exception handling infrastructure with page fault and copy-on-write support
The guest runtime now includes a complete AMD64 exception handling subsystem. This adds low-level assembly entry points and an Interrupt Descriptor Table (IDT) configuration for CPU exceptions 0–20 and 30, ensuring the Direction Flag is cleared before invoking Rust handlers. It introduces a pluggable handler framework allowing guest code to register custom handlers for specific exception vectors. Additionally, the system implements automatic handling of page faults, including lazy zero-initialization of memory regions and copy-on-write (CoW) semantics for snapshot regions, enabling the guest to manage its own stack growth and memory protection dynamically.
_src/hyperlight\_guest\bin/src/arch/amd64/exception · high confidence
New Chrome tracing example for Hyperlight
Added a new example demonstrating how to integrate Chrome tracing with Hyperlight. The example shows how to set up a tracing subscriber with a Chrome layer, create a sandbox using the SandboxBuilder API, and execute a guest function while capturing performance metrics.
_src/hyperlight\host/examples/tracing-chrome · high confidence
New benchmarking tooling for accurate, comparable CI results
The \hyperlight\_ci\ module now provides a complete benchmarking workflow to ensure performance comparisons are accurate and actionable. To eliminate noise from hardware differences, the \bench\ command can now run a baseline measurement on the same machine using a \git worktree\ (controlled by \--baseline-ref\), ensuring comparisons reflect code changes rather than runner variance. It also introduces a \Ballast\ feature that keeps a resident VM alive during runs to prevent kernel patching overhead from skewing results, and allows users to disable this with \--no-ballast\. The \bench-report\ command generates markdown tables from these results, supporting configurable thresholds for improvements and regressions, and can pull data from local directories, specific CI runs, or pull requests. Additionally, a \BenchConfig\ system allows filtering benchmarks via allowlists/denylists and customizing report indicators.
_src/hyperlight\ci · high confidence
New component bindgen macros for WIT-based host/guest interfaces
The \hyperlight\_component\_macro\ crate introduces \host\_bindgen!()\ and \guest\_bindgen!()\ procedural macros to generate Rust bindings for Wasm Component Model interfaces defined by WIT sources. These macros allow developers to specify interface definitions via WIT files, WAT text, inline strings, or wasm-encoded packages, automatically generating the necessary types, trait implementations, and registration functions to connect Hyperlight hosts and guests.
_src/hyperlight\_component\macro · high confidence
New development scripts and tooling for CI automation and release management
The repository now includes a suite of new shell scripts in the \dev/\ directory to automate and streamline development workflows. These include \auto-approve-dependabot.sh\ for automatically approving and merging Dependabot PRs that only modify Cargo files, \check-license-headers.sh\ to enforce license headers on Rust source files, and \check-release-blockers.sh\ to prevent releases if blocking issues are open. Additional utilities support the release process (\crates-to-publish.sh\, \extract-changelog.sh\, \update-cargo-hyperlight-version.sh\, \verify-version.sh\), CI failure notification (\notify-ci-failure.sh\), and macOS code signing (\macos-sign-and-run.sh\, \macos-entitlements.plist\). The existing \verify-msrv.sh\ script has been updated to correctly verify the Minimum Supported Rust Version for \hyperlight-guest\ and \hyperlight-guest-bin\ crates by targeting the \x86\_64-unknown-none\ architecture. The legacy \clean-github-artifacts.sh\ script has been removed.
dev · high confidence
New hyperlight-libc crate provides picolibc-based C standard library for guests
A new \hyperlight-libc\ crate has been introduced to supply a C standard library implementation for Hyperlight guest binaries, built from the picolibc source (version 1.8.11). This crate compiles picolibc from a vendored git submodule and generates Rust bindings for C types and functions, enabling guest code to use standard C features. The library is configured for a micro-VM environment with single-threading, a global errno, and minimal stdio, while relying on the Rust global allocator for memory management. It supports both x86\_64 and aarch64 architectures and requires downstream code to provide specific POSIX stubs (such as \read\, \write\, and \clock\_gettime\) for host interaction.
_src/hyperlight\libc · high confidence
New sandbox tracing and memory profiling infrastructure
The sandbox module now includes a new \trace\ subsystem that captures guest execution data. The \TraceContext\ handles general guest tracing by walking page tables to read trace batches from guest memory, managing OpenTelemetry spans, and calculating timestamps using the TimeStamp Counter (TSC) frequency. Additionally, when the \mem\_profile\ feature is enabled, the \MemTraceInfo\ component records memory allocation and free events, unwinding stack frames via \framehop\ and writing them to trace files. This replaces previous tracing implementations with a structured approach supporting both standard event tracing and detailed memory profiling.
_src/hyperlight\host/src/sandbox/trace · high confidence
OCI-based snapshot persistence with integrity verification and sparse storage
Snapshots are now persisted to and loaded from a local directory using the OCI Image Layout format, enabling structured storage with content-addressed blobs. The implementation validates blob integrity via SHA-256 digests against OCI manifests and rejects symbolic links to prevent path traversal. To optimize disk usage and save time, guest memory images are written sparsely, creating filesystem holes for zero-filled pages while maintaining byte-for-byte correctness. The snapshot format includes metadata for architecture, hypervisor backend, and CPU vendor to ensure compatibility on restore, and supports referencing snapshots by human-readable tags or content digests.
_src/hyperlight\host/src/sandbox/snapshot/file · high confidence
Removals
Removal of OTLP tracing example
The OTLP tracing example located at src/hyperlight\_host/examples/otlp\_tracing has been removed from the codebase. This deletion eliminates the demonstration code that previously showed how to send tracing events to an OTLP collector using the opentelemetry crate, including the setup of the OpenTelemetry layer and the execution of guest sandbox interactions for tracing purposes.
_src/hyperlight\_host/examples/otlp\tracing · high confidence
Removal of PE guest support
The host no longer supports loading or executing PE (Portable Executable) formatted guest binaries. The internal modules responsible for parsing PE headers, base relocations, and PE-specific memory layout (\src/hyperlight\_host/src/mem/pe\) have been removed, meaning PE files can no longer be used as guest payloads.
_src/hyperlight\host/src/mem/pe · high confidence
Removed chrome-tracing example
The chrome-tracing example has been removed from the repository. This example previously demonstrated how to use Hyperlight with Chrome tracing to profile guest function calls, including setup of the tracing subscriber and execution of a simple echo function within a multi-use sandbox.
_src/hyperlight\host/examples/chrome-tracing · high confidence
Architecture
New x86\_64 register abstraction layer for KVM, MSHV, and WHP backends
The x86\_64 hypervisor register handling has been restructured into a new modular abstraction layer (\src/hyperlight\_host/src/hypervisor/regs/x86\_64\) that unifies state management across KVM, MSHV, and Windows Hypervisor Platform (WHP). This change introduces dedicated modules for standard registers (\standard\_regs.rs\), special registers (\special\_regs.rs\), floating-point units (\fpu.rs\), debug registers (\debug\regs.rs\), and model-specific registers (\msrs.rs\). Each module provides a \Common\\ struct that normalizes backend-specific bindings (e.g., \kvm\_regs\, \StandardRegisters\, \WHV\_REGISTER\_VALUE\) into a unified internal representation, ensuring consistent snapshot persistence and restoration behavior regardless of the underlying hypervisor backend.
_src/hyperlight\_host/src/hypervisor/regs/x86\64 · high confidence
Behavioural changes
10 commits (0 fixes) modifying src/hyperlight\_guest/src/arch/aarch64
A change to existing behaviour in src/hyperlight\_guest/src/arch/aarch64 — 10 commits, 5 files: “refactor: share guest paging primitives (\#1889)”; “aarch64: add memory layout”; “feat!: restore snapshots with a different scratch size (\#1947)”; and 7 more (refs \#1889, \#1947, \#1968, \#1793, \#1750, …).
_src/hyperlight\guest/src/arch/aarch64 · medium confidence · unverified
14 commits (2 fixes) modifying src/hyperlight\_guest/src/arch/amd64
A change to existing behaviour in src/hyperlight\guest/src/arch/amd64 — 14 commits (2 fixs), 4 files: “amd64: add exception stack at top of scratch memory”; “Rename MAX\{GPA,GVA} to SCRATCH\TOP\{GPA,GVA}”; “refactor: share guest paging primitives (\#1889)”; and 11 more (refs \#1889, \#1991, \#1534, \#1947, \#1968, …).
_src/hyperlight\guest/src/arch/amd64 · medium confidence · unverified
2 commits (0 fixes) modifying src/hyperlight\_host/src/hypervisor/virtual\_machine/whp
A change to existing behaviour in src/hyperlight\_host/src/hypervisor/virtual\_machine/whp — 2 commits, 3 files: “feat(aarch64): add WHP backend for ARM64 Windows (\#1638)”; “Restore the guest TSC exactly on WHP (\#2022)” (refs \#1638, \#2022).
_src/hyperlight\_host/src/hypervisor/virtual\machine/whp · medium confidence · unverified
2 commits (1 fix) modifying src/hyperlight\_component\_csharp
A change to existing behaviour in src/hyperlight\_component\_csharp — 2 commits (1 fix), 9 files: “Add crate for host-side .net component bindings (\#1946)”; “Fix C\# rejection tests with the stricter WIT parser (\#2049)” (refs \#1946, \#2049).
_src/hyperlight\_component\csharp · medium confidence · unverified
Build system overhaul: macOS Hypervisor.framework support, surrogate cross-compilation fix, and feature cleanup
The build process for hyperlight-host has been significantly updated. On macOS, enabling the new 'hvf' feature now automatically generates Rust bindings for the Hypervisor.framework and compiles necessary C stubs, allowing Hyperlight to run on Apple Silicon and Intel Macs. For Windows builds, the surrogate binary compilation logic was rewritten to correctly handle cross-compilation from Linux by explicitly setting the target triple and fixing path separators, ensuring the embedded surrogate executable is built and located correctly. Additionally, the build script now uses short-form license pragmas, updates the copyright year to 2025, and removes the 'inprocess' and 'mshv' features in favor of 'mshv3' and 'crashdump', while also deleting the legacy Justfile and fuzz target.
_src/hyperlight\host · high confidence
C API guest function wrappers now return hl\_ReturnValue\* instead of hl\_Vec\*
The C API wrapper macros (HYPERLIGHT\_WRAP\FUNCTION\\*) have been updated so that guest functions return an hl\ReturnValue\ constructed via hl\_result\from\\* functions, replacing the previous requirement to return flatbuffer-encoded hl\Vec\ via hl\_flatbuffer\_result\from\\*. This change also introduces support for ByteChunks parameters, which are passed as arrays of borrowed pointer and length spans, and renames internal FFI types (e.g., FfiByteChunk to ByteChunk) in the generated bindings.
_src/hyperlight\_guest\capi · high confidence
Guest function registration and dispatch logic restructured
The guest function handling logic has been reorganized into dedicated modules (call, definition, register) within the guest binary. This change introduces a \GuestFunctionRegister\ to manage the registry of exposed functions and refactors the dispatch mechanism in \internal\_dispatch\_function\ to validate function call types, verify parameter signatures against registered definitions, and route calls to either specific handlers or a default dispatcher. It also integrates trace instrumentation into the dispatch flow to capture execution timing for guest function calls.
_src/hyperlight\_guest\_bin/src/guest\function · high confidence
Guest runtime refactored to use virtqueue transport and simplified exit handling
The guest runtime now communicates with the host via a new virtqueue-based transport layer (src/hyperlight\_guest/src/transport), replacing the previous shared-memory input/output stacks and direct outb-based function dispatch. This change introduces a global transport context for managing host-to-guest and guest-to-host queues, with dedicated modules for message encoding/decoding (codec), memory access within the scratch region (mem), and context management (context). Concurrently, the exit mechanism has been simplified: the old entrypoint, custom stack-checking (chkstk), and alloca implementations have been removed in favor of a new exit module that handles aborts and debug printing through standardized OutB actions, while layout definitions now reference scratch-top addresses for shared memory regions. Also in this area: Virtqueue buffer pool uses pointer equality instead of generation counters.
_src/hyperlight\_guest/src, src/hyperlight\guest/src/transport · high confidence
Guest runtime removes custom alloca and setjmp implementations
The guest runtime build process no longer compiles the custom alloca wrapper or the custom setjmp/longjmp header. The build.rs script, which previously conditionally compiled src/alloca/alloca.c and included src/hyperlight\_guest/include/setjmp.h, has been deleted, removing these custom C implementations from the guest binary.
_src/hyperlight\guest · high confidence
Hyperlight surrogate process optimized for reduced startup overhead
The hyperlight\_surrogate binary has been converted to a \#!\[no\_std\] application to eliminate the loading of unnecessary libraries (such as dbghelp.dll and VCRUNTIME140.dll), which previously added approximately 200ms of overhead during process creation on ARM64 Windows. This change reduces the time required to create the suspended surrogate process used for WHvMapGpaRange2 operations, improving overall host performance.
_src/hyperlight\_host/src/hyperlight\surrogate · high confidence
Introduce SandboxBuilder for simplified sandbox creation
The sandbox creation API has been refactored to use a new \SandboxBuilder\ pattern, replacing the previous \UninitializedSandbox\ and \SingleUseSandbox\ types. Users can now construct sandboxes fluently from a guest binary file, a memory buffer, or an existing snapshot using \SandboxBuilder::from\_file\, \from\_bytes\, or \from\_snapshot\. This builder supports chaining configuration methods for host functions, memory regions, and file mappings before calling \build()\. The legacy \SingleUseSandbox\ and its associated handler abstractions (like \OutBHandler\ and \MemAccessHandler\) have been removed in favor of this unified, state-machine-driven approach.
_src/hyperlight\host/src/sandbox · high confidence
Introduce dedicated hyperlight\_guest\_bin crate for guest runtime core
The guest runtime logic has been reorganized into a new \hyperlight\_guest\_bin\ crate, consolidating the guest entrypoint, panic handling, and error management. This change introduces a new guest logger that forwards log messages to the host via the virtqueue transport, and implements a new host-guest communication layer (\host\_comm\) for function calls. Additionally, the crate provides C-compatible memory management wrappers (\malloc\, \free\, etc.) that interface with the Rust global allocator, and initializes the guest transport queues using host-assigned scratch regions.
_src/hyperlight\_guest\bin/src · high confidence
Introduce virtqueue-based transport and sparse snapshot saving
Guest-host communication now uses virtqueues for all function calls and logging, replacing the legacy stack-based I/O. This change introduces a new ABI (v5) and config schema (v3), requiring existing snapshots to be regenerated. Additionally, \Snapshot::save\ now writes the guest memory blob sparsely, skipping all-zero blocks to significantly reduce the size of saved snapshots without changing the digest or layout.
(repo-wide) · high confidence
Introduces virtqueue-based host-guest communication and removes legacy memory management modules
The memory subsystem now uses a new virtqueue transport layer for host-guest communication, replacing the previous mechanism. This change adds a new \virtq\ module containing codec, memory operations, and snapshot/restore logic for the new transport, along with comprehensive tests. Concurrently, legacy memory management components—\custom\_drop.rs\, \loaded\_lib.rs\, and \shared\_mem\_snapshot.rs\—have been removed, and the ELF/PE loading logic has been refactored to support the new layout and transport requirements.
_src/hyperlight\host/src/mem · high confidence
Metrics subsystem refactored to use the \`metrics\` crate
The metrics implementation in \src/hyperlight\_host/src/metrics\ has been rewritten to use the \metrics\ crate instead of the previous \prometheus\-based wrappers. This removes the custom \Histogram\, \HistogramVec\, \IntCounter\, \IntCounterVec\, \IntGauge\, and \IntGaugeVec\ modules and their associated macros. The new approach introduces specific metrics such as \guest\_errors\_total\, \guest\_cancellations\_total\, and \erroneous\_vcpu\_kicks\_total\, and conditionally emits \guest\_call\_duration\_seconds\ and \host\_call\_duration\_seconds\ when the \function\_call\_metrics\ feature is enabled.
_src/hyperlight\host/src/metrics · high confidence
New generic C API for host-guest return values and byte chunks
The C API in the guest library has been refactored to replace the previous Flatbuffer-based return mechanism with a new generic result API. This change introduces \hl\_result\from\\*\ functions (supporting int, uint, long, ulong, float, double, bool, string, vecbytes, and byte chunks) and corresponding \hl\_get\_host\_return\_value\as\\*\ getters, allowing guests to exchange richer data types with the host. The implementation also adds support for \ByteChunks\ parameters and return values, enabling efficient zero-copy handling of multiple byte buffers. The old \hl\_flatbuffer\_result\from\\*\ functions have been removed in favor of this new typed approach.
_src/hyperlight\_guest\capi/src · high confidence
New guest-side tracing infrastructure with flatbuffers serialization
The \hyperlight\_guest\_tracing\ module has been replaced with a new implementation that captures spans and events in the guest and serializes them using flatbuffers. This change introduces a \GuestSubscriber\ to collect trace data, an \invariant\_tsc\ module for high-performance timestamping on x86\_64, and logic to flush trace batches to the host via \outb\ instructions. The new system includes deadlock protection for exception contexts and allows runtime updates to the log level filter.
_src/hyperlight\_guest\tracing · high confidence
Removal of evolving/devolving sandbox state transitions
The \sandbox\_state\ module has been removed, eliminating the \Sandbox\, \EvolvableSandbox\, \DevolvableSandbox\, and \TransitionMetadata\ traits. This removes the ability for sandboxes to transition between states via evolve and devolve operations, replacing that mechanism with a snapshotting API.
_src/hyperlight\_host/src/sandbox\state · high confidence
Removal of seccomp syscall filtering for guest execution
The seccomp filtering module, which previously enforced a strict allow-list of system calls for untrusted guest code execution within the hypervisor handler thread, has been removed. This eliminates the mechanism that trapped or killed threads attempting disallowed syscalls (such as \openat\, \write\, or \ioctl\), meaning guest code will no longer be restricted by these specific kernel-level syscall filters in this component.
_src/hyperlight\host/src/seccomp · high confidence
Removal of seccomp-based signal handling and panic hook
The seccomp feature has been removed from the signal handlers module, eliminating the SIGSYS handler that previously intercepted disallowed syscalls and the custom panic hook that suppressed 'DisallowedSyscall' panics. The \setup\_signal\_handlers\ function no longer registers SIGSYS handlers or modifies the global panic hook; it now only registers a real-time signal handler for VM termination (renamed to \vm\_kill\_signal\) and accepts a \SandboxConfiguration\ to determine the signal offset. The dedicated \sigsys\_signal\_handler.rs\ file has been deleted entirely.
_src/hyperlight\_host/src/signal\handlers · high confidence
Replace embedded musl libc with git subtree
The local copy of the musl libc source code and its associated patch files in the third\_party directory have been removed. This change reflects a migration to manage the musl dependency via a git subtree, simplifying updates and maintenance of the guest runtime's C library.
_src/hyperlight\_guest/third\party · high confidence
Sandbox API and metrics collection simplified in metrics example
The metrics example has been updated to use the new \SandboxBuilder\ API instead of the previous \UninitializedSandbox\ and \evolve\ pattern, significantly reducing boilerplate for sandbox creation. Guest function calls now use a generic \call\ method with native types rather than the verbose \call\_guest\_function\_by\_name\ with explicit parameter wrappers. Additionally, the example now uses the \metrics\ crate ecosystem with \metrics\_exporter\_prometheus\ for recording and rendering metrics, replacing the direct \prometheus\ crate usage and manual registry management.
_src/hyperlight\host/examples/metrics · high confidence
Sandbox API overhaul and improved error handling
The host runtime now uses a new \SandboxBuilder\ to construct sandboxes, replacing the previous \SingleUseSandbox\ and \SandboxRunOptions\ patterns. Error handling has been significantly refined: the \HyperlightError\ enum now includes a \GuestBinVersionMismatch\ variant to explicitly fail when guest and host versions do not match, and a \TransportError\ variant for virtqueue communication issues. Additionally, the crate has migrated from the \log\ crate to \tracing\ for error logging, and internal memory layout constants (such as the base address) have been updated.
_src/hyperlight\host/src · high confidence
Simplified guest function calling example with SandboxBuilder
The func\_ctx example has been rewritten to use the new SandboxBuilder API, replacing the previous multi-step process of initializing an UninitializedSandbox, evolving it, and managing MultiUseGuestCallContexts. Users can now create and call guest functions (such as Echo and CallMalloc) directly on a Sandbox instance using native Rust types, significantly reducing boilerplate and simplifying the developer experience for invoking guest code.
_src/hyperlight\_host/examples/func\ctx · high confidence
Simplified host function registration and type handling
The \hyperlight\_host\ function module has been refactored to unify host function registration and parameter/return type handling. The previous \HostFunction0\ through \HostFunction10\ traits and the \HyperlightFunction\ wrapper have been removed in favor of a single \HostFunction\ type and a \Registerable\ trait, allowing host functions to be registered on both \UninitializedSandbox\ and \MultiUseSandbox\ instances. Additionally, the local \SupportedParameterType\ and \SupportedReturnType\ traits have been replaced by re-exports from \hyperlight\_common\, and the \call\_ctx\, \guest\_dispatch\, and \guest\_err\ modules have been removed, indicating a shift in how guest function calls and error handling are managed within the host.
_src/hyperlight\host/src/func · high confidence
Simplified sandbox API and added interrupt support in examples
The logging and tracing examples now use the new SandboxBuilder pattern instead of the previous UninitializedSandbox/EvolvableSandbox workflow, resulting in cleaner code and the removal of verbose type annotations for guest function calls. Additionally, the examples demonstrate a new interrupt capability, allowing host-side cancellation of long-running guest functions via an interrupt handle.
_src/hyperlight\host/examples/tracing · high confidence
Simplified sandbox creation and function invocation in hello-world example
The hello-world example now uses the new SandboxBuilder API, replacing the previous multi-step process of creating an UninitializedSandbox, manually registering host functions, and evolving the sandbox state. Users can now build a sandbox with a registered host function in a single fluent chain. Additionally, calling guest functions has been simplified to use native Rust types (e.g., calling \`sandbox.call::\<i32\>(
_src/hyperlight\host/examples/hello-world · high confidence
Snapshot ABI versioning and validation safeguards
The snapshot module now includes compile-time assertions (tripwires) that pin critical ABI constants—such as the snapshot ABI version (5), OCI media types, OCI layout version (1.0.0), Hyperlight PEB size, OutB/VmAction port numbers, and base memory address. These checks ensure that any change to these underlying contracts will fail at compile time, preventing the accidental loading of incompatible older snapshots at runtime. Additionally, the module exposes public OCI reference types (digest, reference, tag) and defines the immutable Snapshot structure with metadata support, laying the groundwork for robust snapshot versioning and validation.
_src/hyperlight\host/src/sandbox/snapshot · high confidence
Testing utilities updated for new guest types, fuzzing support, and logging fixes
The testing library now provides path resolution for new guest types (witguest, dummyguest) and non-PIE simpleguest binaries, while removing support for the deprecated callbackguest. A new fuzzing helper prefers simpleguest binaries located in the same directory as the executable, and standard sandbox heap sizes are now exposed as constants. Additionally, guest logging targets have been corrected from 'hyperlight-guest' to 'hyperlight\_guest', and the tracing subscriber now includes a method to retrieve recorded spans and uses a safer interest strategy to prevent race conditions in parallel tests.
_src/hyperlight\testing · high confidence
Updated Rust toolchain to 1.86 and added developer helper scripts
The development environment now uses Rust 1.86, as reflected in the updated \rust-dependabot-patch.Dockerfile\. Additionally, two new scripts have been added to the \hack\ directory to improve developer workflows: \clippy-package-features.sh\ automates clippy checks across various package feature combinations, and \update-actions.sh\ helps scan and pin GitHub Actions to specific commit hashes for security and reproducibility.
hack · high confidence
Test coverage
1 commit adding/updating tests in src/tests/csharp\_host; Added .gitkeep files to test guest binary directories; Added WIT guest test definitions for component roundtrip and resource handling; Added WIT guest test harness and roundtrip tests; Added WIT roundtrip tests and updated sandbox integration tests; Added bindgen test cases for WIT package name disambiguation and versioning; Added snapshot golden tests for Hyperlight host; Clean up test helper modules and update license headers; New fuzzing targets for guest calls, tracing, and virtio queues; Refactored test helpers to use SandboxBuilder and removed in-process mode support; Removal of callbackguest test fixture; Rewritten benchmark suite with sandbox size dimensions and new lifecycle tests; Updated c\_simpleguest test to use picolibc and standard C functions; Updated dummyguest test to support aarch64 and modernize build configuration; Updated simpleguest test guest to use new guest-bin APIs and exception handling macros.
Dependencies
Rust workspace restructure and dependency modernization
The project has been restructured into a multi-crate workspace, introducing new packages for guest binaries (hyperlight-guest-bin), guest macros (hyperlight-guest-macro), guest tracing (hyperlight-guest-tracing), libc bindings (hyperlight-libc), and component utilities/macros (hyperlight-component-util, hyperlight-component-macro). The host fuzzing target was moved to a top-level fuzz directory, and the test guest workspaces were consolidated. Additionally, the workspace upgraded to Rust edition 2024 (MSRV 1.89) and updated core dependencies, including wasmparser, wit-parser, and flatbuffers, to align with the new component model support.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 71 → 69 (-2.7)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.
Lenses
- Code Health 70 → 87 (+17.7)
- Architecture 95 → 65 (-29.5)
- Maturity 74 → 74 (+0.7)
- Readiness 67 → 67 (-0.7)
- Security 77 → 70 (-6.9)
- Performance 94 → 94 (+0.0)
Resolved (92)
- Change coupling: elf.rs ↔ mgr.rs (src/hyperlight_host/src/mem/elf.rs)
- Duplicated block (10 lines × 2) (src/hyperlight_common/src/arch/aarch64/vmem.rs)
- Duplicated block (10 lines × 2) (src/hyperlight_host/src/hypervisor/virtual_machine/mshv/x86_64.rs)
- Duplicated block (10–23 lines × 2) (src/hyperlight_component_util/src/hl.rs)
- Duplicated block (7 lines × 2) (src/hyperlight_host/src/sandbox/initialized.rs)
- Duplicated block (7 lines × 2) (src/hyperlight_host/src/sandbox/snapshot/file/transport.rs)
- Duplicated block (7–8 lines × 2) (src/hyperlight_component_util/src/substitute.rs)
- Duplicated block (8 lines × 2) (src/hyperlight_host/src/hypervisor/virtual_machine/whp/aarch64.rs)
- Duplicated block (8–10 lines × 3) (src/hyperlight_common/src/flatbuffer_wrappers/guest_trace_data.rs)
- HackComment (src/hyperlight_component_util/src/rtypes.rs)
- Hotspot: src/hyperlight_component_util/src/rtypes.rs (src/hyperlight_component_util/src/rtypes.rs)
- Hotspot: src/hyperlight_host/src/hypervisor/virtual_machine/whp/x86_64.rs (src/hyperlight_host/src/hypervisor/virtual_machine/whp/x86_64.rs)
- Hotspot: src/hyperlight_host/src/sandbox/snapshot/file/config.rs (src/hyperlight_host/src/sandbox/snapshot/file/config.rs)
- Medium vulnerability: RUSTSEC-2026-0344 (Cargo.lock)
- No ADRs found
- Off-boarding risk: anonymized user #1
- Off-boarding risk: anonymized user #2
- Orphaned file (src/hyperlight_guest_tracing/src/state.rs)
- Outdated: arbitrary
- Outdated: tokio
- …and 72 more
New (84)
- Boundary-crossing change coupling: exit.rs ↔ call.rs (src/hyperlight_guest/src/exit.rs)
- ClassTooLong: KvmVm (src/hyperlight_host/src/hypervisor/virtual_machine/kvm/x86_64.rs)
- Duplicated block (10 lines × 2) (src/hyperlight_common/src/arch/aarch64/vmem.rs)
- Duplicated block (10 lines × 2) (src/hyperlight_host/src/hypervisor/virtual_machine/mshv/x86_64.rs)
- Duplicated block (10–23 lines × 2) (src/hyperlight_component_util/src/hl.rs)
- Duplicated block (13 lines × 2) (src/hyperlight_guest/src/arch/aarch64/prim_alloc.rs)
- Duplicated block (13 lines × 2) (src/hyperlight_host/src/hypervisor/virtual_machine/whp/aarch64.rs)
- Duplicated block (14–15 lines × 2) (src/hyperlight_testing/src/logger.rs)
- Duplicated block (5 lines × 2) (src/hyperlight_host/src/hypervisor/hyperlight_vm/mod.rs)
- Duplicated block (6 lines × 2) (src/hyperlight_host/src/mem/mgr.rs)
- Duplicated block (7 lines × 2) (src/hyperlight_component_csharp/src/types.rs)
- Duplicated block (7 lines × 2) (src/hyperlight_host/src/sandbox/initialized.rs)
- Duplicated block (7 lines × 3) (src/hyperlight_common/src/flatbuffer_wrappers/guest_trace_data.rs)
- Edited copies of one member (3 members, 15+ corresponding lines) (src/hyperlight_host/src/hypervisor/gdb/x86_64_target.rs)
- Edited copies of one member (3 members, 20+ corresponding lines) (src/hyperlight_host/src/hypervisor/virtual_machine/whp/x86_64.rs)
- Edited copies of one member (3 members, 42+ corresponding lines) (src/hyperlight_host/src/mem/shared_mem.rs)
- Edited copies of one member (3 members, 7+ corresponding lines) (src/hyperlight_host/src/hypervisor/virtual_machine/kvm/x86_64.rs)
- Edited copies of one member (3 members, 7+ corresponding lines) (src/hyperlight_host/src/hypervisor/virtual_machine/kvm/x86_64.rs)
- Edited copies of one member (3 members, 7+ corresponding lines) (src/hyperlight_host/src/hypervisor/virtual_machine/kvm/x86_64.rs)
- Edited copies of one member (4 members, 17+ corresponding lines) (src/hyperlight_common/src/virtq/ring.rs)
- …and 64 more
Changes since last survey
- 51 commits — 45 feature/other, 6 fixes
By area
- (root) — 16 commits
- .github/workflows — 14 commits
- src/hyperlight_host — 12 commits
- src/tests — 2 commits
- docs/github-labels.md — 1 commit
- docs/hyperlight-metrics-logs-and-traces.md — 1 commit
- proposals/0005-structured-labels — 1 commit
- proposals/0008-postcard-serialization — 1 commit
- proposals/0009-hip-streams — 1 commit
- src/hyperlight_component_csharp — 1 commit
- src/hyperlight_component_util — 1 commit
Notable commits
- fix: Fix C# rejection tests with the stricter WIT parser (#2049)
- fix: Fix flaky reset_vcpu_simple and log cpu in CI (#2018)
- fix: fix(ci): limit setup for golden checks and benchmark reports (#2031)
- fix: fix(guest): allow guest functions with more than 11 parameters (#1998)
- fix: fix(trace): read each guest trace batch once (#1991)
- fix: fix: avoid apple hypercalls and synchronize snapshot instruction caches (#2039)
- change: Add Sandbox::recreate to recover unrecoverable sandboxes (#1751)
- change: Add crate for host-side .net component bindings (#1946)
- change: Document structured label usage (#2010)
- change: Expose how much scratch a sandbox has allocated (#2019)
- change: HIP 0005 - Structured Labels (#1978)
- change: HIP 0008: Postcard serialization for host-guest messages (#1999)
- change: HIP 0009: add proposal for hyperlight streams (#1969)
- change: Layered/incremental snapshots (#1926)
- change: Migrate label automation (#2042)
- change: Moves the surrogate from the shared target\release\build\hls (#2038)
- change: Remove the legacy heap region from snapshots (#1968)
- change: Restore the guest TSC exactly on KVM (#2015)
- change: Restore the guest TSC exactly on WHP (#2022)
- change: Test guest CET access across KVM kernels (#2051)
- …and 31 more
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
hyperlight-dev/hyperlight was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 14 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit d652690b1c7f928465b20052ac3540dcadd863c3 — the exact code this score is about.
- Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.65+preprod-3c33c1882dc1.