Skip to content

README.md

Latest commit

 

History

History
106 lines (84 loc) · 4.96 KB

README.md

File metadata and controls

106 lines (84 loc) · 4.96 KB
Raw

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

Git and Rust are required; install Rust with rustup, which also installs Cargo. The commands below clone NVX, build nvx-rs, 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-rs 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-rs 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-rs. To build NVX from source instead, first initialize the openvmm submodule, which the clone below omits.

ℹ️ For direct OpenVMM integration without nvx-rs, 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
cargo build --release --locked --features cli \
  --manifest-path nvx-rs/Cargo.toml --target-dir nvx-rs/target
nvx-rs/target/release/nvx-rs run

Linux / MSHV

Requires 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-rs/Cargo.toml --target-dir nvx-rs/target
nvx-rs/target/release/nvx-rs run --hypervisor mshv

Windows / WHP

Requires Windows Hypervisor Platform enabled.

git clone https://github.com/microsoft/nvx.git; Set-Location nvx
cargo build --release --locked --features cli `
    --manifest-path nvx-rs/Cargo.toml --target-dir nvx-rs/target
nvx-rs\target\release\nvx-rs.exe 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 nvx-rs and scripts/nvx.py command and option reference.
  • 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