Skip to content

Home

Jump to bottom
Keys edited this page Jul 31, 2026 · 1 revision

shell.js

shell.js is a bounded, headless shell engine for browser terminals. It provides parsing, an in-memory filesystem, portable commands, optional OS profiles, manual-page packs, and an optional WebAssembly accelerator. It does not emulate a kernel or expose the host operating system.

The repository README is the canonical quick start and API example. This wiki records the design and maintenance rules that are easy to lose in examples.

Start here

  • Architecture — execution flow, component boundaries, and WebAssembly
  • Manuals — reproducible FreeBSD and Linux manual packs
  • Security — trust model, deployment checklist, and private reporting
  • Releasing — validation, release-plz, artifacts, and major-line names

Project contract

  • Shell text is parsed, never evaluated as JavaScript.
  • Files and redirects stay inside a bounded MemoryFS.
  • FreeBSD and Linux profiles describe identity, commands, and manuals; they are not browser kernels.
  • Custom command handlers are trusted application code, not a sandbox boundary.
  • The DOM adapter is optional. Applications may call createShell() directly.
  • Manuals and Wasm are optional edges and are loaded only when configured.

Public entry points are createShell, MemoryFS, profiles, createManuals, and mountShell. The classic browser build exposes the same API as globalThis.ShellJS.

Clone this wiki locally