Documentation
How Lifo works
Lifo is a tiny Linux-like VM written in pure TypeScript — no WASM, no emulator, no native binaries. 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.
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.
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.