Documentation
How Lifo works
Lifo is a tiny Linux-like OS written in TypeScript — no WASM, no emulator, no native dependencies — and it runs in browsers, in Node, and in serverless functions. These docs cover the architecture, the Node compatibility layer, the shell and commands, the process model, networking and tunnelling, and the wire protocols that make live previews work.
Getting started
Guides
Run untrusted code
Execute agent- or user-generated code in a disposable box with no container, client-side or server-side.
Full-stack dev environment
Run real web and mobile dev servers in the browser with a terminal and a live preview, no backend.
A box for your agents
Give an AI agent a real computer — filesystem, shell, and npm — to run its own code and commands, safely.
Edge-first bash
A POSIX shell and coreutils anywhere JavaScript runs — including edge runtimes with no filesystem or child processes.
Sync the filesystem
Keep a box's filesystem in sync — full snapshots, an incremental change stream, and recipes for two tabs, a socket, and a database.
Snapshots
Save a box as a portable .tar.gz and restore it anywhere — the same file works in the browser, in Node and through the CLI.
Run a project from orchd.json
orchd boots a project from a manifest that travels with it — one npm package that runs the same orchd.json on your machine, in a container and in a Lifo box.
Concepts
Architecture
The layers behind a box — kernel, filesystem, shell, commands, the Node runtime, and the network — and why none of it is WASM.
The kernel
The Kernel owns a box's durable state — the filesystem, process table, virtual network, ports, and boot-time setup.
Filesystem
The virtual filesystem — an in-memory tree with pluggable providers, blob-backed large files, persistence, and tar.gz snapshots.
Shell & interpreter
The bash-like shell — lexer, parser, and interpreter — with pipes, redirection, job control, globbing, and TTY/raw-mode handling.
Commands
The userland — 60+ lazily-loaded coreutils plus node, npm, and git — and how to write your own.
Processes & jobs
The process model — a PID table with status tracking, job control, ps/top/kill, and a systemd-lite service manager.
Node compatibility
The Node runtime
How `node script.js` runs inside the VM — module loading, the ESM→CJS transform, the completion model, process.exit semantics, and interactive stdin.
node-compat modules
The built-in modules Lifo implements — fs, http, crypto, stream, child_process, process, and more — and the behaviors that matter.
npm & npx
How package installation works in the VM — real registry fetches, a hoisting installer, npm-style aliases, bins, and npx.
Networking
Networking
The virtual network stack — interfaces, sockets, DNS, ports — and how in-VM HTTP servers work.
Live previews
How a service worker turns an in-VM port into a live preview in the browser, with HMR and clean in-app routing.
Previews without a service worker
A blob-iframe preview transport for browsers where service workers are unreliable — and how the injected fetch/XHR/WebSocket shims route to the right in-VM port.
Calling in-VM servers from your code
sandbox.fetch() reaches a server running inside the box directly — no service worker, no port forwarding — for tests, benchmarks, CI and server-side use.
Publishing a port on the host
Bind a real host port to a server running inside the box, so curl, your browser and any local tool can reach it — no relay, no service worker.
Tunnelling & proxies
Reaching an in-VM port from outside the tab — the WebSocket tunnel and relay, and the CORS proxy for outbound requests.
Reference
Protocols
The wire protocols that connect the VM to the outside — the service-worker bridge, the tunnel frames, and I/O streaming.
Browser vs Node
What stays the same and what changes when a box runs in a browser tab versus server-side in Node.
Sandbox API reference
Every option and method on Sandbox — create, run commands, the fs helper, snapshots, and direct kernel/shell access.
Embeddable UI
Drop a Lifo terminal and a live preview browser into your own app with the framework-agnostic @lifo-sh/ui package.
Packages
The published npm packages that make up Lifo, and the in-VM package manager for installing tools inside a box.