Main Components of the Cloudflare Computer Project: Architecture and Package Guide

The Cloudflare Computer repository is organized as a monorepo containing five core packages that implement a durable, SQLite-backed virtual filesystem for Cloudflare Durable Objects with pluggable execution backends.

The cloudflare/computer project enables persistent storage and code execution within Cloudflare's edge infrastructure. Understanding the main components of the cloudflare/computer project is essential for developers building durable agents, automation workflows, or long-running processes that require consistent filesystem access across requests.

The Five Core Packages

The architecture separates storage concerns, RPC communication, daemon management, and public APIs into distinct modules. Each package serves a specific role in the durable workspace ecosystem.

@cloudflare/dofs – Durable Object File System

The @cloudflare/dofs package provides the foundational storage layer. It implements a SQLite-backed virtual filesystem with synchronization protocols and a Node-style VFS provider (@platformatic/vfs). This component acts as the authoritative storage layer for a workspace, persisting data across Durable Object invocations.

Key implementation details reside in packages/dofs/src/filesystem.ts, which contains the core VFS logic. The package handles all low-level filesystem operations, ensuring ACID compliance through SQLite transactions within the Durable Object's storage subsystem.

@cloudflare/computer-rpc – Cap’n Web RPC Layer

Communication between the Durable Object and external processes flows through @cloudflare/computer-rpc. This package defines the Cap’n Web wire types and helper utilities that enable bidirectional RPC channels.

All cross-process calls—including filesystem synchronization and execution requests—traverse this contract. The RPC definitions live in packages/rpc/src/capnweb.ts, while the design specification is documented in docs/08_capnweb_interface.md. This layer abstracts the transport mechanism, allowing seamless communication between sandboxed containers and the Durable Object.

@cloudflare/computerd – Daemon and FUSE Mount

The @cloudflare/computerd package contains the daemon process that bridges the gap between the Durable Object storage and traditional POSIX environments. Running inside a sandbox container, this daemon mounts the DO-backed filesystem via FUSE and exposes an HTTP/WebSocket RPC server.

Implemented primarily in packages/computerd/src/daemon.ts, this component forwards filesystem operations and execution requests to the Durable Object. It translates local system calls into RPC messages, enabling standard Linux binaries to interact with the durable storage layer transparently.

@cloudflare/computer – Public API

The @cloudflare/computer package serves as the primary entry point for Durable Object authors. It bundles the high-level Workspace class that exposes two critical surfaces: workspace.fs for filesystem operations and workspace.runtime.exec for code execution.

The public API implementation in packages/computer/src/workspace.ts aggregates functionality from the underlying packages. It provides utilities for read-only mounts, AI tool integrations, git helpers, and backend registration. Developers import methods like withWorkspace() and getWorkspace() from this package to initialize their durable workspaces.

computer-computerd-linux-x64 – Pre-built Binary

The computer-computerd-linux-x64 package supplies the pre-compiled computerd binary for Linux x64 architectures. Unlike the npm-distributed packages, this artifact is built within a private Docker image and shipped as a standalone binary.

This component enables the container backend execution mode, allowing the system to run real Linux binaries against the mounted filesystem. The binary handles FUSE operations and RPC communication within sandboxed environments.

Pluggable Execution Backends

Beyond storage, the cloudflare/computer project supports three distinct execution backends that workspaces can register based on isolation and performance requirements:

• Container backend – Mounts the filesystem via FUSE inside a sandbox container and executes real Linux binaries through the computerd daemon.
• Isolate shell backend – Runs a minimal Bash-like environment (just-bash) inside a Dynamic Worker, communicating directly with the Durable Object without container overhead.
• Isolate JavaScript backend – Executes ECMAScript modules inside a Dynamic Worker, accessing the same durable filesystem through JavaScript APIs.

These backends allow developers to trade off between full POSIX compatibility and lightweight JavaScript execution while maintaining consistent storage semantics.

Critical Source Files and Implementation Details

Understanding the codebase requires familiarity with these specific implementation files:

