Introduction

NanoVM

A multi-tier platform for running programs in the browser — no server required. A shared kernel routes each program to the right runner: an RV64GC RISC-V Linux VM, Node.js on the host engine, wasm32-wasip1 commands, or sandboxed JS.

NanoVM is a shared kernel (a bus, a virtual filesystem, a process router, networking, capabilities and services) plus a set of peer runners that each execute one kind of program on a different engine. The historic RISC-V VM is one of those runners — the slow, high-fidelity oracle the faster tiers are validated against.

The runners

  • riscv — RV64 ELF (busybox, node) on an emulated CPU (Rust → wasm). The fidelity oracle; slow but exact.
  • node — Node.js on the host JS engine. Trusted and fast.
  • wasm — wasm32-wasip1 commands on the host wasm engine. Capability-scoped and fast.
  • boa — untrusted JS on the Boa interpreter (Rust → wasm). Sandboxed.

Runners are peers: each imports only from the kernel and never from another runner — cross-tier work goes through the router, the bus and the shared VFS.

What the RISC-V runner runs

  • BusyBox — echo, cat, ls, sort, grep, head, tail and the rest of the coreutils.
  • Node.js v25 — a full runtime with require, fs, path, crypto, http, streams, Buffer, EventEmitter and async/await.
  • The npm toolchain — the TypeScript compiler, ESLint and Prettier, all unmodified.

It emulates an RV64GC RISC-V CPU with roughly eighty Linux syscalls — enough of the kernel surface to load real ELF binaries and execute them unmodified, instruction by instruction — handling memory management (brk / mmap), file I/O via an in-memory POSIX filesystem, sockets, epoll, timerfds, futex-based threading and ELF loading, all behind a minimal host boundary.

The RISC-V runner is a userland VM: it runs Linux programs, not a full kernel with device drivers. If you need a complete bootable OS, you want a full-system emulator instead.

Where to go next

  • New here? Start with the Quick start.
  • Embedding it in a web app? The SDK (@userland-run/nano-sdk) is the supported way in — start with the SDK overview.
  • Just want Node in the browser? See running Node.js + dev tools in the browser.
  • Building on the RISC-V VM directly? See the CLI & JS API and Host API.
  • Curious how it works? Read the Architecture page for the platform shape, then the RISC-V runner, Syscalls and Performance pages.
Next →
Quick start