Cloudflare Computer Project Structure: Monorepo Architecture for Virtual Filesystems

The cloudflare/computer repository is organized as a TypeScript monorepo where independent packages implement a virtual filesystem inside a Cloudflare Durable Object, spanning from SQLite storage primitives to a FUSE-mounted container daemon and high-level JavaScript APIs.

The cloudflare/computer project implements the Computer—a virtual filesystem that persists inside a Cloudflare Durable Object. Understanding the cloudflare/computer project structure reveals a deliberate separation of concerns across multiple packages, comprehensive design documentation, and runnable examples that together enable secure, sandboxed code execution at the edge.

Cloudflare Computer Project Structure: Monorepo Packages

The repository follows a strict monorepo pattern where each subdirectory under packages/ represents an independently versioned npm package. This separation allows the SQLite storage layer, RPC transport, container daemon, and public API to evolve without tight coupling.

Virtual Filesystem Core (packages/dofs)

The packages/dofs directory contains the SQLite-backed virtual filesystem implementation. It defines the on-disk schema and exposes sync-protocol primitives that reconcile state between the Durable Object and remote clients. This package is published as @cloudflare/dofs and provides the foundational storage abstraction used throughout the system.

RPC Transport Layer (packages/rpc)

Located in packages/rpc, this package defines the Cap'n Web RPC definitions and client/server helpers. It declares the WorkspaceRPC interface in packages/rpc/src/interface.ts, establishing the contract for sync and shell operations that bridge the Durable Object and the in-container daemon (computerd).

Container Daemon (packages/computerd)

The packages/computerd package implements the sandbox daemon that runs inside a containerized environment. It mounts the virtual filesystem via FUSE and exposes an HTTP/WebSocket RPC endpoint, handling process execution through packages/computerd/src/exec/runner.ts which streams ExecEvents back to the caller.

Public API Façade (packages/computer)

packages/computer serves as the public entry point published as @cloudflare/computer. It wires together the various backends and provides the workspace.runtime API alongside the fs surface, abstracting RPC details and offering a unified interface for Durable Object consumers.

Binary Distribution (packages/computer-computerd-linux-x64)

This package contains the Docker context required to build the pre-compiled Linux x64 computerd binary. It ensures the container backend has a reproducible, versioned artifact for deployment.

Documentation and Example Implementations

Beyond the core packages, the repository includes comprehensive design documentation and working examples that demonstrate the cloudflare/computer project structure in practice.

Design Specifications (docs/)

The docs/ directory contains forward-looking architecture specifications, including the cap'n Web contract, sync protocol details, filesystem schema, and runtime interface definitions. These documents describe intended interactions and future-proof the design against breaking changes.

End-to-End Examples (examples/)

The examples/ directory hosts runnable Workers demonstrating real-world usage of the public API. These include implementations for the container backend, shell backend, JavaScript backend, a Think-agent UI, and various tutorials that showcase how to create workspaces and execute commands.

Architecture Flow in the Cloudflare Computer Project

Understanding how components interact clarifies the runtime behavior of the cloudflare/computer project structure.

The Durable Object maintains authoritative state in SQLite, managed through packages/dofs. When a client initiates an operation, packages/computer selects an appropriate backend—container, shell, or javascript—and routes commands through the Cap'n Web RPC channel defined in packages/rpc. For containerized workloads, packages/computerd receives these calls, mounts the virtual filesystem via FUSE, and spawns processes using the exec runner. Results stream back through the same RPC layer, with the ChangeEntry primitives in packages/dofs/src/sync/changes.ts ensuring filesystem consistency.

Key Implementation Files

Several specific source files define critical behavior within the architecture:

• packages/dofs/src/sync/changes.ts: Defines ChangeEntry types used by the sync protocol to track filesystem mutations.
• packages/rpc/src/interface.ts: Declares the WorkspaceRPC interface specifying available remote procedures.
• packages/computerd/src/exec/runner.ts: Implements process spawning and event streaming for command execution.
• packages/computer/src/index.ts: Exports the public workspace object providing runtime and fs APIs.
• docs/08_capnweb_interface.md: Documents the RPC contract design.
• examples/container/README.md: Demonstrates complete container backend integration.

Interacting with the Public API

Developers consume the system through the @cloudflare/computer package, which abstracts the underlying complexity.

import { workspace } from '@cloudflare/computer';

// Execute a command in the container backend
await workspace.runtime.exec('ls -la', {
  backend: 'container',
});

// Read from the virtual filesystem
const data = await workspace.fs.readFile('/hello.txt', 'utf8');
console.log('File contents:', data);

This example demonstrates the high-level façade selecting the FUSE-backed container runtime and accessing the virtual filesystem surface.

Summary

• The cloudflare/computer project structure follows a monorepo pattern with five distinct packages under packages/.
• packages/dofs provides the SQLite-backed virtual filesystem and sync primitives.
• packages/rpc defines the Cap'n Web transport layer and WorkspaceRPC interface.
• packages/computerd runs as a FUSE-mounting daemon inside sandboxed containers.
• packages/computer exposes the public @cloudflare/computer API consumed by Durable Objects.
• The repository includes extensive design documentation in docs/ and working examples in examples/ demonstrating container, shell, and JavaScript backends.

Frequently Asked Questions

What is the difference between packages/computer and packages/computerd?

packages/computer is the public npm package (@cloudflare/computer) that Durable Objects import to interact with the system, providing high-level APIs like workspace.runtime.exec(). packages/computerd is the sandbox daemon that runs inside containers, mounts the filesystem via FUSE, and handles low-level process execution, communicating with the Durable Object via RPC.

How does data persistence work in the cloudflare/computer architecture?

The Durable Object maintains the authoritative SQLite database state, while packages/dofs manages the virtual filesystem schema and sync protocol. When computerd runs inside a container, it mounts this virtual filesystem via FUSE, ensuring all file operations persist back to the Durable Object's SQLite store through the sync primitives defined in packages/dofs/src/sync/changes.ts.

Which backends are available when using the @cloudflare/computer API?

The public API supports three backend options: container (uses the FUSE-mounted filesystem via computerd), shell (executes commands in a shell environment), and javascript (runs JavaScript code directly). You specify the backend in the workspace.runtime.exec() options object to control where code executes.

Where are the RPC interface definitions located in the repository?

The Cap'n Web RPC definitions reside in packages/rpc/src/interface.ts, which declares the WorkspaceRPC interface including sync and shell methods. The design-level specification for this contract is documented in docs/08_capnweb_interface.md, providing the architectural foundation for communication between the Durable Object and container daemon.

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