How the `dofs` Package Powers Cloudflare Computer's Durable Object File System

The @cloudflare/dofs package (Durable-Object File System) provides the core SQLite-backed virtual filesystem that enables persistent storage, FUSE mounting, and synchronization for Cloudflare Computer.

The dofs package sits at the foundation of the cloudflare/computer project, giving Durable Objects a full POSIX-like filesystem abstraction. Whether you're mounting storage into a sandboxed container or building custom sync logic, understanding how dofs contributes to Cloudflare Computer's features reveals why this architecture enables stateful serverless computing.

What dofs Does: Core Responsibilities

The package bundles five interconnected layers that transform raw Durable Object storage into a usable filesystem:

Database Wrapper Layer

In src/storage.ts, the Database class wraps the DO's native DurableObjectStorage SQL API with ergonomic helpers (run, all, one, scalar) and a re-entrant transaction system. This handles connection pooling and query batching that raw storage access lacks.

Filesystem Primitives Layer

The src/fs/ directory implements POSIX-compatible operations including:

• mkdir, rm, readdir
• writeFile, readFile
• stat, symlink, readlink
• grep, find, watch

These operate directly on SQLite tables rather than a traditional block device, making operations atomic and queryable.

VirtualProvider Adapter Layer

src/provider.ts exports SQLiteWorkspaceProvider, which adapts dofs primitives to the @platformatic/vfs VirtualProvider interface. This bridge is what allows the computerd daemon to mount the filesystem via FUSE inside sandbox containers.

Sync Protocol Layer

The src/sync/ directory contains the wire-format building blocks:

Function	Purpose
applyChanges	Consume incoming change sets from a remote peer
fetchChanges	Query local state for deltas to transmit
pushObjects	Stream blob data to container runtimes
buildManifest	Generate content-addressed snapshots

These power the @cloudflare/computer-rpc communication channel between Durable Objects and container backends.

Schema & Migration Layer

src/schema/ defines the SQLite table structure:

• vfs_nodes – inode metadata and permissions
• vfs_dirents – directory entries linking parents to children
• vfs_chunks – content-addressed file data blocks
• vfs_meta – filesystem-wide properties and versions

How dofs Enables Key Cloudflare Computer Features

FUSE-Mounted Persistent Storage

Without dofs, Cloudflare Computer containers would lose state on every restart. The SQLiteWorkspaceProvider implementation gives containers a stable mountpoint that survives DO migrations:

import { Database, initializeSchema, SQLiteWorkspaceProvider } from '@cloudflare/dofs';

export class WorkspaceDO extends DurableObject {
  private readonly provider: SQLiteWorkspaceProvider;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    const db = new Database(ctx.storage);
    initializeSchema(db, Date.now);
    this.provider = new SQLiteWorkspaceProvider(db); // FUSE-ready VFS
  }
}

The computerd daemon (running in each container) connects to this provider, making the SQLite-backed store appear as a normal Linux filesystem to sandboxed processes.

Bidirectional Synchronization

dofs contributes Cloudflare Computer's live sync capability through low-level primitives that higher-level packages orchestrate:

import { applyChanges, fetchChanges, pushObjects } from '@cloudflare/dofs';

async function syncWithRemote(db: Database, remotePeer: string) {
  // Pull: integrate remote changes into local SQLite state
  const pendingPull = await fetchChanges(db, { since: lastSyncVersion });
  await applyChanges(db, pendingPull);
  
  // Push: stream local blobs to container runtime
  const localDelta = await fetchChanges(db, { since: lastSyncVersion });
  await pushObjects(db, localDelta, { target: remotePeer });
}

This enables real-time collaboration where multiple containers can mount and mutate the same Durable Object filesystem.

Content-Addressed Deduplication

The vfs_chunks table stores file blocks by content hash rather than inode reference. When writeFileSync stores data in src/fs/writeFile.ts, it:

1. Splits content into chunks
2. Hashes each chunk (SHA-256)
3. Inserts only unique chunks
4. Links chunks to inodes in vfs_nodes

This deduplication happens transparently, reducing storage costs for repetitive data patterns.

Direct dofs Usage (Without Full Computer Stack)

Developers can import @cloudflare/dofs independently for lightweight, SQL-backed storage:

import { Database, initializeSchema } from '@cloudflare/dofs';

// Standalone DO with custom storage logic
export class CustomStore extends DurableObject {
  private db: Database;

  constructor(ctx: DurableObjectState) {
    super(ctx, {});
    this.db = new Database(ctx.storage);
    initializeSchema(this.db, Date.now);
  }

  async queryUserFiles(userId: string) {
    // Direct SQL access to filesystem metadata
    return this.db.all(
      `SELECT n.name, n.mtime, c.size 
       FROM vfs_nodes n 
       JOIN vfs_chunks c ON n.id = c.node_id 
       WHERE n.name LIKE ?`,
      [`/users/${userId}/%`]
    );
  }
}

This pattern bypasses @cloudflare/computer entirely while retaining durable, queryable filesystem semantics.

Key Source Files Reference

Path	Contribution to Cloudflare Computer
src/storage.ts	Transaction-safe database access
src/provider.ts	FUSE mount adapter for computerd
src/fs/*.ts	POSIX operations (writeFile, stat, etc.)
src/sync/*.ts	Container-DO synchronization protocol
src/schema/*.ts	SQLite table definitions and migrations
src/index.ts	Public API surface

Summary

The dofs package contributes Cloudflare Computer's foundational storage capabilities through:

• SQLite-backed virtualization – POSIX filesystem in Durable Object SQL storage
• FUSE integration – SQLiteWorkspaceProvider enables container mountpoints
• Sync protocol – applyChanges/fetchChanges enable stateful collaboration
• Content addressing – automatic deduplication via vfs_chunks table
• Standalone usability – direct import for custom DO storage patterns

Current status: Preview only. The API surface remains unstable and is intended for experiments and internal tooling rather than production deployment.

Frequently Asked Questions

What does "dofs" stand for?

DOFS abbreviates Durable-Object File System. The package name reflects its purpose: providing filesystem semantics backed by Durable Object storage rather than a traditional disk or network filesystem.

Can I use dofs without the full Cloudflare Computer stack?

Yes. Install @cloudflare/dofs directly and import Database, initializeSchema, and filesystem primitives. This works for custom Durable Objects needing queryable, persistent storage without container orchestration overhead. The SQLiteWorkspaceProvider adapter is only required for FUSE mounting.

How does dofs handle concurrent writes from multiple containers?

Through Durable Object's single-threaded execution model combined with SQLite transactions. All operations serialize through the DO's event loop. The Database wrapper in src/storage.ts adds re-entrant transaction guards so nested async operations don't deadlock, but external synchronization (via sync protocol operations in src/sync/) is required to coordinate across peer containers.

Is the dofs filesystem performant for large files?

Moderately. Content chunking in vfs_chunks enables incremental updates and deduplication, but large sequential I/O is slower than native filesystems due to SQLite overhead and DO storage latency. The package optimizes for durability and synchronization rather than raw throughput—design patterns with smaller, frequently-changing files match the architecture best.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}