Create sandboxes directly from snapshots by ludfjig · Pull Request #1459 · hyperlight-dev/hyperlight

ludfjig · 2026-05-15T07:07:10Z

Builds a ready-to-use MultiUseSandbox directly from an Arc<Snapshot> without going through UninitializedSandbox + evolve(). Building block for OCI-backed snapshot loading on a follow-up branch.

Adds:

HostFunctions newtype around the internal FunctionRegistry. default() pre-registers HostPrint, empty() starts empty.
MultiUseSandbox::from_snapshot(snap, host_funcs, cfg). Snapshot is the source of truth for layout. cfg is honored for non-layout fields (timeouts, debug info, interrupt retry delay).
Snapshot records host function metadata. from_snapshot rejects registries missing functions or with mismatched signatures. Pre-init snapshots record nothing and accept any registry, matching the UninitializedSandbox contract.
gdb support extended to sandboxes built via from_snapshot.

Recommend to review commit-by-commit

Copilot

Pull request overview

Adds the ability to construct a MultiUseSandbox directly from an Arc<Snapshot>, bypassing UninitializedSandbox + evolve(). Snapshots now record the host functions registered at capture time, and the new constructor validates that the provided host-function set is a superset of those required. The gdb entry-point breakpoint mechanism is reworked into a one-shot tracked on the VM so it works for both Initialise and Call snapshots.

Changes:

New HostFunctions newtype (with default() pre-registering HostPrint and new() empty) and MultiUseSandbox::from_snapshot(snap, host_funcs, cfg).
Snapshot now carries HostFunctionDetails and exposes validate_host_functions to reject missing/mismatched signatures; pre-init snapshots accept any registry.
Gdb support: replaces VcpuStopReason::EntryPointBp with a one_shot_entry_bp field cleared by the run loop; entry breakpoint installed for both Initialise and Call entries; new gdb e2e test for snapshot path.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/hyperlight_host/src/sandbox/initialized_multi_use.rs	Implements `from_snapshot`, layout-override warning, snapshot host-function plumbing, and tests.
src/hyperlight_host/src/sandbox/snapshot/mod.rs	Adds `host_functions` field and `validate_host_functions`; updates constructors and tests.
src/hyperlight_host/src/sandbox/host_funcs.rs	Adds `HostFunctions` newtype and `with_default_host_print`; changes `register_host_function` to infallible; tweaks `From` impl.
src/hyperlight_host/src/sandbox/uninitialized.rs	Uses `with_default_host_print` and removes redundant `register_print` call in `new`.
src/hyperlight_host/src/func/host_functions.rs	Adapts `Registerable` impls to infallible registry call; adds `HostFunctions` impl.
src/hyperlight_host/src/mem/mgr.rs	Plumbs `HostFunctionDetails` into `snapshot()`; inherits `snapshot_count` in `from_snapshot`.
src/hyperlight_host/src/mem/layout.rs	Widens visibility of several layout fields and `MAX_MEMORY_SIZE`.
src/hyperlight_host/src/lib.rs	Re-exports `HostFunctions`.
src/hyperlight_host/src/hypervisor/hyperlight_vm/x86_64.rs	Sets up one-shot entry breakpoint covering `Initialise` and `Call`.
src/hyperlight_host/src/hypervisor/hyperlight_vm/mod.rs	Adds `one_shot_entry_bp` field and run-loop logic to clear it on first hit.
src/hyperlight_host/src/hypervisor/gdb/mod.rs	Removes `VcpuStopReason::EntryPointBp` variant.
src/hyperlight_host/src/hypervisor/gdb/event_loop.rs	Drops handling for the removed variant.
src/hyperlight_host/src/hypervisor/gdb/arch.rs	`vcpu_stop_reason` no longer takes/uses the entrypoint, becomes side-effect-free classifier.
src/hyperlight_host/examples/guest-debugging/main.rs	Extracts gdb test helpers and adds `test_gdb_from_snapshot`.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

jsturtevant

LGTM, I've left a few comments and one missing testing that needs a fix

jsturtevant · 2026-05-19T18:44:48Z

+
+        // Validate that the provided host functions are a superset of
+        // those required by the snapshot.
+        snapshot.validate_host_functions(&host_funcs)?;


I assume the snapshot manager does other validation? Should this validation live with that validation? if not are we missing validation? Can a maliciously crafted snapshot bypass any assumptions we have about the memory layout?

There's no way to create malicious snapshots (yet). Right now they are completely opaque structs to the user. This will change when we load them from disk though (future PR, where I add a lot of validation)

(future PR, where I add a lot of validation)

