DOCSEARCHbyAlgolia
Submit Docs

Hyperlight Documentation

repository·main·Indexed 26 days ago

https://github.com/hyperlight-dev/hyperlight

A lightweight VMM designed for running untrusted code in hypervisor-isolated micro VMs with millisecond startup times and microsecond function call latency. Optimized for high-density environments like functions-as-a-service (FaaS), Hyperlight provides libraries for implementing hosts and guests in Rust and C, including hyperlight-libc based on picolibc 1.8.11 and the hyperlight_guest_capi for C-API integration.

Tokens
37.4K
Snippets
72
Records
224
Agent score
88%

What's inside Hyperlight

  2. Create Hyperlight guests in C using hyperlight_guest_capi

    main

    The hyperlight_guest_capi crate provides a C-API wrapper over hyperlight-guest/hyperlight-guest-bin, enabling the development of Hyperlight guests using the C language. It generates platform-specific library files (.lib or .a) and the necessary header files for integration.

    For a practical implementation reference, see the c_simpleguest example in the tests/c_guests/c_simpleguest/ directory.

  3. Understand the Hyperlight security model and threat model

    main

    Hyperlight is designed to safely execute untrusted or potentially malicious guest code without compromising the host. The security model is built on three pillars:

    1. Hypervisor Isolation: Guest code runs in a Virtual Machine with access only to a pre-allocated memory buffer. No dynamic memory allocation is allowed, and no devices (files, network, etc.) are provided by default.
    2. Strict Communication: Host-guest communication occurs via a shared memory buffer using FlatBuffers. The host enforces strong typing by only accepting data that matches the formal FlatBuffer schemas defined in the project.
    3. Controlled Function Exposure: Guests can only access host functionality that has been explicitly registered and exposed by the host application. Any attempt to call unregistered functions will result in an error.

  4. Determine when to use Hyperlight

    main

    Use Hyperlight when:

    • You need hypervisor-level isolation for untrusted or third-party code.
    • You require millisecond startup times for sandboxes.
    • You need microsecond latency for guest function calls.
    • You want to embed sandboxed execution directly into an application.
    • You are building functions-as-a-service (FaaS) with hypervisor isolation.
    • You need to reuse sandboxes efficiently via snapshot/restore.

    Do NOT use Hyperlight for:

    • General-purpose virtualization (use a full VMM instead).
    • Running full Linux guest workloads that require syscalls, networking, or filesystem access.

  5. Understand the Hyperlight snapshot on-disk format

    main

    Hyperlight serializes a Snapshot to disk using the [OCI Image Layout] standard. This allows snapshots to be managed similarly to container images.

    Directory Layout

    A snapshot directory contains:

    • oci-layout: Specifies the OCI layout version.
    • index.json: Contains manifest descriptors for each tag, using the org.opencontainers.image.ref.name annotation.
    • blobs/sha256/: A content-addressable store containing:
      • manifest: A JSON pointer (application/vnd.oci.image.manifest.v1+json) referencing a config and a layer.
      • config: The snapshot descriptor (application/vnd.hyperlight.snapshot.config.v1+json) containing architecture, hypervisor, CPU vendor, ABI version, registers, and memory layout.
      • layer / memory: The raw guest memory image (application/vnd.hyperlight.snapshot.memory.v1) of exactly memory_size bytes.

  6. Understand Hyperlight VM execution model

    main

    Hyperlight is designed for creating micro virtual machines (VMs) optimized for small, short-running functions. Unlike traditional VM platforms, Hyperlight provides only minimal hardware isolation (vCPU and virtual memory) and shared memory between the host and the in-VM process (the "guest").

    To achieve high efficiency and low latency, Hyperlight excludes several standard VM features:

    • No Bootloader or OS kernel
    • No Virtual networking
    • No Virtual filesystem

    This makes it suitable for lightweight function execution rather than long-running, complex workloads.

  7. Understand the Hyperlight Improvement Process (HIP)

    main

    Hyperlight Improvement Proposals (HIPs) are a standardized development process used to communicate intent and maintain a historical record of motivations for Hyperlight enhancements. The process is modeled after the Kubernetes Enhancement Proposal (KEP) process but is scaled to fit the Hyperlight community.

    When to use a HIP

    A HIP is not required for all changes. You should only propose a HIP for significantly impacting work, such as:

    • Large refactorings
    • Significant feature enhancements
    • Breaking API changes

  9. Understand Hyperlight snapshot versioning axes

    main

    Hyperlight snapshots use three independent versioning axes to manage evolution. A change to any of these requires a version bump and potentially a compatibility path in the loader:

    1. Memory blob ABI (SNAPSHOT_ABI_VERSION): A u32 in the config blob. It defines the interface between host and guest, including OutBAction and VmAction port numbers, buffer stack formats, memory region offsets/sizes (including HyperlightPEB), and guest function calling conventions.
    2. Snapshot blob encoding (MT_SNAPSHOT_V1 / MT_SNAPSHOT_CURRENT): The on-wire OCI layer format, covering framing, section ordering, alignment, and byte packing.
    3. Config schema (MT_CONFIG_V1 / MT_CONFIG_CURRENT): The JSON structure of the config blob, including field names, types, and required descriptors (e.g., abi_version, hyperlight_version).

    Note: hyperlight_version (the host's CARGO_PKG_VERSION) is recorded in the config for diagnostics but does not gate loading.

  10. Understand Hyperlight core concepts

    main
    Hyperlight is a library designed to be embedded within a Host Application to provide hypervisor-isolated execution. It uses Sandboxes as an abstraction to create, configure, execute, and destroy Micro Virtual Machines that run Guest binaries. This architecture allows for low-latency execution of Workloads by running purpose-fit guest binaries instead of full operating systems.

  11. Understand Hyperlight Guest-aided Copy-on-Write (CoW) snapshots

    main

    Hyperlight uses a design where the guest is aware of a read-only snapshot and manages its own Copy-on-Write (CoW) operations to reduce the cost of Stage 2 translation page faults on Type 1 hypervisors.

    The guest physical address space is divided into two fundamental regions:

    1. Snapshot Region: Located at the very bottom of memory. It is a hypervisor-enforced read-only mapping of the base snapshot.
    2. Scratch Region: Located at the top of memory. A large area of blank, writable pages used for CoW operations and metadata.

    When a guest writes to a CoW page in the snapshot region, it must:

    1. Allocate a fresh page from the scratch region (using a bump allocator).
    2. Copy the content from the snapshot page to the new scratch page.
    3. Update the Page Table Entry (PTE) to point to the new scratch page and set it to R/W.

  12. Understand the Hyperlight Architecture

    main

    Hyperlight operates using two primary components that interact in a controlled manner:

    • Host library: Responsible for creating the Hyperlight VM (the "sandbox"), configuring vCPUs, virtual registers, and VM memory, loading the guest binary, and managing function calls. It marshals calls to "guest functions" inside the VM and dispatches "host functions" (callbacks) from the guest back into the host.
    • Guest binary: Code running inside the sandbox that dispatches calls from the host to specific guest functions and marshals calls to host functions.