Repository navigation
Add experimental C API and .NET packages for components - #564
Merged
Merged
Conversation
ludfjig
force-pushed
the
hyperlight-0.18-capi
branch
4 times, most recently
from
November 4, 2026 01:22
fbcf9c8 to
b91d23d
Compare
ludfjig
force-pushed
the
hyperlight-0.18-capi
branch
from
November 11, 2026 19:25
b91d23d to
214c584
Compare
ludfjig
force-pushed
the
hyperlight-0.18-capi
branch
10 times, most recently
from
November 12, 2026 18:39
152740d to
0231892
Compare
ludfjig
marked this pull request as ready for review
November 12, 2026 20:31
This was referenced Nov 13, 2026
jsturtevant
reviewed
Nov 13, 2026
jsturtevant
reviewed
Nov 13, 2026
jsturtevant
reviewed
Nov 13, 2026
jsturtevant
reviewed
Nov 13, 2026
jsturtevant
reviewed
Nov 13, 2026
jsturtevant
reviewed
Nov 13, 2026
jsturtevant
reviewed
Nov 13, 2026
jsturtevant
reviewed
Nov 13, 2026
jsturtevant
reviewed
Nov 13, 2026
jsturtevant
reviewed
Nov 13, 2026
jsturtevant
reviewed
Nov 13, 2026
ludfjig
force-pushed
the
hyperlight-0.18-capi
branch
2 times, most recently
from
November 16, 2026 18:46
1baa590 to
95f1991
Compare
jsturtevant
reviewed
Nov 16, 2026
jsturtevant
reviewed
Nov 16, 2026
jsturtevant
reviewed
Nov 16, 2026
jsturtevant
reviewed
Nov 16, 2026
jsturtevant
reviewed
Nov 16, 2026
ludfjig
force-pushed
the
hyperlight-0.18-capi
branch
from
November 17, 2026 00:03
95f1991 to
9fc835f
Compare
jsturtevant
reviewed
Nov 17, 2026
simongdavies
left a comment
Member
There was a problem hiding this comment.
a few comments/questions.
I am not a fan of the with_runtime_file, it would be better if the runtime was either created at build time or the world was seperate
ludfjig
force-pushed
the
hyperlight-0.18-capi
branch
2 times, most recently
from
November 17, 2026 19:33
1d8d096 to
9db79f3
Compare
Contributor
Author
Agree, unfortunately only rust can create it at build time, not c#(c). |
ludfjig
force-pushed
the
hyperlight-0.18-capi
branch
2 times, most recently
from
November 17, 2026 21:39
1586dd4 to
0baba7a
Compare
The experimental_runtime_file feature adds SandboxBuilder::with_runtime_file, which loads the guest runtime from a file instead of the one built into the crate. A host built once can then run components of any world whose runtime was built separately. The runtime records its hyperlight-wasm version and a hash of its WIT world in an ELF section. with_runtime_file rejects a runtime from another version, and snapshots of the sandbox record the runtime's world, so they can be saved and loaded. A host built without WIT_WORLD has no bindings of its own, so it loads snapshots of any world. SandboxBuilder::with_interrupt_vcpu_sigrtmin_offset changes the signal that interrupts a running guest on Linux. Hosts such as .NET use SIGRTMIN themselves. Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
Add hyperlight-wasm-capi, a C library declared in include/hyperlight_wasm.h. Callers register host functions, load a component and call its functions. They can also snapshot, restore and interrupt a sandbox. It is experimental and not published. The C API works with any component, because it never decodes values. Callers pass each argument as a byte buffer in hyperlight's component wire format and get the result back the same way. Generated bindings, such as the .NET ones, do the encoding. Host functions take up to 32 parameters. Calls from a host function into its own sandbox fail. just examples-components runs its tests against the component_sample example world. Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
ludfjig
force-pushed
the
hyperlight-0.18-capi
branch
from
November 17, 2026 22:16
0baba7a to
c234b2f
Compare
simongdavies
requested changes
Nov 18, 2026
Hyperlight.Wasm runs components from .NET through the C API. WasmSandbox registers host functions, loads components and calls them, with snapshots, interrupts and CancellationToken support. Host exceptions become the InnerException of the failed call. Their messages do not reach the guest. The interrupt signal defaults to SIGRTMIN + 1, because the .NET runtime suspends threads for garbage collection with SIGRTMIN. With offset 0 a collection can hang. Hyperlight.Wasm.Build generates C# bindings from HyperlightWit items at build time. Its MSBuild task loads hyperlight-wasm-csharp-bindgen, a native library around hyperlight's C# generator, so builds need no Rust. Both packages are experimental and take the workspace version with a preview suffix. They are not published yet. just dotnet-test runs the tests against the component_sample example world. CI runs them with the prebuilt component on every platform. The tests build as an xUnit.net v3 executable, so macOS signs it with the hypervisor entitlement and runs it directly. dotnet test would run them inside the unsigned dotnet host. just dotnet-pack packs both packages for the build machine's runtime identifier. Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
ludfjig
force-pushed
the
hyperlight-0.18-capi
branch
from
November 18, 2026 21:45
c234b2f to
f43b1b0
Compare
simongdavies
approved these changes
Nov 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
.NET and other non-Rust hosts can't use hyperlight-wasm, because its host API is Rust only.
This adds an experimental C API and .NET packages on top of it:
hyperlight-wasm-capiis a C API for running components. Callers register host functions, load a component and call its functions. They can also snapshot, restore and interrupt a sandbox.Hyperlight.Wasmwraps the C API.Hyperlight.Wasm.Buildgenerates typed C# bindings from WIT at build time. Its MSBuild task loadshyperlight-wasm-csharp-bindgen, a native library around Hyperlight'shyperlight-component-csharp, so builds need no Rust.A guest runtime is built for one WIT world and is embedded when a Rust host builds. A non-Rust host has no Rust build to embed it in. So the C API loads the runtime from a file, through
SandboxBuilder::with_runtime_filebehind theexperimental_runtime_filefeature. Here users build that runtime withcargo hyperlight. #574 adds a tool and MSBuild support for it.hyperlight-wasm-runtimeguest binary has an ELF section,.note_hyperlight_wasm_runtime, holding its crate version and a hash of its WIT world. The hash covers theWIT_WORLDfile or directory andWIT_WORLD_NAME.with_runtime_filerejects a guest binary whose crate version differs from the host'shyperlight-wasmcrate version, because host and guest must agree on the guest ABI. Thehyperlight-wasmbuild checks its embedded guest binary the same way.WIT_WORLDonly loads snapshots with the same hash. A host built without one, like the C API, loads snapshots of any world, because it only uses guest binaries from files.SandboxBuilder::with_interrupt_vcpu_sigrtmin_offsetchanges the interrupt signal, since .NET usesSIGRTMIN.The C API and packages are versioned as experimental and not published yet.
just dotnet-testandjust examples-componentsrun their tests, and CI runs both on every platform. On macOS the .NET tests run as a signed executable, because thedotnethost lacks the hypervisor entitlement.