# hyperlight-wasm: running Wasm modules inside a VM-backed sandbox

> hyperlight-wasm is a Rust crate that runs untrusted Wasm modules and Component Model components inside a lightweight virtual machine sandbox built on Hyperlight. It is experimental, pinned to Rust 1.94, and expects KVM, Windows Hypervisor Platform or /dev/mshv underneath.

**hyperlight-dev/hyperlight-wasm** — hyperlight-wasm is a rust library crate that enables Wasm Modules and components to be run inside lightweight Virtual Machine backed Sandbox. It is built on top of Hyperlight.

- Repository: https://github.com/hyperlight-dev/hyperlight-wasm
- Stars: 728 · Forks: 39
- Language: Rust
- License: Apache-2.0
- Published: 2026-08-24 · Updated: 2026-08-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/hyperlight-dev-hyperlight-wasm

## What hyperlight-wasm is for, and who should care

The README states the purpose plainly: hyperlight-wasm lets applications run untrusted or third-party Wasm code inside a VM with very low latency and overhead. That combination is the whole pitch. A plain Wasm runtime gives you language-level isolation inside your own process; a full VM gives you a hardware boundary but usually costs you a boot. Hyperlight sits between those two, and hyperlight-wasm is the layer that makes Wasm the thing running inside it.

The audience is narrow but real. You are building a host application in Rust that must execute code you did not write: a plugin system, a multi-tenant function runner, a policy engine that takes uploaded modules. You care about the syscall surface and about cold-start time. You are willing to run on bare metal or a VM with nested virtualization, because the README lists Windows Hypervisor Platform on Windows, KVM on Linux, or /dev/mshv as the supported backends. If your deployment target is a locked-down container with no /dev/kvm, this project is not aimed at you.

The README also carries a warning in its own words: this is experimental code, not considered production-grade by its developers, and not "supported" software. That sentence should drive the adoption decision more than any feature list.

## The mechanism: a Hyperlight micro-VM hosting a Wasm runtime

hyperlight-wasm is built on top of Hyperlight, which supplies the lightweight VM. The crate does not implement a hypervisor; it packages the guest-side Wasm execution and the host-side bindings so a module can be loaded into that VM. The workspace layout reflects this split. Cargo.toml lists members including src/hyperlight_wasm, src/hyperlight_wasm_aot, src/hyperlight_wasm_runtime and src/hyperlight_wasm_macro, with the runtime and macro crates versioned at 0.15.0 and depending on hyperlight-host, hyperlight-guest and hyperlight-guest-bin at 0.17.0.

Data flow, as far as the repository describes it: the host application links the hyperlight-wasm library, the VM is created through Hyperlight against the platform backend, and the Wasm module runs inside that VM. There is an AOT member in the workspace, which suggests ahead-of-time compilation is part of the intended path for the guest code rather than pure interpretation, though the README does not spell out the AOT workflow.

The component path changes the build, not just the runtime call. The README says Component Model support is experimental and that you set the WIT_WORLD environment variable to a binary encoding of a component type, for example the output of wasm-tools component wit -w -o /path/to/output.wasm /path/to/input.wit. That value is consumed at build time, so the resulting library includes a guest binary specialised to that component type. On the host side you generate matching bindings with hyperlight_component_macro::host_bindgen!(). Setting an environment variable to change what a library can load is an unusual contract, and it means one build artifact per component type rather than one runtime that accepts anything.

## Building it on Linux with KVM, then running the example

The README's prerequisites for Ubuntu are build-essential, Rust, just (at least 1.5.0, installed via cargo rather than a package manager), GitHub CLI, wasm-tools and cargo component. KVM must be available; the README suggests cpu-checker to confirm it.

```bash
sudo apt install build-essential
curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh
cargo install just
sudo apt install cpu-checker && kvm-ok
sudo adduser $USER kvm
```

The kvm-ok step should print that /dev/kvm exists and that KVM acceleration can be used. If it does not, stop here: the later build and test steps will not have a backend to run against.

The toolchain is pinned. The README says to use version 1.94 of the Rust toolchain, and the workspace Cargo.toml sets rust-version to 1.94 with edition 2024. Install and select it explicitly rather than relying on your default.

```bash
rustup install 1.94
rustup default 1.94
```

Build the library and the example Wasm modules the tests use, then run the test suite and the sample host application:

```bash
just build
just build-wasm-examples
just build-rust-wasm-examples
just test
cargo run --example helloworld
```

The helloworld example is the first real use: it is the host application the repository ships for trying the crate out. For usage instructions beyond that, the README points at RustDev.md rather than repeating them, so expect to read that file before writing your own host code.

If you want the Component Model path instead, the build changes shape. Generate a binary encoding of the component type, then build with WIT_WORLD pointing at it:

```bash
WIT_WORLD=/path/to/output.wasm WIT_WORLD_NAME=http-world cargo build -p hyperlight-wasm
```

WIT_WORLD_NAME selects a specific world when the WIT file declares more than one; the README notes that if it is unset, the last world in the file is used. When the macro fails, the README documents expanding it locally with HYPERLIGHT_COMPONENT_MACRO_DEBUG set to a file path to get more detailed error output.

## Where hyperlight-wasm is the wrong tool

