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 ten
static guest binaries from nvx at
their common /sbin/nvx-* paths.
Git and Rust are required; install Rust with rustup, which also installs
Cargo. The commands below clone NVX, build nvx, the NVX command-line
interface, and run a microVM. The first run downloads the prebuilt NVX package of the host's
platform, from the release that CI built from the cloned revision when available, or from its
nearest released first-parent ancestor otherwise, so the guest and OpenVMM need no build. The
download uses the curl and tar of the host, which Windows 10 and later include. After you pull
newer commits, nvx download installs their release; run downloads only into a checkout that
holds no artifacts.
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 run. Exit cleanly from the guest with
/sbin/nvx-exit 0. See the setup and run guides for detailed
prerequisites and runtime options. To run without Rust, extract the package of a
development release and run its bin/nvx. To
build NVX from source instead, first initialize the openvmm
submodule, which the clone below omits.
ℹ️ To run microVMs from a program of your own through the
nvxlibrary, see the library guide; for direct OpenVMM integration withoutnvx, see Run OpenVMM directly.
Requires KVM configured with read/write access to /dev/kvm.
git clone https://github.com/microsoft/nvx.git && cd nvx
cargo build --release --locked --features cli \
--manifest-path nvx/Cargo.toml --target-dir nvx/target
nvx/target/release/nvx runRequires MSHV configured with read/write access to /dev/mshv.
git clone https://github.com/microsoft/nvx.git && cd nvx
cargo build --release --locked --features cli \
--manifest-path nvx/Cargo.toml --target-dir nvx/target
nvx/target/release/nvx run --hypervisor mshvRequires Windows Hypervisor Platform enabled.
git clone https://github.com/microsoft/nvx.git; Set-Location nvx
cargo build --release --locked --features cli `
--manifest-path nvx/Cargo.toml --target-dir nvx/target
nvx\target\release\nvx.exe run- 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
nvxandscripts/nvx.pycommand and option reference. - NVX Rust crate - The
nvxcrate: the library of mechanisms and value types with which programs run NVX microVMs, and NVX's own programs, private to it. - Library guide - A cold boot, a restore, and a reattach through the
nvxlibrary, and what its caller owns. - Guest-agent guidelines - What an init agent owns in an NVX guest: its space, its executions, and its part in a capture and a restore.
- 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.
- Module diagrams - Diagrams of the modules of the
nvxcrate and the dependencies between them. - Continuous integration - Instructions for running and maintaining NVX CI.
- Case matrix - The fate of each test of the runtime adapter, of CI and of the docs, and of each microVM scenario, before NVX deleted the adapter.
- 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.