# How to Use the `dofs` Package in Cloudflare Computer: Examples and Implementation Guide

> Explore the `@cloudflare/dofs` package in Cloudflare Computer. Discover implementation examples and learn how to leverage this SQLite-backed virtual filesystem for your projects. Get the guide.

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

---

**The `@cloudflare/dofs` package provides a SQLite-backed virtual filesystem used internally by Cloudflare Computer, with direct usage examples found primarily in the test suite where the package is exercised in isolation.**

If you're building on Cloudflare Computer, understanding the `dofs` package helps you grasp how file operations work under the hood. While most developers interact with higher-level APIs, direct access to `dofs` enables custom storage patterns and testing scenarios. This guide walks through concrete examples from the `cloudflare/computer` source code.

## What Is the `dofs` Package?

The `dofs` package implements a **distributed object filesystem**—a virtual filesystem layer backed by SQLite. According to the Cloudflare Computer source code, it powers all file operations in the platform. The package is located in `packages/dofs/` and exposes a low-level `Database` class that higher-level Computer APIs delegate to.

Most repository examples use `dofs` **indirectly** through `@cloudflare/computer` wrappers. For direct usage, you need to examine the test suite and internal components.

## Direct Usage Examples in the Repository

The `cloudflare/computer` repository contains four key patterns for using `dofs` directly. These patterns appear in test files and internal implementations rather than public `examples/` directories.

### Creating a Workspace Database

The foundational pattern initializes a SQLite store and prepares the root inode. You'll see this in [`packages/rpc/tests/shell-and-composite.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/rpc/tests/shell-and-composite.test.ts) at lines 21-22, where the test suite sets up isolated database instances:

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

```

The `initializeSchema` function prepares the database tables for file and directory storage, while `ROOT_INODE` provides the entry point for the filesystem hierarchy.

### Using Test Storage with SQLiteTestStorage

For unit tests and prototypes, the `@cloudflare/dofs/testing` submodule provides `SQLiteTestStorage`. This in-memory SQLite implementation avoids persistence overhead.

Found in [`packages/rpc/tests/wire.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/rpc/tests/wire.test.ts) at lines 15-16:

```typescript
import { SQLiteTestStorage } from '@cloudflare/dofs/testing';

```

This pattern is essential for **fast, isolated testing** without external dependencies.

### Reading and Writing Files

Low-level file operations use methods like `stat`, `writeFile`, and `mkdir` on a `Database` instance. The [`packages/computerd/src/exec/runner.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/exec/runner.test.ts) file demonstrates these operations, showing how the Computer runtime ultimately delegates to `dofs` primitives.

These same methods power the `workspace.runtime` APIs that most developers use daily.

### Synchronizing Changes with applyResult and readWatermark

The sync flow between Durable Objects and sandboxes uses `applyResult` and `readWatermark` utilities. Found in [`packages/rpc/src/sync-driver.ts`](https://github.com/cloudflare/computer/blob/main/packages/rpc/src/sync-driver.ts) at line 29, this pattern shows how the `dofs` sync driver propagates filesystem changes:

```typescript
// From sync-driver.ts line 29
import { applyResult, readWatermark } from '@cloudflare/dofs';

```

## Complete Working Example

Based on the repository patterns, here's a standalone demonstration combining all four approaches. This runs in Node.js or any Worker-compatible environment with SQLite access:

```typescript
// Import the core types and helpers
import { Database, initializeSchema, ROOT_INODE } from '@cloudflare/dofs';
import { SQLiteTestStorage } from '@cloudflare/dofs/testing';

async function demo() {
  // 1️⃣ Create an in-memory SQLite DB (perfect for demos or tests)
  const storage = new SQLiteTestStorage();

  // 2️⃣ Open the DB and set up the schema
  const db = await Database.open(storage);
  await initializeSchema(db);

  // 3️⃣ Write a file under the root inode
  const helloPath = '/hello.txt';
  await db.writeFile(ROOT_INODE, helloPath, Buffer.from('Hello, dofs!'));

  // 4️⃣ Read the file back
  const content = await db.readFile(ROOT_INODE, helloPath);
  console.log(content.toString()); // → "Hello, dofs!"
}

demo().catch(console.error);

```

This example mirrors the initialization pattern in [`packages/rpc/tests/shell-and-composite.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/rpc/tests/shell-and-composite.test.ts) and the file operations from [`packages/computerd/src/exec/runner.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/exec/runner.test.ts).

## Key Source Files for Reference

| File | Purpose |
|------|---------|
| [`packages/dofs/src/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/index.ts) | Core public API of the `dofs` package |
| [`packages/dofs/src/testing.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/testing.ts) | Test utilities including `SQLiteTestStorage` |
| [`packages/rpc/tests/shell-and-composite.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/rpc/tests/shell-and-composite.test.ts) | Typical imports and database setup |
| [`packages/computerd/src/exec/runner.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/exec/runner.test.ts) | File operations using `Database` |
| [`packages/rpc/src/sync-driver.ts`](https://github.com/cloudflare/computer/blob/main/packages/rpc/src/sync-driver.ts) | Sync driver implementing push/pull changes |

## When to Use `dofs` Directly vs. Higher-Level APIs

- **Use `@cloudflare/computer` APIs** for application code, build tooling, and most production scenarios
- **Use `@cloudflare/dofs` directly** when:
  - Building custom test environments
  - Implementing alternative storage backends
  - Debugging filesystem synchronization issues
  - Prototyping low-level storage features

## Summary

- The `dofs` package provides Cloudflare Computer's SQLite-backed virtual filesystem
- Direct usage examples live in the test suite, not public `examples/` directories
- **Key imports**: `Database`, `initializeSchema`, `ROOT_INODE` from `@cloudflare/dofs`
- **Testing helper**: `SQLiteTestStorage` from `@cloudflare/dofs/testing`
- **Core operations**: `writeFile`, `readFile`, `stat`, `mkdir` on `Database` instances
- **Sync utilities**: `applyResult` and `readWatermark` for Durable Object synchronization

## Frequently Asked Questions

### How do I install the `dofs` package?

The `@cloudflare/dofs` package is part of the `cloudflare/computer` monorepo. If you're working within that repository, import directly from the package path. For external projects, check the repository's published packages or build from source. The package is designed for internal use alongside `@cloudflare/computer`.

### Can I use `dofs` outside of Cloudflare Workers?

Yes. The `SQLiteTestStorage` backend runs in standard Node.js environments, making `dofs` usable for local development and testing. Production deployments typically use Durable Object storage bindings, which require the Workers runtime.

### What's the difference between `dofs` and the `workspace.runtime` APIs?

The `workspace.runtime` APIs in `@cloudflare/computer` are **higher-level wrappers** that delegate to `dofs`. They add features like permission management, sandbox isolation, and automatic synchronization. Direct `dofs` usage gives you raw filesystem access without these abstractions.

### Where are the official `dofs` examples?

As of the current `cloudflare/computer` source code, **no public examples** demonstrate standalone `dofs` usage. The package is exercised indirectly through Computer APIs in `examples/` and directly in test files under `packages/*/tests/`. The patterns in this article derive from those test implementations.