mithic

Capability-based sandboxed process runtime for the agent era.

Mithic is an isomorphic, capability-based sandboxed JavaScript process runtime that runs identically in the browser and on native Node platforms. A microkernel brokers syscalls, IPC pipes, and process lifecycle; a POSIX-style shell and a Unix command suite run as ordinary sandboxed processes on top of it. The same code runs in the browser (local-first, no server required) and on Node.js — every resource a process can touch is an explicitly granted capability over a virtual filesystem and network layer.

Core Pillars

1. Agent Harness — Designed for AI agent tool execution. Pluggable VFS means agents see only the resources they are granted.
2. Security — Capability-based sandboxing. Each process runs in an isolation backend (iframe, Web Worker, QuickJS, or isolated-vm); only explicitly granted filesystem, network, and IPC capabilities are reachable, and every syscall is checked in-kernel.
3. Virtualization — Mount any storage provider at any path: in-memory, browser OPFS, Node FS, devices, network devices, or a caching layer — all behind the same provider interface.
4. Isomorphic — Same code runs in the browser (local-first, no server required), on Node.js servers, and native hosts.

Architecture

┌───────────────────────────────────────────────────────────────────┐
│                      Browser / Node.js Host                       │
│                                                                   │
│   ┌─────────────────────────── Kernel ────────────────────────┐   │
│   │  ProcessManager · IpcBroker · CapabilityManager           │   │
│   │  SyscallDispatcher · Remote-DOM host                      │   │
│   │      │              │                │                    │   │
│   │   capability-     pipe IPC      command namespace         │   │
│   │   gated VFS +     (credit-based  (resolveCommand →        │   │
│   │   net (@mithic/io)  flow control)  guest module URL)      │   │
│   └──────┼──────────────┼────────────────┼────────────────────┘   │
│          │              │                │                        │
│   ┌──────┴──────────────┴────────────────┴────────────────────┐   │
│   │   Runtime backend  (one isolation context per process)    │   │
│   │   iframe (GUI) · Worker · QuickJS-WASM · isolated-vm      │   │
│   │       └─ guest-runtime: mithic.* syscall API + stdio      │   │
│   │          streams + Remote-DOM client                      │   │
│   └───────────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────────────┘

