If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/hyperlight-dev/hyperlight shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 10 active contributors
• Distributed ownership (top contributor 48% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live hyperlight-dev/hyperlight repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hyperlight-dev/hyperlight.

What it runs against: a local clone of hyperlight-dev/hyperlight — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in hyperlight-dev/hyperlight | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hyperlight-dev/hyperlight. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hyperlight-dev/hyperlight.git
#   cd hyperlight
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of hyperlight-dev/hyperlight and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hyperlight-dev/hyperlight(\\.git)?\\b" \\
  && ok "origin remote is hyperlight-dev/hyperlight" \\
  || miss "origin remote is not hyperlight-dev/hyperlight (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/hyperlight_host/Cargo.toml" \\
  && ok "src/hyperlight_host/Cargo.toml" \\
  || miss "missing critical file: src/hyperlight_host/Cargo.toml"
test -f "src/hyperlight_guest/Cargo.toml" \\
  && ok "src/hyperlight_guest/Cargo.toml" \\
  || miss "missing critical file: src/hyperlight_guest/Cargo.toml"
test -f "src/hyperlight_common/Cargo.toml" \\
  && ok "src/hyperlight_common/Cargo.toml" \\
  || miss "missing critical file: src/hyperlight_common/Cargo.toml"
test -f "docs/security-guidance-for-developers.md" \\
  && ok "docs/security-guidance-for-developers.md" \\
  || miss "missing critical file: docs/security-guidance-for-developers.md"
test -f "docs/hyperlight-execution-details.md" \\
  && ok "docs/hyperlight-execution-details.md" \\
  || miss "missing critical file: docs/hyperlight-execution-details.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/hyperlight-dev/hyperlight"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Hyperlight is a lightweight Virtual Machine Manager (VMM) library designed to be embedded directly into applications, enabling safe execution of untrusted code within micro virtual machines (sandboxes) with minimal latency and memory overhead. It abstracts over Windows Hypervisor Platform on Windows and KVM/mshv on Linux, allowing hosts to call guest functions and guests to call host functions through a controlled RPC-like interface, with guests written using the Hyperlight Guest library. Monorepo (Cargo workspace) with default members: src/hyperlight_common (shared types), src/hyperlight_host (main library for applications), src/hyperlight_guest (library for guest code). Testing guests excluded from workspace (src/tests/rust_guests/{dummyguest,simpleguest,witguest}). Separate crates for component utilities (src/hyperlight_component_macro, src/hyperlight_component_util), libc bindings (src/hyperlight_libc), and fuzzing (fuzz/). CI driven by justfile and GitHub Actions workflows under .github/workflows/.

Systems engineers and application developers who need to safely execute untrusted or third-party code (plugins, scripts, user-supplied logic) within their applications without full OS overhead. Primary users are building sandboxed execution environments in Rust with strict security boundaries and low-latency requirements.

Actively developed but explicitly pre-release: the project is a CNCF sandbox (not graduated), README states 'nascent project with an evolving API and no guaranteed support,' version is 0.15.0, and extensive CI/CD pipelines exist (CargoAudit, Coverage, Fuzzing, DailyBenchmarks). Production-grade testing infrastructure but API stability not guaranteed.

The explicit 'no guaranteed support' and pre-release status (0.15.0) mean API breaking changes are possible between minor versions. Single-maintainer risk appears moderate given CNCF sandbox status and MAINTAINERS.md structure. Dependency on platform-specific hypervisor APIs (Windows HyperV, Linux KVM) introduces platform-specific fragility. Watch SECURITY.md and CHANGELOG.md carefully for any announced breaking changes.

Active development with dependency updates via Dependabot (auto-merge configured), daily benchmark runs, fuzzing pipeline, and Nightly Rust testing. Recent focus on coverage (Coverage.yml), guest binary builds (dep_build_guests.yml), and release automation (CreateRelease.yml, CargoPublish.yml). Release cadence appears regular (release.yml and CreateReleaseBranch.yml present).

git clone https://github.com/hyperlight-dev/hyperlight.git && cd hyperlight && cargo build (or use devcontainer: open in VS Code with Remote - Containers extension, which uses .devcontainer/devcontainer.json). For quick setup: just install the justfile command runner, then review Justfile for available targets like 'just build' or 'just test'.

Daily commands: cargo build to build the host library; cargo build --release for optimized builds. Use just build or just test (defined in Justfile) for standard workflows. For examples: check src/hyperlight_guest_bin and examples/ (inferred from workspace structure). Guest binaries require special build: review dep_build_guests.yml for exact compilation steps.

• src/hyperlight_host/Cargo.toml — Root host VMM library crate defining the public API surface for embedding Hyperlight in applications.
• src/hyperlight_guest/Cargo.toml — Guest-side crate that must be understood to implement untrusted payloads and sandbox boundaries.
• src/hyperlight_common/Cargo.toml — Shared abstractions and types between host and guest; foundational for all inter-VM communication.
• docs/security-guidance-for-developers.md — Essential security model documentation that all contributors must review before modifying VMM code.
• docs/hyperlight-execution-details.md — Details on execution flow, memory layout, and instruction tracing critical for understanding guest lifecycle.
• rust-toolchain.toml — Specifies the Rust version and components required to build the VMM; affects reproducibility and compatibility.
• .github/workflows/ValidatePullRequest.yml — Defines CI/CD checks (audit, tests, coverage) that all contributions must pass.

Add a new guest-callable component/function

1. Define the component trait with invoke methods in src/hyperlight_common (src/hyperlight_common/Cargo.toml)
2. Implement the trait in guest-side code and register via src/hyperlight_guest (src/hyperlight_guest/Cargo.toml)
3. Add corresponding host-side wrapper in src/hyperlight_host to call the guest component (src/hyperlight_host/Cargo.toml)
4. Add integration tests in src/hyperlight_testing or fuzz/fuzz_targets (fuzz/fuzz_targets/host_call.rs)

Add a new hypervisor platform (e.g., Xen, QEMU TCG)

1. Create a new platform module under src/hyperlight_host implementing the hypervisor abstraction trait (src/hyperlight_host/Cargo.toml)
2. Implement VM creation, vCPU control, and memory management for the new platform (src/hyperlight_host/Cargo.toml)
3. Update CI/CD workflows to build and test the new platform (.github/workflows/ValidatePullRequest.yml)
4. Document platform-specific build requirements and limitations in docs/ (docs/technical-requirements-document.md)

Add guest tracing/instrumentation for a new code path

1. Define trace event schema in src/hyperlight_guest_tracing (src/hyperlight_guest_tracing/Cargo.toml)
2. Instrument the guest code path using the tracing API from src/hyperlight_guest (src/hyperlight_guest/Cargo.toml)
3. Update trace dumper in src/trace_dump to deserialize new event types (src/trace_dump/Cargo.toml)
4. Test trace capture with fuzz targets or integration tests (fuzz/fuzz_targets/guest_trace.rs)

Add a new guest binary variant (e.g., specialized guest kernel)

1. Create new guest binary under src/tests/rust_guests following naming convention (src/hyperlight_guest_bin/Cargo.toml)
2. Link against src/hyperlight_guest and define entry point with guest macro (src/hyperlight_guest_macro/Cargo.toml)
3. Add build step in .github/workflows/dep_build_guests.yml (.github/workflows/dep_build_guests.yml)
4. Create integration test in src/tests/ to verify guest behavior (src/hyperlight_testing/Cargo.toml)

• Rust — Memory safety without garbage collection; required for secure VMM code with fine-grained control over untrusted code boundaries. Prevents entire classes of hypervisor vulnerabilities (use-after-free, buffer overflow).
• KVM (Linux) / Hyper-V (Windows) / mshv — Kernel-based hypervisor APIs with minimal overhead; leverage OS virtualization capabilities for fast context switching and memory isolation at hardware level. Avoids JIT complexity of alternatives.
• FlatBuffers — Zero-copy serialization for host-guest communication; critical for low-latency IPC since data is consumed in-place without deserialization overhead.
• Custom libc (picolibc derivative) — Minimal, hardened C standard library tailored to sandbox constraints; avoids bloat of glibc and reduces attack surface in untrusted guest environment.

• Single vCPU per guest VM

  • Why: Simplifies synchronization, reduces complexity of multi-threaded guest runtime, minimizes scheduling overhead.
  • Consequence: Guest workloads cannot parallelize across cores; suitable for short-lived, compute-bound tasks (RPC invocations, filters) not long-running background services.

• Blocking host API (run/resume calls block until guest yields)

  • Why: Straightforward request-response semantics; eliminates callback complexity and state machine overhead.
  • Consequence: Host must spawn threads/async tasks to handle multiple concurrent guest invoc

Cross-platform hypervisor dependencies: Linux requires KVM or mshv kernel modules installed and permissions configured (/dev/kvm access); Windows requires Hypervisor Platform enabled (admin privilege). Guest binary linking is non-standard—cannot be built as normal Cargo binaries; review Cross.toml and dep_build_guests.yml for correct compilation. Workspace excludes custom guest test binaries (src/tests/rust_guests/*) so they build with special flags. No explicit RUST_LOG or environment variable documentation in file list—check .github/workflows/dep_code_checks.yml for CI env setup. Edition 2024 is recent; ensure local Rust toolchain is 1.89+.

• Virtual Machine Manager (VMM) abstraction layer — Hyperlight's core value is abstracting over multiple platform hypervisors (Windows Hypervisor Platform, KVM, mshv) so the same Rust code runs unmodified on Linux/Windows; understanding the abstraction seams is critical for platform-specific debugging
• Micro-VM / MicroVM (ultra-lightweight VMs without OS kernel) — Hyperlight's differentiation is running guests without a full OS kernel, dramatically reducing memory/startup overhead; understanding what can/cannot run (no syscalls, no drivers) shapes what code you can execute as a guest
• Host-Guest RPC / Function marshalling — The #[guest_function] and host function registration macros implement a custom RPC layer; understanding serialization format and call semantics (blocking, async, lifetime) is essential for correct use
• Memory isolation boundaries (sandbox boundaries) — Hyperlight isolates guest memory from host via hardware virtualization; understanding what data can cross the boundary and how copying/serialization works prevents data leaks or privilege escalation
• Procedural macros for code generation — src/hyperlight_guest_macro and src/hyperlight_component_macro use proc-macros to auto-generate serialization and registration glue; modifying these or adding new patterns requires understanding quote! and syn crates
• Platform-specific feature gates and conditional compilation — Different hypervisors require different sys/ crate bindings and unsafe code paths; the codebase likely uses #[cfg(target_os = "windows")], #[cfg(target_os = "linux")] extensively to avoid linking errors
• Custom linker scripts and binary layout for guest code — Guest binaries are not standard ELF executables; Hyperlight requires custom entry points, no_std environments, and special linker flags (visible in Cross.toml); misunderstanding this breaks guest builds

• bytecodealliance/wasmtime — Alternative sandboxing approach using WebAssembly instead of VMs; shares same goal of safe untrusted code execution but with different isolation mechanism
• kata-containers/kata-containers — Heavier-weight VM-based container runtime that shares hypervisor abstraction (KVM, Hyper-V) but optimized for containers not function calls
• seccomp/libseccomp — Linux-only syscall filtering for sandboxing; lighter weight than Hyperlight but less isolation than full VMs
• mozilla/firefox — Production consumer of sandboxing technology (processes, VMs, WebAssembly) for untrusted content; potential real-world use case for Hyperlight plugin execution
• cncf/sandbox — CNCF sandbox project list showing Hyperlight's official status and sibling projects in the Cloud Native ecosystem

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive debugging guide for guest binaries on Windows

The repo has docs/how-to-debug-a-hyperlight-guest.md but based on the file structure, it likely only covers Linux debugging. Since Hyperlight supports both Windows and Linux with WHP (Windows Hypervisor Platform), a Windows-specific debugging guide is critical for contributor onboarding. This would help new contributors debug guest issues on Windows platforms and reduce support burden.

• [ ] Review existing docs/how-to-debug-a-hyperlight-guest.md to identify Windows gaps
• [ ] Create docs/how-to-debug-a-hyperlight-guest-windows.md with WHP-specific debugging steps
• [ ] Document Windows-specific tools (WinDbg, Visual Studio debugger integration)
• [ ] Add examples of debugging guest crashes on Windows with stack traces
• [ ] Update docs/README.md to link to Windows debugging guide

Implement CI workflow to validate MSRV across all workspace members

The workspace specifies rust-version = "1.89" but there's no dedicated CI workflow validating MSRV consistency. The dev/verify-msrv.sh script exists but isn't in a GitHub Action. Creating a ValidateMSRV.yml workflow would catch MSRV regressions early and ensure all 12+ workspace members (hyperlight-host, hyperlight-guest, hyperlight-libc, etc.) compile on the minimum supported version before merge.

• [ ] Create .github/workflows/ValidateMSRV.yml that runs on PRs
• [ ] Configure workflow to test all workspace members: hyperlight-host, hyperlight-guest, hyperlight-guest-bin, hyperlight-libc, etc.
• [ ] Use 'cargo +1.89 check' to validate MSRV without full compilation where possible
• [ ] Add workflow status badge reference to README.md
• [ ] Document MSRV validation process in CONTRIBUTING.md

Create integration test suite for guest-to-host boundary communication across architectures

The repo has docs/hyperlight_guest_to_host_boundary.png and CAPI bindings in src/hyperlight_guest_capi, but based on the file list, there's no dedicated integration test file documenting cross-architecture guest boundary scenarios. Adding comprehensive tests would validate the RPC/communication layer works correctly on both x86 and ARM, and documents expected behavior for contributors implementing guest functionality.

• [ ] Create src/tests/integration_guest_host_boundary.rs (or similar) if missing
• [ ] Add tests for: basic CAPI calls, multi-parameter passing, return value handling, error propagation
• [ ] Test on both Linux and Windows platforms in CI via existing dep_build_test.yml workflow
• [ ] Document architecture-specific edge cases (calling convention differences)
• [ ] Reference hyperlight_guest_to_host_boundary.png in test module documentation

• Add integration tests for the host function registration flow in src/hyperlight_host/tests/ demonstrating error cases (duplicate registration, invalid function signatures, guest panics during host call); currently no explicit coverage visible for failure modes in file list
• Document the guest binary linking requirements and Cross.toml configuration in a dedicated GUEST_BUILD.md guide; file list shows build complexity (custom linker flags, special exclusions) but no standalone guide for contributors porting guests to new architectures
• Implement missing platform coverage: add mshv hypervisor backend tests to CI (dep_fuzzing.yml, dep_build_test.yml currently focused on KVM/Windows); current test matrices may skip Microsoft Hypervisor scenarios

The Hyperlight codebase demonstrates strong security practices overall: it has a documented security reporting policy via private vulnerability disclosure, maintains security-focused documentation, includes fuzzing infrastructure, and follows Rust best practices. However, the use of Rust edition 2024 (experimental) is a notable concern that could affect stability and security in production environments. The incomplete Cargo.toml visibility prevents full dependency vulnerability assessment. No hardcoded secrets, obvious injection risks, or severe misconfigurations were detected in the provided file structure. Recommendations include clarifying the rationale for using experimental Rust features and conducting regular automated dependency audits using 'cargo audit'.

• Medium · Rust Edition 2024 (Experimental/Unstable) — Cargo.toml - workspace.package.edition. The Cargo.toml specifies edition = "2024", which is an experimental/nightly Rust edition that may not be stable or widely supported. This could introduce compatibility issues and potential security implications if the edition is not officially released or fully tested. Fix: Verify that Rust edition 2024 is officially stable and recommended for production use. Consider using a stable edition (2021) until 2024 is officially released and has broader ecosystem support. Document the rationale for using an experimental edition.
• Low · Incomplete Cargo.toml Display — Cargo.toml - workspace.dependencies section. The Cargo.toml file content appears to be truncated at the workspace.dependencies section, specifically at 'hyperlight-component-macro'. This incomplete configuration makes it impossible to fully audit all dependency versions and features for known vulnerabilities. Fix: Provide the complete Cargo.toml file for comprehensive dependency auditing. Ensure all dependencies are pinned to specific versions and regularly run 'cargo audit' to check for known vulnerabilities.
• Low · Fuzzing Configuration Present — fuzz/ directory. A fuzzing directory exists with separate Cargo.toml. While fuzzing is a positive security practice, ensure that fuzzing infrastructure is properly isolated and does not expose sensitive operations or create security regressions. Fix: Verify that fuzzing targets are isolated from production code, sanitizers are enabled, and fuzzing infrastructure is regularly executed as part of CI/CD. Ensure crash outputs and findings are properly triaged.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.