Add SandboxBuilder by jprendes · Pull Request #1725 · hyperlight-dev/hyperlight

jprendes · 2026-08-12T11:30:45Z

Description

SandboxBuilder is the entry point for creating a sandbox. It gathers machine configuration, host functions, init data and memory mappings, then builds a MultiUseSandbox from a guest binary on disk, a guest binary in memory, or a snapshot.

It merges the roles of SandboxConfiguration, GuestEnvironment and UninitializedSandbox into a single type, so all three can become implementation details.

Every setting has an in place accessor taking &mut self and a with_* counterpart consuming self for chaining. Machine configuration values are readable through get_*.

map_memory_region is unsafe, matching MultiUseSandbox::map_region. The mapped region must stay valid for the lifetime of the built sandbox.

build_from_snapshot errors when init_data or max_guest_log_level are set, as a snapshot already carries both.

Scope

This PR only adds the new API, it does not deprecate any old API, and does not replace the use of the old API throughout the repo.

`SandboxBuilder` is the entry point for creating a sandbox. It gathers machine configuration, host functions, init data and memory mappings, then builds a `MultiUseSandbox` from a guest binary on disk, a guest binary in memory, or a snapshot. It merges the roles of `SandboxConfiguration`, `GuestEnvironment` and `UninitializedSandbox` into a single type, so all three can become implementation details. Every setting has an in place accessor taking `&mut self` and a `with_*` counterpart consuming `self` for chaining. Machine configuration values are readable through `get_*`. `map_memory_region` is `unsafe`, matching `MultiUseSandbox::map_region`. The mapped region must stay valid for the lifetime of the built sandbox. `build_from_snapshot` errors when `init_data` or `max_guest_log_level` are set, as a snapshot already carries both. Signed-off-by: Jorge Prendes <jorge.prendes@gmail.com>

Copilot

Pull request overview

This PR introduces a new SandboxBuilder API in hyperlight_host as the primary entry point for configuring and constructing MultiUseSandbox instances from a guest binary (file or bytes) or from a snapshot, consolidating configuration, host-function registration, init data, and memory mappings into one builder type.

Changes:

Added sandbox::builder::SandboxBuilder with build_from_file, build_from_bytes, and build_from_snapshot constructors plus with_*/in-place setters.
Exposed MultiUseSandbox::builder() and re-exported SandboxBuilder from hyperlight_host.
Adjusted host function registry internals to support builder-driven registration.

Reviewed changes

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

Show a summary per file

File	Description
src/hyperlight_host/src/sandbox/mod.rs	Exposes the new `builder` module under `sandbox`.
src/hyperlight_host/src/sandbox/initialized_multi_use.rs	Adds `MultiUseSandbox::builder()` entry point returning a default `SandboxBuilder`.
src/hyperlight_host/src/sandbox/host_funcs.rs	Loosens visibility of `FunctionRegistry::functions_map` to support builder registration.
src/hyperlight_host/src/sandbox/builder.rs	New builder implementation + unit tests for building from file/bytes/snapshot.
src/hyperlight_host/src/lib.rs	Re-exports `SandboxBuilder` from the crate root.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

jprendes · 2026-08-12T11:51:22Z

