An embeddable Linux terminal for any web page

<nano-terminal> is a custom element that boots its own NanoVM and gives visitors a real Linux shell — BusyBox on an emulated RISC-V CPU, compiled to WebAssembly and running entirely in their tab. No server, no container, no iframe to a backend. Each sample below mounts a fresh terminal with different attributes and types a command into it.

What you get from one tag

The element ships in the SDK's @userland-run/nano-sdk/terminal subpath, separate from the headless core, so pages that only need the VM never download the UI. It renders into its own Shadow DOM: its stylesheet can't leak into your page and your CSS can't break it.

• A real shell. sh -i from BusyBox runs as a Linux process on the RISC-V VM — pipes, redirects, job control and the usual applets (ls, grep, sed, awk, sort, …).
• Files panel + editor. Browse the in-memory filesystem and edit files in a CodeMirror editor tab.
• App catalog sidebar. Install signed apps such as node, ripgrep or jq into the running VM — see the app catalog.
• Command palette. ⌘K to search commands and apps.
• Preview tab. An iframe onto an HTTP server running inside the VM, routed through a service worker — see dev servers.

Every feature is on by default and can be switched off with a no-* attribute, so the same element works as a full mini-IDE or as a bare shell in a blog post.

Quick start

Install the SDK, register the element once, and put the tag in your markup. The page must be cross-origin isolated because the VM uses a shared WebAssembly.Memory — either send the two headers below or register the SDK's service worker, which adds them for you (see requirements).

npm install @userland-run/nano-sdk

# serve with these response headers (or use the shipped service worker):
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

import { defineNanoTerminal } from "@userland-run/nano-sdk/terminal";

defineNanoTerminal(); // registers <nano-terminal> (idempotent)

<nano-terminal
  wasm-url="/nano/console.wasm"
  ram-mb="512"
  style="display:block; height:420px"
></nano-terminal>

<nano-terminal
  wasm-url="/nano/console.wasm"
  ram-mb="512"
></nano-terminal>

/ # uname -m
riscv64

Every attribute

Attributes are read once, when the element connects. To change them, remove the element and insert a new one (a DOM move keeps the running VM). The config property, if set before insertion, overrides the attributes.

<nano-terminal
  wasm-url="/nano/console.wasm"
  ram-mb="512"
  font-px="15"
  no-catalog
  no-palette
></nano-terminal>

/ # busybox | head -n 1
BusyBox v1.36.1 (2026-02-15 09:06:52 UTC) multi-call binary.

<nano-terminal
  wasm-url="/nano/console.wasm"
  ram-mb="256"
  no-catalog
  no-palette
  no-files
  no-editor
  no-preview
></nano-terminal>

answer: 42

<nano-terminal
  wasm-url="/nano/console.wasm"
  ram-mb="512"
  shell-command="env GREETING=hello sh -i"
></nano-terminal>

hello from the session

Programmatic control

el.ready resolves to a handle once the VM is up. createTerminal(target, config) does the same without the custom element. The handle lets your page drive the terminal:

import { createTerminal } from "@userland-run/nano-sdk/terminal";

const term = await createTerminal("#app", {
  wasmUrl: "/nano/console.wasm",
  ramMB: 512,
  features: { editor: false, preview: { ports: [8080, 3000], defaultPort: 3000 } },
});
await term.installApp("ripgrep", { quiet: true });
term.openFile("/root/notes.txt");

The features.preview object form is only available through config / createTerminal: it sets which ports the preview selector offers (default [8080]).

Lifecycle

• One element = one VM. Two terminals on a page are two independent machines with separate filesystems.
• Removing the element disposes the VM after the current task; moving it in the DOM does not.
• Nothing is fetched until the element connects, so terminals further down a page cost nothing until they are inserted. This page inserts each one only when you press Run.

Browser requirements

A cross-origin-isolated page (crossOriginIsolated === true) in a browser with SharedArrayBuffer and WebAssembly. The preview tab additionally needs a service worker. The full matrix, including hosts that can't set headers, is on Requirements; known gaps are on Limitations.

FAQ