Loads on demand
Loads only what the workload needs
Base images aren't downloaded at boot. Blocks stream in as programs ask for them, and everything a pod writes stays in the browser's own storage.
A filesystem built for the browser
Streamed, not downloaded
Blocks arrive as they're read and are cached locally, so a pod starts without fetching the whole image.
A POSIX-like filesystem
Real file semantics, with bash, git, curl, grep, ripgrep, vi, npm and pnpm in the base image.
Persistent or ephemeral
Pass a storageKey to keep a disk between visits, or leave it out for a fresh disk on every boot.
Stored in the browser
Writes are kept in the Origin Private File System or IndexedDB. Nothing is uploaded.
How the filesystem loads
BrowserPod's filesystem behaves like Ext2, with real POSIX semantics. The base image isn't downloaded when a pod boots. Its blocks stream on demand, over a WebSocket from our disk servers or from any HTTP server that supports byte-range requests.
Every block a program reads is cached locally, and everything it writes stays in the browser, in the Origin Private File System by default or in IndexedDB. Nothing is uploaded, and a returning user's pod reuses what's already stored instead of fetching it again.
A storageKey picks a persistent disk that survives reloads. Leave it out and the pod runs ephemerally, with a fresh disk on every boot and old disks cleaned up for you.
What you need to know
The working directory is /home/user, and /home is kept when BrowserPod upgrades while the rest of the disk resets.
A storageKey disk opens in one tab at a time and raises a catchable error if it's already open, so you can handle it in your UI.
Keep a disk between visits
A storageKey names a persistent disk. Files you create through the API are there for programs in the pod.
import { BrowserPod } from "@leaningtech/browserpod";
// A named disk survives reloads
const pod = await BrowserPod.boot({ storageKey: "my-project" });
await pod.createDirectory("/home/user/app", { recursive: true });
const file = await pod.createFile("/home/user/app/index.js", "utf-8");
await file.write(`console.log("Hello from the pod");`);
await file.close(); Questions
Where are files stored?
In the browser, in the Origin Private File System by default or IndexedDB. Nothing is uploaded.
Can I open the same disk in two tabs?
A persistent disk opens in one tab at a time, with a clear error if it's open elsewhere. Ephemeral pods work in as many tabs as you like.
What's in the base image?
bash, git, curl, grep, openssl, vi, BusyBox coreutils, an ssh client, ripgrep, fd, npm, npx and pnpm, alongside Node.js.
How do I get files into a pod?
Write them from your page with createFile, openFile and createDirectory, or fetch them from inside the pod. git clone works when the pod is connected through BrowserPod Edge.
What happens to files when BrowserPod updates?
Everything in /home is kept, and the rest of the disk resets to the new base image, so users' projects survive upgrades.










