Hyperlight-Wasm - Run Wasm Modules in a Virtual Machine backed sandbox

Hyperlight-Wasm is a component that enables Wasm Modules to be run inside lightweight Virtual Machine backed Sandbox. Its purpose is to enable applications to safely run untrusted or third party Wasm code within a VM with very low latency/overhead. It is built on top of Hyperlight.

Hyperlight-Wasm currently supports running applications using either the Windows Hypervisor Platform on Windows, KVM on Linux or /dev/mshv.

WARNING: This is experimental code. It is not considered production-grade by its developers, neither is it "supported" software.

This repo contains hyperlight-wasm along with a couple of sample Wasm modules and an example host application that can be used to either test or try it out.

This document contains instructions on building Hyperlight-Wasm. For usage instructions, please see RustDev.md.

Prerequisites

Windows

Make sure the following are installed:

1. Rust
2. just. is used as a command runner cargo install just. Do not install just with Chocolately because it installs an older incompatible version, make sure to use at least version 1.5.0 if not installed through cargo.
3. pwsh
4. git
5. GitHub CLI

Ensure that Windows Hypervisor Platform is enabled:

Enable-WindowsOptionalFeature -Online -FeatureName HyperVisorPlatform

Linux

Ubuntu/KVM

Make sure the following are installed:

1. build-essential: sudo apt install build-essential
2. Rust curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh
3. just. is used as a command runner cargo install just. Do not install just through a package manager as it may install an older incompatible version, make sure to use at least version 1.5.0 if not installed through cargo.
4. GitHub CLI

Ensure that KVM is enabled: On an Azure VM using a size that supports nested virtualisation:

sudo apt install cpu-checker && kvm-ok

If KVM is installed and available you should see the output

INFO: /dev/kvm exists
KVM acceleration can be used

You should also add your user to the kvm group: sudo adduser $USER kvm

Building

NOTE: Ensure that you use version 1.82.0 of rust toolchain.

rustup install 1.82.0
rustup default 1.82.0

Now you can build the Rust Wasm library:

just build

And the example wasm modules used by the tests:

just build-wasm-examples
just build-rust-wasm-examples

Then you can test the Rust Wasm library and run the example:

just test
cargo run --example helloworld

Component Model support

Hyperlight-Wasm has experimental support for running WebAssembly Component Model components, rather than core wasm modules. In this mode, set the HYPERLIGHT_WASM_WORLD environment variable to point to a binary encoding of a component type (e.g. the result of running wasm-tools component wit -w -o /path/to/output.wasm /path/to/input.wit), which will ensure that the resultant library includes a guest binary that is specialised to load components with that type. Then, use hyperlight_component_macro::host_bindgen!() to generate bindings from the same component type in the host. For a complete (albeit small) example of this, see this example.

Note

Currently, component model support in Hyperlight-Wasm requires using the hyperlight-component-macro branch of core hyperlight. The Hyperlight-Wasm Cargo.toml already depends on this version, rather than the published one, but you should be careful to use the same dependency specification to avoid Cargo pulling two instances of core hyperlight into your dependency graph.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct.

For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.