Docs· Understand it

One box, in the tab and in the cloud

View as Markdown

A Lifo box is a small computer for you or your agent: files, a shell, processes, ports and a URL. The same box runs in a browser tab, in a Node.js process, and in Lifo Cloud, and moves between them as a snapshot. The tab is free and private; the cloud keeps the box running when the tab closes and plugs in the things a tab can't do, like a real Postgres or a real browser.

This page is the map: where a box runs, what changes when it moves to the cloud, and how Lifo Cloud is put together. The pages it links to have the commands and limits.

Three places, one box

Browser tab@lifo-sh/corefiles in memory or IndexedDBfree and privateends with the tabNode.js · your terminal@lifo-sh/corefiles in memory or your foldersnpx lifo-sh, tests, CIruns wherever Node runsLifo Cloud@lifo-sh/corefiles saved as they're writtenalways reachable at its URLsleeps when idle, wakes on usebox.exportSnapshot · importSnapshotlifo cloud push · pullsnapshot: a tar.gz of the box's files, environment and working directory
One box, three hosts. Every host runs the same @lifo-sh/core; the box moves between them as a snapshot (files, environment, working directory), so nothing is rebuilt.

It's the same @lifo-sh/core everywhere, so a command that works in the tab works in the cloud. Nothing is rebuilt or containerized when a box moves: lifo cloud push uploads the box's files and starts the same command there.

What swaps when a box moves to the cloud

Most of a box is JavaScript and WebAssembly, and runs the same in every host. A few things are too heavy for a tab, or need native code, a GPU or a real kernel. For those, the box has a stand-in that works anywhere, and Lifo Cloud plugs in the real thing as a service. Your code calls the same command or reads the same variable either way.

Your code calls the same command either way. In a tab the stand-in runs inside the box; in Lifo Cloud the call leaves the box over a private path to a service attached on first use (ffmpeg asks before it uploads your files), and the stand-in is still there if the box moves back.
CapabilityIn the tab or a Node boxIn a cloud boxDocs
Databasesupabase start runs tinbase on pg-mem (fast, in memory); PGlite for real Postgres on requestthe box's own Postgres 17 in DATABASE_URL; supabase start serves the Supabase API on itDatabases
Web browsingbrowser: a text browser through lifo.sh; Firefox in WebAssembly in the split panea headless Chromium per account, an isolated context per box; BROWSER_WS_ENDPOINT for Playwright or puppeteerAgents
Mediaffmpeg.wasm for small filesnative ffmpeg in a locked-down containerServices
AI modelsWebLLM on the visitor's GPUGPU models (planned)Agents
Filesmemory, IndexedDB or your mounted folderswritten to the box's own database as they changeFiles
Network outHTTP through the page (and a CORS proxy)HTTP and real TCP to the public internetCloud boxes
Network ina preview in your page; lifo tunnel for a public URLthe box's URL, HTTP and WebSocketsTunnels

Services attach on first use. A cloud box doesn't declare its services. The first supabase start or database connection starts the box's Postgres; the first ffmpeg on a big file sends it to the service (asking you first, because your files leave the box); the first browser call starts the account's Chromium. A service follows its box: it sleeps when the box sleeps, it is metered with the box, and it is deleted with the box.

Where the line is

What runs inside a box and what becomes a service follows three rules:

  • Inside the box when it is JavaScript or WebAssembly that fits a box, must also work in a tab, and keeps its state in files. Node.js, npm, Vite, Python, git and small media jobs live here.
  • A service when it needs native code, threads, a GPU or a real kernel; when its WebAssembly version costs many times the native one (PGlite takes over 600 MB where native Postgres takes under 100 MB); or when its state should outlive the box or be shared between boxes.
  • Every service has a stand-in in the box, so a box keeps working in a tab and offline. A tool without one doesn't become a Lifo service.

The list of services is short on purpose: Postgres, a browser, media tools and AI models, and later object storage. For anything else (Redis, MySQL, a hosted Postgres, a queue), a cloud box has real outbound TCP, so you bring your own.

How Lifo Cloud is put together

