hyperlight-guest 0.16.0

Provides only the essential building blocks for interacting with the host environment, including the VM exit mechanism, abstractions for calling host functions and receiving return values, and the input/output stacks used for guest-host communication.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

<div align="center">
    <h1>Hyperlight</h1>
    <img src="https://raw.githubusercontent.com/hyperlight-dev/hyperlight/refs/heads/main/docs/assets/hyperlight-logo.png" width="150px" alt="hyperlight logo"/>
    <p>
        <strong>A lightweight VMM for running untrusted code in micro VMs with minimal overhead.</strong><br>
        A <a href="https://www.cncf.io/projects/hyperlight/">Cloud Native Computing Foundation</a> sandbox project.
    </p>
</div>

> **Status:** Hyperlight is pre-1.0. The API may change between releases, and upgrading will sometimes require code changes.

Hyperlight lets you safely run untrusted code inside hypervisor-isolated micro VMs that spin up in milliseconds, with guest function calls completing in microseconds. You embed it as a library in your Rust application, hand it a guest binary, and call functions across the VM boundary as naturally as calling a local function. To minimize startup time and memory footprint, there's no guest kernel or OS. Guests are purpose-built using the Hyperlight guest library.

- Supports [KVM](https://linux-kvm.org/page/Main_Page), [MSHV](https://github.com/rust-vmm/mshv), and [Windows Hypervisor Platform](https://docs.microsoft.com/en-us/virtualization/api/#windows-hypervisor-platform)
- No kernel or OS in the VM. Guests are regular ELF binaries written in `no_std` Rust or C
- Host and guest communicate through typed function calls
- Guests are sandboxed by default with no access to the host filesystem, network, etc.

## Example

**Host** - create a sandbox, register a host function, and call into the guest:

```rust
// Create an uninitialized sandbox by giving it the path to a guest binary.
// Allocates memory but does not yet run a VM.
let mut sandbox = UninitializedSandbox::new(GuestBinary::FilePath(guest_path), None)?;

// Register a host function that the guest can call. In a real app this
// might query a database, read a config, or call an external API.
// By default, guests can only print to the host.
sandbox.register("GetWeekday", || Ok("Monday".to_string()))?;

// Initialize the sandbox. Starts the VM and runs guest setup code.
let mut sandbox: MultiUseSandbox = sandbox.evolve()?;

// Call a function inside the VM
let greeting: String = sandbox.call("SayHello", "World".to_string())?;
println!("{greeting}"); // "Hello, World! Today is Monday."
```

Guest state persists across calls. Use `snapshot()` and `restore()` to save and reset VM memory. This avoids recreating the VM while ensuring each call starts from a clean state.

**Guest** (Rust) - declare host functions and expose guest functions with simple macros. Guests can also be [written in C](./src/hyperlight_guest_capi).

```rust
#[host_function("GetWeekday")]
fn get_weekday() -> Result<String>;

#[guest_function("SayHello")]
fn say_hello(name: String) -> Result<String> {
    let weekday = get_weekday()?;
    Ok(format!("Hello, {name}! Today is {weekday}."))
}
```

To get started, see the [Getting Started](./docs/getting-started.md) guide. For more details on writing guests, see [How to build a Hyperlight guest binary](./docs/how-to-build-a-hyperlight-guest-binary.md).

## When to use Hyperlight

Hyperlight is a good fit when you need to:

- Run untrusted or third-party code with hypervisor-level isolation
- Create and tear down sandboxes in milliseconds
- Make guest function calls in microseconds
- Embed sandboxed execution directly in your application
- Build functions-as-a-service with hypervisor-level isolation
- Reuse sandboxes efficiently with snapshot and restore

Hyperlight is *not* designed for:

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

## Getting started

See [docs/getting-started.md](./docs/getting-started.md) for detailed prerequisites and platform-specific setup for:
- **Running** Hyperlight
- **Building guests**

Or skip setup entirely with a codespace:

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/hyperlight-dev/hyperlight)

## Repository Structure

| Directory | Description |
|---|---|
| [src/hyperlight_host](./src/hyperlight_host) | Host library - creates and manages micro VMs |
| [src/hyperlight_guest](./src/hyperlight_guest) | Core guest library - minimal building blocks for guest-host interaction |
| [src/hyperlight_guest_bin](./src/hyperlight_guest_bin) | Extended guest library - entry point, panic handler, heap, logging, exceptions |
| [src/hyperlight_guest_capi](./src/hyperlight_guest_capi) | C API wrapper around `hyperlight_guest_bin` for use via FFI |
| [src/hyperlight_libc](./src/hyperlight_libc) | C standard library for guests, built from picolibc |
| [src/hyperlight_guest_macro](./src/hyperlight_guest_macro) | Macros for registering guest and host functions |
| [src/hyperlight_guest_tracing](./src/hyperlight_guest_tracing) | Tracing support for guests |
| [src/hyperlight_common](./src/hyperlight_common) | Shared code used by both host and guest |
| [src/hyperlight_component_macro](./src/hyperlight_component_macro) | Proc macros for WIT-based host/guest bindings |
| [src/hyperlight_component_util](./src/hyperlight_component_util) | Shared implementation for WIT binding generation |
| [src/hyperlight_testing](./src/hyperlight_testing) | Shared test utilities |
| [src/schema](./src/schema) | FlatBuffer schema definitions |
| [src/trace_dump](./src/trace_dump) | Tool for dumping and visualizing trace data |
| [src/tests](./src/tests) | Test guest programs (Rust and C) |

## Related Projects

- [cargo-hyperlight](https://github.com/hyperlight-dev/cargo-hyperlight) - Cargo subcommand for building and scaffolding Hyperlight guests
- [hyperlight-wasm](https://github.com/hyperlight-dev/hyperlight-wasm) - Run WebAssembly modules inside Hyperlight micro VMs
- [hyperlight-js](https://github.com/hyperlight-dev/hyperlight-js) - Run JavaScript inside Hyperlight micro VMs
- [hyperlight-sandbox](https://github.com/hyperlight-dev/hyperlight-sandbox) - Multi-backend sandboxing framework for running untrusted code with controlled host capabilities, with Python, .NET, and Rust SDKs
- [hyperlight-unikraft](https://github.com/hyperlight-dev/hyperlight-unikraft) - Run Linux applications (Python, Node.js, Go, Rust, C/C++) on Hyperlight micro VMs using Unikraft as the guest kernel

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## Community

- **Meetings**: Every other Wednesday 09:00 PST/PDT ([convert to your time](https://dateful.com/convert/pst-pdt-pacific-time?t=09)). Agenda and join info in the [Community Meeting Notes](https://hackmd.io/blCrncfOSEuqSbRVT9KYkg#Agenda).
- **Slack**: [#hyperlight](https://cloud-native.slack.com/archives/hyperlight) on CNCF Slack ([join here](https://www.cncf.io/membership-faq/#how-do-i-join-cncfs-slack)).
- **Docs**: [`docs/` directory](./docs/README.md)
- **Code of Conduct**: [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md)

---

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fhyperlight-dev%2Fhyperlight.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fhyperlight-dev%2Fhyperlight?ref=badge_large)