NVX: An Ultra-Light Micro-VM Sandbox

NVX is an ultra-light micro-VM sandbox for running untrusted workloads with hardware-enforced isolation. It is built on top of OpenVMM and runs Linux as a guest.

NVX was jointly developed by the MSR Systems Research Group and Azure Research - Systems, building on research results from the Nanvix system.

This repository includes version pins for Linux, OpenVMM, and the Rust guest toolchain, along with the patches, guest source files, build tools, and benchmarks needed to use NVX. Alpine, Ubuntu, and Azure Linux ship the nine static guest binaries from nvx-rs at their common /sbin/nvx-* paths.

Quick Start

Python 3.10 or newer and Git are required. The commands below download the prebuilt NVX package for the selected platform from the cloned revision's release when available, or from its nearest released first-parent ancestor otherwise, so the guest and OpenVMM need no build.

nvx.py run also runs nvx-rs, which download installs only from a release built from the checkout's nvx-rs sources. Otherwise, nvx.py builds nvx-rs with Cargo the first time that a command needs it, so install Rust with rustup. A clone of the latest dev often needs this build, because nvx-rs may have changed since its nearest release. To run without Rust, check out the tag of a development release before download.

A successful boot prints NVX-GUEST-BOOT-OK: alpine and opens a root shell. The package also includes the Ubuntu and Azure Linux userlands: boot either with the same NVX kernel by adding --guest ubuntu or --guest azurelinux to nvx.py run. Exit cleanly from the guest with /sbin/nvx-exit 0. See the setup and run guides for detailed prerequisites and runtime options. To build NVX from source instead, first initialize the openvmm submodule, which the clone below omits.

ℹ️ For direct OpenVMM integration without the scripts/nvx.py runtime harness, see Run OpenVMM directly.

Linux / KVM

Requires KVM configured with read/write access to /dev/kvm.

git clone https://github.com/microsoft/nvx.git && cd nvx
python3 scripts/nvx.py download
python3 scripts/nvx.py run

Linux / MSHV

Requires MSHV configured with read/write access to /dev/mshv.

git clone https://github.com/microsoft/nvx.git && cd nvx
python3 scripts/nvx.py download --hypervisor mshv
python3 scripts/nvx.py run --hypervisor mshv

Windows / WHP

Requires Windows Hypervisor Platform enabled.

git clone https://github.com/microsoft/nvx.git; Set-Location nvx
python scripts\nvx.py download
python scripts\nvx.py run

Documentation

Usage

• Setup - Instructions for setting up your environment.
• Build - Instructions for building NVX.
• Run - Instructions for running NVX.
• Benchmark - Instructions for benchmarking NVX.
• Command-line reference - Complete scripts/nvx.py command and option reference.
• Rust API - The aci_edge_sandboxes crate for driving the sandbox lifecycle from Rust.
• NVX Rust crate - The nvx crate that holds the NVX mechanics: the OpenVMM control protocol and the launch, policy lowering, and supervision of NVX microVMs.

Development

• Design - Architecture of the NVX microVM and its single-workload guest runtime.
• Ubuntu guest support - How NVX runs Ubuntu userland on its own kernel.
• Azure Linux guest support - How NVX runs Azure Linux userland on its own kernel.
• Project structure - Overview of the NVX repository layout.
• Continuous integration - Instructions for running and maintaining NVX CI.
• Copilot-driven adversarial testing - Bounded adaptive stress and containment campaigns.
• Package and source delivery - Instructions for packaging and distributing NVX.
• Contributing - Guidelines for contributing to NVX.
• OpenVMM upstream roadmap - Plan for upstreaming the OpenVMM fork's microVM commits.