The kernel owns process lifecycle, the command namespace, and the syscall surface (fs/* including fs/{get,set,list,remove}xattr, net/fetch, ipc/*, process/*, dom/mutate). Guests never hold a socket or a raw file handle — they issue syscalls that the kernel checks against the process's granted capabilities before touching the VFS or HttpClient. Following the Linux file-capabilities model, an executable's security.capability xattr is its grant: exec reads it and narrows against the parent. Each process runs in a pluggable runtime backend:

• Worker — true parallelism with direct MessagePort pipe transfer.
• iframe — the only GUI backend; renders a sanitized Remote-DOM tree in an opaque-origin sandboxed iframe.
• QuickJS-WASM — deterministic, with hard memory and CPU-budget limits; uses the kernel relay path for syscalls.
• isolated-vm — V8 isolate with a hard memory cap.

selectBackend() picks a backend from a policy (preferred / fallback order / capability requirements) against each backend's advertised RuntimeCapabilities.

Packages

Each package works independently — pick the abstraction level you need.

Package	Description
@mithic/protocol	Wire/IPC protocol: errno + signals, syscall request/response, process init, capability and pipe (credit-flow) types
@mithic/runtime	Pluggable isolation backends (iframe, Worker, QuickJS, isolated-vm), capability descriptors, and selectBackend()
@mithic/guest-runtime	In-sandbox guest API: createGuest() → syscall client, stdio streams, signal/DOM hooks, Remote-DOM client
@mithic/kernel	The microkernel: process lifecycle, IPC broker, capability manager, syscall dispatch, pipelines, Remote-DOM host
@mithic/io	I/O engine: VFS router + providers (memory, OPFS, Node FS, device, caching) with extended-attribute support (a per-mount metadata store backs xattr + mode/mtime on OPFS/Node FS), HTTP/socket abstractions
@mithic/shell	POSIX-style shell interpreter (lexer/parser/expander/executor with builtins) running as a regular Mithic process
@mithic/coreutils	71 pure-TypeScript Unix coreutils (including getcap/setcap over the fs/*xattr syscalls), one sandboxed guest module per command
@mithic/jq	Pure-TypeScript jq JSON processor as a sandboxed process
@mithic/curl	Pure-TypeScript curl-like HTTP client, routed through the capability-gated net/fetch syscall
@mithic/server	Host-side Hono REST server: sandboxed code execution over POST /exec
@mithic/worker	Web Worker polyfill for Node.js (isomorphic new Worker())
@mithic/desktop	Host-side window manager for a browser OS: frames, drag/resize, z-order, taskbar, app registry, geometry persistence — zero third-party deps

The command suite includes: 70+ coreutils plus jq and curl. The shell dispatches its builtins in-process and spawns everything else as child processes via process/spawn and process/pipeline. process/spawn resolves a bare name via $PATH against a VFS file first (checking the execute bit and dispatching by shebang), falling back to the command registry for bootstrap.

Examples

Example	Description
@mithic/example-shell	xterm.js browser terminal running @mithic/shell over a Kernel wired to the full coreutils + jq + curl suite
@mithic/example-image-viewer	A GUI Mithic process: drop-zone + <img> rendered in its own sandboxed iframe DOM
@mithic/example-desktop	A minimalist browser OS: @mithic/desktop window manager + terminal, text editor, file manager, and a sandboxed image viewer over one shared kernel + VFS
@mithic/example-lab	An in-browser automation Lab: installs web-API utilities (copy, csvcols, imgresize, imgconvert) into /usr/bin with manifest-sourced capability xattrs, composes them as shell-script workflows, and persists to OPFS

Getting Started

npm install          # install deps
npm run build        # vite build across all workspaces

Build before test. Many suites import from each package's dist/, so run npm run build before any test run.

Run the example shell (browser)

npm run dev --workspace=@mithic/example-shell

Opens an xterm.js terminal connected to a Kernel running @mithic/shell with the full coreutils + jq + curl command suite. Run pipelines, scripts, and built-in commands against a capability-gated virtual filesystem.

Run the example desktop (browser)

npm run dev --workspace=@mithic/example-desktop

A minimalist browser OS: a window manager hosting a terminal, a text editor, a file manager, and a sandboxed image viewer — all over one shared capability-gated kernel and VFS. Each GUI app is a real process; closing a sandboxed window SIGTERMs its guest, and files + window geometry persist to OPFS.

Development

Prerequisites

• Node.js >= 26.0

Commands

npm install          # install deps
npm run build        # vite build across all workspaces
npm run typecheck    # tsc --noEmit per package
npm test             # vitest run (node + browser projects)
npm run test:node    # node-environment tests only
npm run test:browser # browser-mode tests (Chromium via Playwright)
npm run lint         # eslint

Tests use Vitest with two projects: a node project for unit/integration tests, and a browser project running in real Chromium via Playwright for iframe sandboxing, DOM, and MessagePort/ArrayBuffer-transfer tests (*.browser.test.ts). The standard verification sequence from the repo root is:

npm run build && npm run typecheck && npm test

Toolchain: TypeScript 6+, ESM-only, Vite 8, Vitest 3.2.

A note on the WASM approach

Mithic 2.0 is JavaScript-first. The earlier WebAssembly / WASI-Preview-2 implementation — including the wasip2, process, and wasm-transpile packages and the WASM variants of the shell and command packages — is paused, not deleted. It is preserved on the wasm branch, and is recoverable there.

API Documentation

TypeDoc-generated API reference is available at docs/api/.

License

This repository and the code inside it is licensed under the MIT License. Read LICENSE for more information.