The first limitation is the one the project states about itself. Experimental code that its own developers do not call production-grade is a poor fit for anything on a critical path. If you need a supported runtime with a security response process you can point auditors at, the README's warning is the answer, and the repository's SECURITY.md and SUPPORT.md files are what exist in place of a commercial support contract.

The second is the hypervisor dependency. KVM on Linux, Windows Hypervisor Platform on Windows, or /dev/mshv. Cloud instances that do not expose nested virtualization will not run this, and the README's own hint for Azure is to pick a VM size that supports nested virtualisation. That is a deployment constraint that no amount of Rust code removes.

The third is the build-time specialisation of components. Because WIT_WORLD is read when the library is compiled, a host that needs to accept arbitrary component types at runtime is working against the design. You build for the type you know about. If your product is a general module marketplace, this is friction you will feel on every new interface.

Finally, the toolchain pin cuts both ways. Rust 1.94 and edition 2024 with the workspace's rust-version field mean the crate tracks a recent compiler. If your organisation standardises on an older toolchain across many services, this dependency forces a split.

## How it differs from Wasmtime and plain Wasm sandboxing

Wasmtime is the obvious comparison, and the difference is where the isolation boundary sits. Wasmtime runs modules in your process and relies on the Wasm sandbox plus its own engine for safety. hyperlight-wasm puts a virtual machine between the host and the executing code, using Hyperlight as the micro-VM layer. That is a stronger boundary in kind, not just in degree: a Wasm escape lands you in a VM with a minimal device surface rather than in your address space.

The cost of that boundary is the environment. Wasmtime runs anywhere a Rust binary runs, including ordinary containers, because it does not need a hypervisor. hyperlight-wasm needs KVM, Windows Hypervisor Platform or /dev/mshv. You are trading portability for a hardware-backed boundary, and the README's low-latency claim is the reason that trade is interesting at all; without it, a conventional VM would be the simpler answer.

There is also a maturity gap that has nothing to do with architecture. Wasmtime is a general-purpose runtime with a long release history. hyperlight-wasm's own README calls the code experimental. Choosing between them is less about which sandbox is theoretically stronger and more about whether you can carry an experimental dependency and a hypervisor requirement into production.

## Maintenance, versioning and licence

The last push to the repository was on 2026-04-15, and the most recent release is dev-latest from the same date, described as the latest development build from the dev branch. The most recent numbered release is v0.14.0, dated 2026-04-09, preceded by v0.12.0 on 2025-12-12. The workspace Cargo.toml carries version 0.15.0, which is ahead of the newest tagged release, so the published crates and the tagged releases are not moving in lockstep. Plan for the possibility that the version you depend on from crates.io and the version in the repository differ.

The workspace depends on Hyperlight crates at 0.17.0 while hyperlight-wasm itself is at 0.15.0. Upgrading hyperlight-wasm therefore means tracking a separate version line for its underlying runtime, and the 0.x minor versions on both sides signal that breaking changes are expected rather than exceptional. The CHANGELOG.md at the repository root is where those changes should be recorded.

The licence is Apache-2.0, declared both in the workspace Cargo.toml and in LICENSE.txt. Apache-2.0 is permissive and includes an explicit patent grant, which matters if you are embedding this in a product. It also carries attribution and notice obligations, and the repository contains a FOSSA status badge for licence and security scanning in the README. Whether those obligations are acceptable in your distribution model is a question for your own legal review, not something the README answers.

## Conclusion

Adopt hyperlight-wasm if you already accept Hyperlight's model and need Wasm isolation with a VM boundary, and you can pin Rust 1.94 and run on KVM, Windows Hypervisor Platform or /dev/mshv. Do not adopt it if you need a production-grade, supported runtime, or if you plan to run it in a container without nested virtualization, since the README requires /dev/kvm. Before committing, verify that your target host exposes the hypervisor interface, that your toolchain matches the workspace's rust-version of 1.94, and whether you need core modules or Component Model components, because the component path requires WIT_WORLD to be set at build time.

## FAQ

### What hypervisor backends does hyperlight-wasm support?

The README lists Windows Hypervisor Platform on Windows, KVM on Linux, and /dev/mshv. On Linux you also need your user in the kvm group, and the README suggests confirming availability with cpu-checker and kvm-ok.

### Which Rust version does hyperlight-wasm require?

The README says to use version 1.94 of the Rust toolchain, and the workspace Cargo.toml sets rust-version to 1.94 with edition 2024. The README gives rustup install 1.94 and rustup default 1.94 as the commands.

### How do I run a Wasm Component Model component with hyperlight-wasm?

Set the WIT_WORLD environment variable to a binary encoding of a component type, for example the output of wasm-tools component wit, and generate host bindings with hyperlight_component_macro::host_bindgen!(). The README notes this support is experimental and that WIT_WORLD_NAME selects a world when the WIT file declares several.

### Is hyperlight-wasm production ready?

No. The README states that this is experimental code, not considered production-grade by its developers, and not "supported" software.

## Sources

- [Official README](https://github.com/hyperlight-dev/hyperlight-wasm#readme)
- [Project repository](https://github.com/hyperlight-dev/hyperlight-wasm)
- [Release notes](https://github.com/hyperlight-dev/hyperlight-wasm/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hyperlight-dev-hyperlight-wasm