• packages/dofs/src/filesystem.ts – Core virtual filesystem implementation with SQLite persistence.
• packages/rpc/src/capnweb.ts – Cap’n Proto wire format definitions for cross-process communication.
• packages/computerd/src/daemon.ts – FUSE mount logic and RPC server implementation.
• packages/computer/src/workspace.ts – Public Workspace class exposing fs and runtime surfaces.
• docs/08_capnweb_interface.md – Formal specification of the RPC contract between components.
• examples/worker-shell/README.md – End-to-end integration examples for the worker-shell backend.

Working with the Components

Creating a Durable Filesystem Workspace

To initialize a workspace with only storage capabilities, extend your Durable Object using the withWorkspace mixin:

import { withWorkspace, getWorkspace } from "@cloudflare/computer";
import { DurableObject } from "cloudflare:workers";

export class Agent extends withWorkspace(
  class extends DurableObject<Env> {},
  (self) => ({ storage: self.ctx.storage })
) {}

export default {
  async fetch(request: Request, env: Env) {
    const id = env.Agent.idFromName("user-123");
    using ws = await getWorkspace(env.Agent.get(id));

    await ws.fs.writeFile("/notes.md", "- [ ] ship it\n");
    const notes = await ws.fs.readFile("/notes.md", "utf8");
    return new Response(notes);
  },
} satisfies ExportedHandler<Env>;

Adding the Worker-Shell Execution Backend

To enable command execution within the isolate, register the WorkerShellBackend during workspace initialization:

import { withWorkspace, getWorkspace } from "@cloudflare/computer";
import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
import curlModules from "@cloudflare/computer/shell/curl";
import { DurableObject } from "cloudflare:workers";

export class Agent extends withWorkspace(
  class extends DurableObject<Env> {},
  (self) => ({
    storage: self.ctx.storage,
    backends: [
      new WorkerShellBackend({
        loader: self.env.LOADER,
        workspace: { binding: "Agent", id: self.ctx.id.toString() },
        ctx: self.ctx,
        commands: [curlModules],
      }),
    ],
  })
) {}

Executing Commands Against the Mounted Filesystem

Once configured, execute commands and interact with the persistent filesystem:

using ws = await getWorkspace(env.Agent.get(id));
await ws.fs.writeFile("/hello.txt", "world");
using run = await ws.runtime.exec("cat /hello.txt");
const { stdout } = await run.result();
console.log(stdout); // → "world"

Summary

• The cloudflare/computer project consists of five core packages: @cloudflare/dofs (storage), @cloudflare/computer-rpc (communication), @cloudflare/computerd (daemon/FUSE), @cloudflare/computer (public API), and computer-computerd-linux-x64 (binary distribution).
• The architecture separates durable SQLite-backed storage from execution environments through a virtual filesystem abstraction.
• Three pluggable backends—Container, Isolate Shell, and Isolate JavaScript—provide flexible trade-offs between POSIX compatibility and performance.
• Key source files include packages/dofs/src/filesystem.ts for VFS logic and packages/computer/src/workspace.ts for the public API surface.
• The system enables Cloudflare Durable Objects to maintain persistent workspaces accessible across requests and execution contexts.

Frequently Asked Questions

What is the relationship between @cloudflare/dofs and @cloudflare/computer?

@cloudflare/dofs implements the low-level SQLite-backed virtual filesystem, while @cloudflare/computer provides the high-level public API that developers consume. The computer package re-exports and orchestrates dofs functionality alongside execution backends, presenting a unified Workspace interface with fs and runtime properties.

How does the computerd daemon communicate with the Durable Object?

The daemon uses Cap’n Web RPC protocol defined in @cloudflare/computer-rpc to establish bidirectional communication channels. Implemented in packages/computerd/src/daemon.ts, it translates local FUSE filesystem operations into RPC messages sent to the Durable Object, which handles the actual SQLite storage transactions.

Can I use the filesystem without the container backend?

Yes. The @cloudflare/dofs package functions independently as a durable storage layer. You can create workspaces using only the filesystem capabilities through withWorkspace() without registering any execution backends, or use the lightweight Isolate Shell or Isolate JavaScript backends instead of the container-based solution.

Where are the RPC protocol specifications documented?

The Cap’n Web interface specification is documented in docs/08_capnweb_interface.md at the repository root. This file defines the wire format and contract used for all communication between the computerd daemon, execution backends, and the Durable Object storage layer.

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