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

> Explore the `@cloudflare/dofs` package and discover how its SQLite-backed virtual filesystem powers persistent storage, FUSE mounting, and synchronization for Cloudflare Computer.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: internals
- Published: 2026-08-15

---

**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](https://github.com/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/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:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/src/storage.ts) | Transaction-safe database access |
| [`src/provider.ts`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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.