Lifo Cloud's servers are closed source; the client side (LifoCloud, lifo cloud, the CLI) is in this repo. This is how it behaves:

your tab, terminal or agentlifo cloud push · exec · shellvisitorshttps://my-api-tunnel.lifo.shlifo.shaccounts, keys, usageingressTLS, routing by box namelifo_ key or tab tokenHTTP, WebSocketsA REGIONYOUR ACCOUNTbox "notes"its own V8 isolate · @lifo-sh/corefiles in its own SQLiteone instance, sleeps when idlebox "my-api"its own V8 isolate · @lifo-sh/corefiles in its own SQLiteone instance, sleeps when idlepush · exec · shellits URLPostgres 17one database per box · on demandChromiumone context per box · on demandprivate pathprivate pathone process for your boxes · memory and CPU limits · internet out onlyother accountsseparate processes,databases andbrowsersreal containersboxes that neednative code;ffmpeg jobs
How Lifo Cloud is put together. Commands reach a box through lifo.sh with your key; visitors reach it through the ingress by name. Each account is its own process; each box is a single isolate with its files in its own SQLite; services start on demand on a private path. A box that needs native code runs in a real container instead, with the same API.
  • A box is a single durable instance. Each box name maps to exactly one running instance, in its own V8 isolate (the boundary Cloudflare Workers use between customers), with its own storage. Think of a Durable Object rather than a stateless function: it has an identity, keeps state, holds long connections (shells, WebSockets), and sleeps when nobody uses it.
  • Files are durable as they're written. A cloud box writes every file change to its own SQLite database as it happens. A crash loses at most the write in progress; sleeping saves nothing and waking loads nothing.
  • Accounts are separate processes. Your boxes share a process with memory and CPU limits from your plan; another account's busy or crashing box can't touch yours.
  • A real container when a box needs one. A box with native npm modules, a Dockerfile or binaries Lifo doesn't have runs in a Linux container instead (picked automatically, or with --runtime container), with the same URL, commands, database and sleep and wake. A Lifo box stays the default: it's far lighter and wakes faster (Runtimes).
  • Compute and storage are split. The box's database lives next to it, not inside it, so it survives the box sleeping, restarting or being pushed again, and it's backed up on its own.
  • Network. Boxes reach the public internet only (HTTP and TCP). Private and loopback addresses are refused; the only private path a box has is to its own account's services.

A box's day

pushfiles + start cmdbooting~110 msservingURL · exec · shellasleepno CPU or memorystart cmd runsno requests, commands orshell input for sleepAfter(default 5 minutes)request, exec or shellwakes it (~110–150 ms)kept: files (saved as written), the databasenot kept: memory, running processes
A box's day. Asleep, a box uses no CPU or memory; its files and database are kept. Memory and running processes start again on every wake, when the start command runs.

Memory and running processes don't survive a sleep; files and the database do. Services that the box used (its database, its browser) start again when the box next needs them.

Where the servers are

Lifo Cloud is regional, not edge. A box lives in one region, next to its database, and requests from anywhere are routed to it; the edge only terminates connections and forwards them. Boxes are single instances by design, the way most uses need them: one box per agent, per project preview or per app. During the preview there is one region. Because a sleeping box is just its files and its database, a box can move to another region between wakes.

What's open

Open source (this repo)Closed source (Lifo Cloud)
@lifo-sh/core: the box, everywhere it runsthe servers that run cloud boxes
LifoCloud, lifo cloud, lifo-sh cloud: the clientaccounts, metering and billing
the stand-ins: pg-mem/PGlite via tinbase, the text browser, ffmpeg.wasm, WebLLMthe services: Postgres, Chromium, native ffmpeg
the HTTP and WebSocket APIs, documented in Cloud boxes and Services

A box doesn't depend on Lifo Cloud: everything on this page except the services runs in your tab or on your machine, and a pulled box keeps working there.

See also

  • Cloud boxes: commands, sleep settings, databases, limits and the API
  • Services: tools that run on Lifo's servers, and asking before files leave the box
  • Architecture: inside a box (kernel, shell, Node.js layer)
  • Security and isolation: what a box protects, in a tab and in the cloud

Edit this page on GitHub