Use SandboxBuilder across examples, tests and docs

[jprendes]

SandboxBuilder is the entry point for creating a sandbox, so examples, benchmarks, fuzz targets, integration tests and documentation all go through it.

Reshape the shared test helpers in tests/common around the builder: build_rust_sandbox, with_rust_sandbox_from, with_c_sandbox_from and with_all_guests replace the helpers that handed out an UninitializedSandbox.

Call sites that test internals below the public API keep using UninitializedSandbox and SandboxConfiguration directly. So does wit_test, because the generated Test::instantiate takes an UninitializedSandbox.

[Copilot]

Pull request overview

This pull request standardizes sandbox creation across the repository by routing examples, benchmarks, fuzz targets, integration tests, and documentation through SandboxBuilder, while reshaping shared test helpers to construct sandboxes via the builder rather than exposing UninitializedSandbox.

Changes:

• Migrate sandbox creation in tests, examples, fuzz targets, benches, and docs to SandboxBuilder::{build_from_file, build_from_snapshot}.
• Replace shared test helpers that returned UninitializedSandbox with builder-oriented helpers (build_rust_sandbox, with_*_sandbox_from, with_all_guests).
• Update rustdoc/examples and snapshot golden generation/loading to use builder-based APIs.

Reviewed changes

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

Show a summary per file

File	Description
src/hyperlight_host/tests/snapshot_goldens/fixtures.rs	Generate golden snapshots via SandboxBuilder + HostFunctions.
src/hyperlight_host/tests/snapshot_goldens/checks.rs	Load goldens via SandboxBuilder::build_from_snapshot instead of MultiUseSandbox::from_snapshot.
src/hyperlight_host/tests/sandbox_host_tests.rs	Rework tests to build sandboxes directly with SandboxBuilder and new helpers.
src/hyperlight_host/tests/integration_test.rs	Switch integration tests to builder-based sandbox construction, adding *_sandbox_from helper usage.
src/hyperlight_host/tests/common/mod.rs	Replace uninit-sandbox helpers with builder-first helpers (build_*_sandbox, with_*_from, with_all_guests).
src/hyperlight_host/src/sandbox/uninitialized.rs	Remove unnecessary explicit MultiUseSandbox type annotations in tests.
src/hyperlight_host/src/sandbox/snapshot/file/mod.rs	Update rustdoc example to create sandboxes via SandboxBuilder.
src/hyperlight_host/src/sandbox/snapshot/file_tests.rs	Update snapshot file tests to build sandboxes via SandboxBuilder (including MSR + init-data cases).
src/hyperlight_host/src/sandbox/initialized_multi_use.rs	Update docs/tests to use SandboxBuilder for “normal path” sandbox creation and snapshot restore.
src/hyperlight_host/src/sandbox/host_funcs.rs	Align HostFunctions docs with builder-based lifecycle.
src/hyperlight_host/src/metrics/mod.rs	Update metrics tests to use SandboxBuilder for sandbox creation.
src/hyperlight_host/src/lib.rs	Update crate-level docs to present SandboxBuilder as the primary entry point.
src/hyperlight_host/src/func/host_functions.rs	Update guidance on host-function registration to point at SandboxBuilder::host_function.
src/hyperlight_host/examples/tracing/main.rs	Use SandboxBuilder in tracing example setup.
src/hyperlight_host/examples/tracing-otlp/main.rs	Use SandboxBuilder in OTLP tracing example setup.
src/hyperlight_host/examples/tracing-chrome/main.rs	Use SandboxBuilder in Chrome tracing example setup.
src/hyperlight_host/examples/metrics/main.rs	Use SandboxBuilder in metrics example setup.
src/hyperlight_host/examples/map-file-cow-test/main.rs	Demonstrate mapped-file COW via builder configuration (mapped_file_cow).
src/hyperlight_host/examples/logging/main.rs	Use SandboxBuilder in logging example setup.
src/hyperlight_host/examples/hello-world/main.rs	Use SandboxBuilder for a minimal “hello world” sandbox.
src/hyperlight_host/examples/guest-debugging/main.rs	Use SandboxBuilder for optional GDB-enabled sandbox creation.
src/hyperlight_host/examples/func_ctx/main.rs	Use SandboxBuilder to construct a sandbox for function-context example.
src/hyperlight_host/examples/crashdump/main.rs	Update crashdump example/docs/tests to use SandboxBuilder and builder flags.
src/hyperlight_host/benches/benchmarks.rs	Convert benchmarks to builder-based sandbox creation and sizing configuration.
README.md	Update getting-started snippet to build sandboxes via SandboxBuilder.
fuzz/fuzz_targets/host_print.rs	Initialize the persistent fuzz sandbox via SandboxBuilder.
fuzz/fuzz_targets/host_call.rs	Initialize the persistent fuzz sandbox via SandboxBuilder with tuned buffer sizes.
fuzz/fuzz_targets/guest_trace.rs	Initialize the persistent fuzz sandbox via SandboxBuilder with tuned scratch size.
fuzz/fuzz_targets/guest_call.rs	Initialize the persistent fuzz sandbox via SandboxBuilder.
docs/msr.md	Update MSR documentation references from SandboxConfiguration to SandboxBuilder.
docs/how-to-debug-a-hyperlight-guest.md	Update debugging docs/snippets to use SandboxBuilder configuration calls.

---

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

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/hyperlight_host/src/sandbox/snapshot/file/mod.rs:343

• The Snapshot::load example later in this file still imports HostFunctions and MultiUseSandbox and calls MultiUseSandbox::from_snapshot (lines 687-694). Update that example to use SandboxBuilder::new().build_from_snapshot(snapshot) so the public snapshot documentation consistently uses the stated entry point.

    /// # use hyperlight_host::SandboxBuilder;
    /// # use hyperlight_host::sandbox::snapshot::OciTag;
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut sandbox = SandboxBuilder::new().build_from_file("guest.bin")?;

src/hyperlight_host/benches/benchmarks.rs:28

• The benchmark suite still constructs sandboxes with MultiUseSandbox::from_snapshot at lines 331, 626, and 651. This leaves the benchmark migration incomplete despite the stated goal that benchmarks go through SandboxBuilder. Convert those paths to SandboxBuilder::new().build_from_snapshot(...) and remove their local HostFunctions imports.

use hyperlight_host::sandbox::MultiUseSandbox;

[ludfjig]

LGTM with 1 question about keeping benchmark

[ludfjig]

should we really remove these?

[jprendes]

Good question, the main reasoning was that this is not possible anymore, but I guess it still gives valuable benchmarking information. How different is creating an UninitializedSandbox from creating a MultiUseSandbox from a Snapshot?