hyperlight-host 0.17.0

A lightweight Virtual Machine Manager that can be hosted in an application to safely run untrusted or code within a VM partition with very low latency and overhead.
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

// SPDX-License-Identifier: Apache-2.0
// Copyright 2025 The Hyperlight Authors.

use std::path::PathBuf;

use hyperlight_host::{MultiUseSandbox, SandboxBuilder};
use hyperlight_testing::{c_simple_guest_as_pathbuf, simple_guest_as_pathbuf};

/// Returns the path to the Rust simple guest binary.
fn rust_guest_path() -> PathBuf {
    simple_guest_as_pathbuf()
}

/// Returns the path to the C simple guest binary.
fn c_guest_path() -> PathBuf {
    c_simple_guest_as_pathbuf()
}

// =============================================================================
// Rust guest helpers
// =============================================================================

/// Builds a Rust guest MultiUseSandbox, applying `configure` to the builder.
pub fn build_rust_sandbox<C>(configure: C) -> MultiUseSandbox
where
    C: FnOnce(SandboxBuilder) -> SandboxBuilder,
{
    configure(SandboxBuilder::from_file(rust_guest_path()))
        .build()
        .unwrap()
}

/// Creates a new Rust guest MultiUseSandbox.
pub fn new_rust_sandbox() -> MultiUseSandbox {
    build_rust_sandbox(|builder| builder)
}

/// Runs a test with a Rust guest MultiUseSandbox.
pub fn with_rust_sandbox<F>(f: F)
where
    F: FnOnce(MultiUseSandbox),
{
    f(new_rust_sandbox());
}

/// Runs a test with a Rust guest MultiUseSandbox built with `configure`.
pub fn with_rust_sandbox_from<C, F>(configure: C, f: F)
where
    C: FnOnce(SandboxBuilder) -> SandboxBuilder,
    F: FnOnce(MultiUseSandbox),
{
    f(build_rust_sandbox(configure));
}

// =============================================================================
// C guest helpers
// =============================================================================

/// Builds a C guest MultiUseSandbox, applying `configure` to the builder.
pub fn build_c_sandbox<C>(configure: C) -> MultiUseSandbox
where
    C: FnOnce(SandboxBuilder) -> SandboxBuilder,
{
    configure(SandboxBuilder::from_file(c_guest_path()))
        .build()
        .unwrap()
}

/// Runs a test with a C guest MultiUseSandbox.
pub fn with_c_sandbox<F>(f: F)
where
    F: FnOnce(MultiUseSandbox),
{
    f(build_c_sandbox(|builder| builder));
}

/// Runs a test with a C guest MultiUseSandbox built with `configure`.
pub fn with_c_sandbox_from<C, F>(configure: C, f: F)
where
    C: FnOnce(SandboxBuilder) -> SandboxBuilder,
    F: FnOnce(MultiUseSandbox),
{
    f(build_c_sandbox(configure));
}

// =============================================================================
// Both guests helpers (run test with Rust AND C guests)
// =============================================================================

/// Runs a test once per guest binary, passing the path to it.
///
/// Use this when the test needs to configure the sandbox itself, for instance
/// to register a host function that owns per-guest state.
pub fn with_all_guests<F>(f: F)
where
    F: Fn(PathBuf),
{
    for path in [rust_guest_path(), c_guest_path()] {
        f(path);
    }
}

/// Runs a test with both Rust and C guest MultiUseSandboxes.
pub fn with_all_sandboxes<F>(f: F)
where
    F: Fn(MultiUseSandbox),
{
    with_all_guests(|path| {
        f(SandboxBuilder::from_file(path).build().unwrap());
    });
}