Filesystem

How the virtual filesystem is structured and how it behaves

Each Pod includes a virtual filesystem with POSIX-style paths (for example, /project/main.js). This filesystem lives inside the Pod runtime and is exposed through the BrowserPod API.

What the filesystem is

The Pod filesystem is a virtual, Linux-like filesystem presented to processes running inside the Pod, whether that’s the Node.js runtime or a compiled binary started with pod.run(...). It behaves like a typical POSIX filesystem:

  • Paths are absolute and use / as the separator.
  • Directories and files are distinct nodes.
  • Processes see a current working directory (cwd) when they run.
  • File handles are explicit and must be closed.

It is not the same as your machine’s filesystem and has no direct access to local disk. Everything exists inside the Pod runtime.

Persistence and storage

By default a Pod is ephemeral: every boot starts from a fresh filesystem and nothing is saved. To keep the filesystem between sessions, pass a storageKey to boot:

  • Booting with the same key resumes the same filesystem, across page reloads and browser sessions.
  • Booting with a different key starts a separate filesystem.
  • A key can only be used by one tab at a time. Booting with a key that is already in use in another tab fails.

Persistent data is stored in the browser’s Origin Private File System (OPFS), or in IndexedDB if the browser does not support OPFS. Storage is scoped to the origin, so a different origin never sees the same data, even with the same key.

The filesystem is still virtual: the browser stores it in an internal format that is not human-readable.

To start a Pod with files already in place, pass your own ext2 disk image as userImage to boot. Its contents appear under /home: a file at user/notes.txt in the image becomes /home/user/notes.txt.

When you change userImage, also change the storageKey. Otherwise booting can fail for returning users, or they keep seeing the old image. Updating to a newer BrowserPod version keeps /home but resets the rest of the filesystem.

Files, handles, and modes

The API returns file handles when you open or create a file. A handle represents an open file descriptor inside the Pod runtime. Handles are not automatically garbage collected; you must close them explicitly to release the underlying resources.

BrowserPod supports two file modes:

  • "binary" for raw bytes
  • "utf-8" for text

These modes determine the type of file handle you receive and the type of data it reads or writes.

Process view of the filesystem

Processes launched with pod.run(...) see the filesystem as their local disk. When a process starts, it can read and write the same filesystem tree the API exposes. The cwd option sets the working directory for that process. It does not change the filesystem itself; it only changes how relative paths are resolved inside that process.

All processes in the same Pod share the same filesystem state.

If you need to write files into the Pod or copy in a project, see the guide: Write files to the pod.