Glad to hear we are planning this. What if a malicious guest does something (writes some handcrafted assembly) and we take a snapshot with that in there?

danbugs

Mostly LGTM!

danbugs · 2026-05-20T16:57:05Z

    }

    /// Create a snapshot with the given mapped regions
+    #[allow(clippy::too_many_arguments)]


Should we consider a snapshot builder to avoid this?

Hmm I don't think so, none of these are really optional in that sense

danbugs · 2026-05-20T17:00:30Z

+        let mgr = crate::mem::mgr::SandboxMemoryManager::from_snapshot(&snapshot)?;
+        let (mut hshm, gshm) = mgr.build()?;
+
+        let page_size = u32::try_from(page_size::get())? as usize;


Hm--just noticed set set_up_hypervisor_partition takes a usize page_size but vm.initialise takes a u32. Can we improve this to avoid the casts?

good point, but I'd prefer to fix this in follow up. I don't think we should require both methods to take in page size as well, that seems strange

danbugs · 2026-05-20T17:04:25Z

+    /// produced by a test-only constructor) accepts any `provided`
+    /// set.
+    pub(crate) fn validate_host_functions(&self, provided: &crate::HostFunctions) -> Result<()> {
+        let required = match &self.host_functions.host_functions {


nit: host_functions.host_functions

Agree. I can fix this in follow up as well

danbugs · 2026-05-20T17:12:37Z

+        for req in required {
+            match provided_funcs
+                .iter()
+                .find(|f| f.function_name == req.function_name)


Can we improve this lookup? For every req function, we look at all provided functions (i.e., O(req * provided)). What if we built a HashMap for the provided functions? This way we'd have a O(provided + req)?

good point let me investigate. HostFunc is already based on HashMap

danbugs · 2026-05-20T17:16:22Z

+            let sregs = snapshot.sregs().ok_or_else(|| {
+                crate::new_error!("snapshot with NextAction::Call must have captured sregs")
+            })?;
+            vm.apply_sregs(hshm.layout.get_pt_base_gpa(), sregs)


Might be worth adding a comment that this is overwriting the apply_sregs from vm.initialise?

it's not, vm.initialize is a noop

danbugs · 2026-05-20T17:18:51Z


+    /// Construct the (out_file_path, cmd_file_path, manifest_dir)
+    /// triple every gdb test needs.
+    fn gdb_test_paths(name: &str) -> (String, String, String) {


GDB changes look good to me, but it might be worth getting @dblnz to have a look :)

agree I would be more confident if @dblnz took a look as well :)

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

ludfjig added the kind/enhancement For PRs adding features, improving functionality, docs, tests, etc. label May 15, 2026

ludfjig marked this pull request as ready for review May 15, 2026 07:10

ludfjig requested review from andreiltd, danbugs, dblnz, devigned, jprendes, jsturtevant, simongdavies and syntactically as code owners May 15, 2026 07:10

danbugs requested a review from Copilot May 15, 2026 16:26

Copilot started reviewing on behalf of danbugs May 15, 2026 16:30 View session

Copilot AI reviewed May 15, 2026

View reviewed changes

ludfjig force-pushed the from_snapshot branch from 9b3d8bf to 0220bdc Compare May 15, 2026 17:29

ludfjig added 4 commits May 19, 2026 09:56

Introduce HostFunctions newtype for sandbox construction

017328c

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

Expose SandboxMemoryLayout fields to crate

7b0eff1

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

Capture host function metadata in Snapshot

dc206ab

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

Make gdb work for already initialised snapshots

59c9a35

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

ludfjig force-pushed the from_snapshot branch from 0220bdc to ae2ede9 Compare May 19, 2026 16:57

jsturtevant reviewed May 19, 2026

View reviewed changes

ludfjig force-pushed the from_snapshot branch from ae2ede9 to 60f1f7f Compare May 19, 2026 20:21

danbugs reviewed May 20, 2026

View reviewed changes

ludfjig mentioned this pull request May 20, 2026

Save/load snapshot from disk (oci format) #1465

Draft

ludfjig added 3 commits May 20, 2026 11:27

Add MultiUseSandbox from_snapshot

3cf5d2c

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

Add gdb test for MultiUseSandbox from_snapshot

61f0625

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

Add tests for MultiUseSandbox from_snapshot

6152b7e

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

ludfjig force-pushed the from_snapshot branch from 60f1f7f to 6152b7e Compare May 20, 2026 18:28

Conversation

ludfjig commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jsturtevant left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ludfjig May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

danbugs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ludfjig May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ludfjig commented May 15, 2026 •

edited

Loading

ludfjig May 19, 2026 •

edited

Loading

ludfjig May 20, 2026 •

edited

Loading