SDK

Headless features

The same features the terminal exposes in its UI — files, catalog, run and serve — available programmatically, with no terminal rendered. The counterpart to the embedded terminal.

createHeadless() boots a VM and returns a session that bundles the terminal's feature surface, minus the chrome — a thin facade over the in-process core (Nano) plus the serve bridge.

javascript

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

const s = await createHeadless({ wasmUrl: "/nano/nano.wasm" });

s.fs.writeFile("/work/server.js", code);   // files
await s.installApp("ripgrep");             // catalog
const { stdout } = await s.run("rg --version"); // run
const srv = await s.serve(                  // serve / preview
  { node: ["/work/server.js"] },
  { port: 3000 },
);
console.log(srv.url()); // routed through the service worker

The session

Member

Feature

filesystem CRUD (the Vfs)

installApp(ref) / catalog()

install signed catalog apps

run(cmd) / sh(line)

run binaries / full shell lines

serve(launch, { port })

host an in-VM HTTP server, get a preview URL

the underlying Nano (escape hatch)

createHeadless() runs the VM on the main thread. For a worker-hosted, recipe-driven runtime (e.g. provisioning Node off the UI thread), see Provisioning & recipes.

Display vs. headless: createTerminal / <nano-terminal> renders the features as a UI; createHeadless exposes the same features as an API. Both sit on the one nano.wasm runtime.

← Previous

Embedded terminal

Running commands