# hyperlight-dev/hyperlight architecture

> Architecture diagram of the GitHub repository hyperlight-dev/hyperlight, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyperlight-dev/hyperlight
- Repository: https://github.com/hyperlight-dev/hyperlight

## Overview

##### Project Purpose and Type
- This project is a VMM library (and related toolchain) for embedding micro VMs into applications.
- Its purpose is to securely execute untrusted guest code using low-overhead virtualization. It targets both Windows (using Windows Hypervisor Platform and mshv) and Linux (using KVM) environments.
- The architecture comprises multiple libraries: a host library (managing the underlying virtual machine/sandbox), guest libraries (to facilitate guest development), and a common library (with shared utilities like flatbuffer wrappers).

##### Main Components
a. Hyperlight Host Library:
- Located in src/hyperlight_host.
- Responsible for creating and managing the sandboxed micro VMs, managing memory, handling system calls and virtualization integration (KVM, MSHV, WHP).
- Contains examples and test binaries as well as integration with host function calls.
b. Hyperlight Guest Library:
- Two flavors exist:
- The primary guest library (src/hyperlight_guest) is written in Rust.
- The C-compatible version (src/hyperlight_guest_capi) is used for guest applications that need a C interface.
- Both libraries work in tandem with the host by registering guest functions and calling host installations.
c. Hyperlight Common:
- Located in src/hyperlight_common.
- Includes shared code such as flatbuffer wrappers (for guest-host call serialization), memory and other common utilities.
d. Test and Example Guest Applications:
- Found in src/tests (Rust and C guests) as well as example directories in the hyperlight_host component.
- These demonstrate how to use the host and guest APIs.
e. Build, Configuration, and Infrastructure Items:
- Workflow configurations are provided in the .github directory, various Docker and development container files in .devcontainer, and build scripts (Justfile, Cargo.toml, etc.).
- Documentation assets in the docs directory illustrate the intended usage scenarios (debugging, metrics, etc.).
f. Integration with Virtualization:

- Shared “Hyperlight Common” module, positioned such that both the host and guest modules depend upon it.
– From the Host to a Guest: host calls exposed guest functions (e.g., PrintOutput).
– From the Guest to the Host: guest calls host functions (e.g., HostPrint or any registered host function).
- External components such as the underlying hypervisor:
– On UNIX-like systems: KVM.
– On Windows: WHP or mshv.
- Additionally, demonstrate that the integration is achieved with low overhead—indicate the “micro VM” or “sandbox” boundary.

##### Architectural Patterns and Design Principles
- Layered scheme: the lower layer (virtualization/hypervisor interface), the middle layer (host management and sandboxing), and the upper layers (guest libraries and development tools).
- Modularity: separate repositories or directories for host functionality, guest functionality, and common infrastructure.
- Clear separation of concerns: the host provides sandboxing and the guest provides application-specific behavior with a minimal exposed API.
- The use of flatbuffers for communication suggests a protocol-driven design to serialize and decode function call parameters/results.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Infrastructure Section
    subgraph "Build & Infrastructure"
        H["CI/CD Workflows"]:::build
        I["Dev Containers"]:::build
        J["Build Scripts"]:::build
        K["Documentation"]:::build
    end

    %% System Architecture Section
    subgraph "System Architecture"
        A["Hyperlight Host"]:::host
        B["Hyperlight Common"]:::common
        E["Hypervisor Interface (KVM,mshv/WHP)"]:::hypervisor

        subgraph "Sandbox"
            C["Hyperlight Guest (Rust)"]:::guest
            D["Hyperlight Guest C-API"]:::guest
        end

        %% Interactions between Host and Guest(s)
        A -->|"call_guest_func"| C
        A -->|"call_guest_func"| D
        C -->|"call_host_func"| A
        D -->|"call_host_func"| A

        %% Shared dependency on Common module
        A --- B
        C --- B
        D --- B

        %% Integration with Hypervisor
        A --- E
    end

    %% Examples & Tests Section
    subgraph "Examples & Tests"
        F["Examples (Host)"]:::example
        G["Test Applications"]:::test
    end

    %% Connecting Examples/Tests to Host to depict usage demonstrations
    F --> A
    G --> A

    %% Click Events for Component Mapping
    click A "https://github.com/hyperlight-dev/hyperlight/tree/main/src/hyperlight_host"
    click C "https://github.com/hyperlight-dev/hyperlight/tree/main/src/hyperlight_guest"
    click D "https://github.com/hyperlight-dev/hyperlight/tree/main/src/hyperlight_guest_capi"
    click B "https://github.com/hyperlight-dev/hyperlight/tree/main/src/hyperlight_common"
    click F "https://github.com/hyperlight-dev/hyperlight/tree/main/src/hyperlight_host/examples"
    click G "https://github.com/hyperlight-dev/hyperlight/tree/main/src/tests"
    click H "https://github.com/hyperlight-dev/hyperlight/tree/main/.github/workflows"
    click I "https://github.com/hyperlight-dev/hyperlight/blob/main/.devcontainer"
    click J "https://github.com/hyperlight-dev/hyperlight/tree/main/Justfile"
    click K "https://github.com/hyperlight-dev/hyperlight/tree/main/docs"

    %% Styles for different component types
    classDef host fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef guest fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef common fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef hypervisor fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef example fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef test fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef build fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
