SDK overview
@userland-run/nano-sdk embeds NanoVM in any web app: write files, run real binaries, stream output, host servers and sandbox plugins — from a typed, ESM, zero-dependency package.
The SDK is a thin, fully-typed layer over the nano.wasm runtime. It boots the emulator, gives you a filesystem and a process API, and layers a few higher-level modes on top — a shell engine, an HTTP serve bridge, a sandboxed scripting engine and a Web Worker transport.
Install
npm install @userland-run/nano-sdk
ESM-only, ships complete TypeScript types, and has zero runtime dependencies — the NanoVM and Boa runtimes are vendored into the bundle.
Cross-origin isolation
NanoVM allocates a shared WebAssembly.Memory, which requires the page to be cross-origin isolated. Either set the response headers yourself, or register the bundled service worker (exported at @userland-run/nano-sdk/service-worker as nano-sw.js), which injects them for you.
Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corp
Boot the VM
import { createNano, nanoImage } from "@userland-run/nano-sdk";
const nano = await createNano({
image: nanoImage({ baseUrl: "/nano/", withNode: true }),
});
nano.fs.writeFile("/app/data.txt", "1\n2\n3\n");
const { stdout } = await nano.shExec("sort -rn /app/data.txt | head -1");
console.log(stdout); // "3"nanoImage() builds the image config: point baseUrl at the directory holding nano.wasm and the binaries, and toggle which to load (withBusybox defaults to true, plus withNode and withDevenv). You can also pass raw bytes instead of URLs.
The five modes
- Code mode — write files, run commands, read results.
- Terminal mode — a stateful shell engine (cwd / env, sh semantics) for any renderer.
- Serve mode — bridge an in-VM HTTP server to a preview iframe via a service worker.
- Scripting mode — a sandboxed, capability-scoped Boa JavaScript engine.
- Worker transport — host the VM in a Web Worker so the UI thread stays responsive.