Add SandboxBuilder

[jprendes]

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.

[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.

[jsturtevant]

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]

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]

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

[jprendes]

any suggestions?

[yoshuawuyts]

I love the work you're doing on making sandboxes easier to construct! I think that will go a long way in how people experience using Hyperlight. However in Rust, the builder suffix typically does refer to a chaining constructor. These typically take self by-value or by-(mutable)-reference. I would prefer it if we just kept the with_ variants of the APIs here, but without the with_ prefix (so e.g. with_mapped_file_cow -> mapped_file_cow).

As provided I think the mutable accessors on a type named *Builder will probably confuse first-time users of the crate.

[jprendes]

I was mostly following the std::process::Command, which is the builder I most frequently use. But I agree it's not called *Builder.
As for things *Builder in the rust std, there's:

• DirBuilder -> takes &mut self
• ContextBuilder -> takes self
• thread::Builder -> takes self
• ProcThreadAttributeListBuilder -> takes self

outside rust's std:

• tokio::runtime::Builder -> takes &mut self
• LogHistogramBuilder -> takes self
• rayon::ThreadPoolBuilder -> takes self
• rustls -> many builder consistently taking self

So yeah, I think the most common pattern is taking self.

How would you feel about having method xxx(self, ...) and in a trait SandboxBuilderMut (name TBD) that exposes the with_xxx(&mut self, ...) (with_ prefix TBD) methods?