+}
+
+impl SandboxBuilder {
+    /// Create a builder with the default configuration and no host functions.


HostPrint is always available, this is the same as the existing behaviour.

true, but maybe we can word it something like ".. and no additional host functions" to avoid confusion?

jsturtevant · 2026-08-13T22:16:27Z

This PR only adds the new API, it does not deprecate any old API, and does not replace the use of the old API throughout the repo.

I like that this just simplifies the API, and would be an almost drop in for https://github.com/hyperlight-dev/hyperlight-sandbox which I would be able to reduce the code there.

What do propose for plans to depreciate the older apis? I think this would provide a bit more flexibility to do things internally

andreiltd

A big fan of this PR 🚀

jprendes · 2026-08-14T13:04:27Z

I should have dropped this link in the PR description.
Here's the document describing the API https://hackmd.io/SdWE6fKSShifX-2_DlY4Fw

At the end of the document I added how we can deprecate the old API

We have 3 deprecation levels, in increasing severity:

#[doc(hidden)]: the types disappear from rustdoc and from code completion,
so new code stops reaching for them. Nothing downstream breaks.
#[deprecated]: existing users get a compiler warning pointing at the
builder, or an error where warnings are denied.
pub(crate): the types leave the public API. A breaking change, and the only
one of the three that guarantees no downstream use remains.

Applying #[doc(hidden)] and #[deprecated] together in one release, then
pub(crate) in the next, is the recommended path. The first release hides the
types from new code and warns existing users, the second removes them from the
public API.

I'd be happy to hear different opinions.

ludfjig

I like this! Only one concern:

Looks like pr is missing newly added guest_msrs config.

Some minor things:

Would it be possible to somehow allow multiple sandboxes to be created from a builder? Or have builder be clonable? Just thinking about ergonomics if multiple identical sandboxes are to be created (I understand this might not be easy with host functions...)
Also bikeshedding if any apis should be renamed (my candiadates are max_guest_log_level, map_file_cow, map_memory_region) but not blocking for this pr...
Could you add this builder addition to CHANGELOG.md?
Do we want to consider adding the possiblity of having sandboxes without any host functions (including no hostprint?)

ludfjig · 2026-08-14T16:57:56Z

+/// Builds a [`Sandbox`].
+///
+/// Start from [`SandboxBuilder::new`], adjust settings through the `with_*`
+/// (consuming, chainable) or bare-named (in place) accessors, then call one of
+/// the `build_from_*` methods to create the sandbox from a guest binary on
+/// disk, a guest binary in memory, or a [`Snapshot`]. Every setting has a
+/// default, so a builder with no adjustments is valid.
+#[derive(Default)]
+pub struct SandboxBuilder {


Maybe a rustdoc example showing off relevant apis could be a good addition

ludfjig · 2026-08-14T17:02:06Z

+    }
+
+    /// Like [`Self::max_guest_log_level`], but consumes and returns `self` for chaining.
+    pub fn with_max_guest_log_level(mut self, level: LevelFilter) -> Self {


thinking about if we can name this something better...

ludfjig · 2026-08-14T17:13:57Z

+        let host_funcs = self.host_funcs.into_inner().functions_map;
+        for (func_name, func_entry) in host_funcs {
+            func_registry.register_host_function(func_name, func_entry);
+        }


this will re-register default hostprint host function (which is probably fine...?)

Copilot AI lite review requested due to automatic review settings August 12, 2026 11:30

jprendes requested review from andreiltd, danbugs, dblnz, devigned, jsturtevant, ludfjig, simongdavies, squillace and syntactically as code owners August 12, 2026 11:30

jprendes added the area/API Related to the API or public interface label Aug 12, 2026

Copilot started reviewing on behalf of jprendes August 12, 2026 11:31 View session

jprendes force-pushed the builder branch from adce75e to d0e9792 Compare August 12, 2026 11:31

Copilot AI reviewed Aug 12, 2026

View reviewed changes

andreiltd approved these changes Aug 14, 2026

View reviewed changes

ludfjig requested changes Aug 14, 2026

View reviewed changes

Navigation Menu

Uh oh!

Add SandboxBuilder - #1725

Add SandboxBuilder#1725
jprendes wants to merge 1 commit into
hyperlight-dev:mainfrom
jprendes:builder

jprendes commented Aug 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

jprendes Aug 12, 2026

Uh oh!

ludfjig Aug 14, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jsturtevant commented Aug 13, 2026

Uh oh!

andreiltd left a comment

Uh oh!

jprendes commented Aug 14, 2026

Uh oh!

ludfjig left a comment

Uh oh!

ludfjig Aug 14, 2026

Uh oh!

ludfjig Aug 14, 2026

Uh oh!

ludfjig Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

jprendes commented Aug 12, 2026

Description

Scope

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

jprendes Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

ludfjig Aug 14, 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jsturtevant commented Aug 13, 2026

Uh oh!

andreiltd left a comment

Choose a reason for hiding this comment

Uh oh!

jprendes commented Aug 14, 2026

Uh oh!

ludfjig left a comment

Choose a reason for hiding this comment

Uh oh!

ludfjig Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

ludfjig Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

ludfjig Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ludfjig Aug 14, 2026 •

edited

Loading