Prototype: Expose filesystem to a durable object

[aron-cf]

A core problem with Durable Objects as a runtime for agentic workflows is a lack of filesystem. @cloudflare/computer aims to solve this in user space by using the SQLite store built into each DO as the basis of a virtual filesystem. It goes further by syncing this filesystem to a container using a daemon running on the container so that code execution (such as npm install) runs on the same files.

This PR looks at what it might look like for a Durable Object to have a first class filesystem API that is made available to both the Durable Object itself via either an interface on ctx or by importing "node:fs" directly. Then making this same filesystem available directly to the container.

This pull request gives every SQLite-backed Durable Object a writable filesystem at /data. The filesystem is backed by a second SQLite database that belongs to the object but is separate from the application's ctx.storage and ctx.storage.sql database.

graph TD
  A["node:fs / node:fs/promises"] --> C["/data (virtual filesystem)"]
  B["ctx.filesystem"] --> C
  C --> D["filesystem SQLite database"]
  E["application storage (key/value + SQL)"] --> F["storage SQLite database"]
  D --> G["output gate"]
  F --> G
  H["container /data"] <--> I["9p live mount"]
  I <--> C

Loading

Both Worker-facing surfaces read and write the same bytes (ultimately there should only be one interface). A file written with node:fs is visible through ctx.filesystem, and a file written with ctx.filesystem is visible through node:fs:

import { writeFile, readFile } from "node:fs/promises";
import { DurableObject } from "cloudflare:workers";

export class Workspace extends DurableObject {
  async run() {
    await writeFile("/data/notes.txt", "hello");
    await this.ctx.filesystem.readFile("/data/notes.txt", "utf8"); // "hello"

    await this.ctx.filesystem.writeFile("/data/other.txt", "world");
    await readFile("/data/other.txt", "utf8"); // "world"
  }
}

The ctx.filesystem API is intentionally small. It gives code a promise-based surface over the same tree with readFile, writeFile, readdir, stat, mkdir, rm, and fsync. Writes use the relaxed durability tier: they are committed locally and are visible immediately, but they do not hold the output gate. ctx.filesystem.fsync() performs an explicit strict write, which gives applications a clear point to promote prior filesystem changes to the confirmed durability path.

await this.ctx.filesystem.mkdir("/data/cache");
await this.ctx.filesystem.writeFile("/data/cache/key", bytes);
await this.ctx.filesystem.fsync();

Containers see the same files without touching SQLite. When ctx.container.start() receives a filesystem mount, workerd serves the Durable Object filesystem over 9p and the container mounts it at the requested path. The container and the object then see one live tree as it changes.

ctx.container.start({
  entrypoint: ["sleep", "3600"],
  filesystemMounts: [{ path: "/data" }],
});

await ctx.container.exec(["sh", "-c", "echo hi > /data/hello.txt"]);
await ctx.filesystem.readFile("/data/hello.txt", "utf8"); // "hi\n"
await ctx.filesystem.fsync();

The container API owns the container lifecycle and the mount.

A runnable example lives in examples/filesystem. Its full-cycle worker writes a file from the Durable Object, starts a container with /data mounted live, reads the object's file from the container, writes a second file from the container, and reads that file back from the Durable Object through both node:fs and ctx.filesystem. A second route throws the object away and reads again, which shows the container's write survived in the Durable Object filesystem database.

Build workerd from this branch and run the container example directly with workerd serve:

bazel build //src/workerd/server:workerd
bazel run //images:load_all

cd examples/filesystem
mkdir -p state
../../bazel-bin/src/workerd/server/workerd serve --experimental --directory-path CYCLE_TMPDIR=./state workerd.capnp

Then call the example:

curl localhost:8790/
curl localhost:8790/evict
curl "localhost:8790/read?path=/data/from-container.txt"

The same directory also has a filesystem-only worker that needs no container and can run under wrangler dev against a custom build:

cd examples/filesystem
MINIFLARE_WORKERD_PATH=$PWD/../../bazel-bin/src/workerd/server/workerd npx wrangler dev
curl localhost:8787/

That response shows native node:fs, ctx.filesystem, cross-surface reads, and fsync() all working:

{"nativeWrite":"hi","ctxWrite":"yo","crossRead":["x.txt","y.txt"],"fsync":"confirmed"}

examples/filesystem/README.md covers both flows and calls out the requirements that are easy to miss: the worker needs the experimental flag, the Durable Object class must be SQLite-backed, and the full container cycle needs a local container engine and the test container image.

Follow-up work

This is intended as a UX prototype only, not a suggestion for a real implementation. The use of a second SQLite database is convenience rather than recommendation.