NanoVM documentation
NanoVM runs real programs inside a browser tab with no server: BusyBox and Node.js as RISC-V Linux binaries, Node.js on the browser's own JS engine, wasm32-wasip1 command-line tools, and sandboxed JavaScript. One kernel routes each program to the right runner, and every runner shares one virtual filesystem.
Most people use NanoVM through the TypeScript SDK, @userland-run/nano-sdk: it boots the VM, gives you a filesystem and a process API, and adds a shell engine, an HTTP preview bridge, a JavaScript sandbox, a Web Worker transport, a signed app catalog and an embeddable terminal. Every code block with a Run button on these pages executes for real in your tab. Nothing is downloaded until you press it.
Your first run
nano is a booted instance (createNano() with the BusyBox image). shExec() runs a full shell line on the emulated RISC-V CPU; node() runs a Node.js program on the browser's JS engine. Both see the same files.
nano.fs.writeFile("/work/hello.txt", "hello from the VFS\n");
const sh = await nano.shExec("cat /work/hello.txt; uname -m");
print(sh.stdout.trim());
const js = await nano.node(["-e", "console.log(require('fs').readFileSync('/work/hello.txt', 'utf8').trim(), '(node', process.version + ')')"]);
print(js.stdout.trim());hello from the VFS riscv64 hello from the VFS (node v25.4.0)
The four runners
NanoVM is a shared kernel (bus, virtual filesystem, process router, networking, capabilities, services) plus peer runners. A runner imports only from the kernel, never from another runner; cross-runner work goes through the router and the shared VFS. See Architecture for the details.
run, exec, shExec, node() with engines.node: "vm"node() with engines.node: "host" or "auto"registerWasmApp + execWasmAppscript() / scripting()The RISC-V runner is the fidelity reference: it runs unmodified upstream binaries instruction by instruction, so it is the slowest. The host-engine Node runner is fast but reimplements Node's built-in modules; its known differences are listed in Limitations. Pick per program with engines.
What you can build
- An embedded terminal or browser IDE: one
<nano-terminal>element. See Embedded terminal and the embeddable terminal feature. - Live code samples and playgrounds that run Node.js or shell commands client-side. See Running commands and the examples gallery.
- Dev-server previews: an HTTP server in the VM rendered in a real iframe. See Serve mode and dev servers.
- A plugin sandbox for untrusted JavaScript. See Scripting and the JS sandbox feature.
- Command-line tools on demand from a signed catalog: ripgrep, fd, jaq, numbat and more. See the app catalog and App catalog API.
Where to go next
- Quick start: install the SDK and run a command in five minutes.
- Requirements: cross-origin isolation, the service worker, browsers and memory.
- Configuration: every
createNano()option with a runnable sample. - Limitations: what does not work yet, observed with SDK 0.2.10.
- Building NanoVM itself: the build guide and the command-line runner.