Skip to content

Allow snapshot-backed SandboxBuilder to accept a complete SandboxConfiguration #1862

Open

Description

@simongdavies

Problem

Hyperlight-JS stores construction settings in a SandboxConfiguration. Its fresh-sandbox path forwards that configuration to Hyperlight, but its snapshot restoration path discards it and creates a hyperlight_host::SandboxBuilder::from_snapshot() using Hyperlight defaults.

This loses any configured non-structural construction settings available for the current platform and feature set, including interrupt configuration, per-sandbox crashdump enablement, and GDB configuration. These settings cannot be changed after the restored MultiUseSandbox is built.

Hyperlight's snapshot builder exposes per-field methods for these values, so Hyperlight-JS could separately retain and replay every setting. However, that would duplicate Hyperlight's configuration state, require wrapper changes whenever settings are added, and cannot reconstruct fields whose SandboxConfiguration getters are not public.

The snapshot builder should therefore accept a complete SandboxConfiguration. Hyperlight's existing low-level restore semantics should remain unchanged: snapshot-owned heap, scratch, and transport geometry override caller values, while non-structural construction settings come from the restoring host.

Proposed API

let sandbox = SandboxBuilder::from_snapshot(snapshot)
    .sandbox_configuration(config)
    .build()?;

Snapshot-owned structural values are still applied. Other restorer-owned settings should come from the supplied configuration.

Maybe we should split the configuration into 2 different structs to make this cleaner

Activity

  1. ludfjig commented on Oct 22, 2026

    @ludfjig
    Contributor

    The other side of this: SandboxBuilder::from_snapshot accepts heap_size, scratch_size, and the transport size setters, and the snapshot silently overrides them. Only Sandbox::from_snapshot warns about the override.

    Whatever API this lands on should also stop accepting values that will be ignored. For example, a separate builder type for snapshot sources without the layout setters, or an error from build() when they are set.

    This replaces the "separate configs for creating sandboxes from scratch and from snapshot" item in #1479.

  2. ludfjig commented on Oct 22, 2026

    @ludfjig
    Contributor

    This conflicts with #1803, which plans to deprecate SandboxConfiguration in favour of SandboxBuilder. If SandboxConfiguration goes away, the snapshot builder cannot take one. The two issues need one answer for how restorer-owned settings reach a snapshot-backed sandbox, together with which builder setters apply to snapshot sources. Tracked as part of #1560.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions