What Is the cloudflare/computer Repository? Understanding Cloudflare Computer

The cloudflare/computer repository implements Cloudflare Computer, a preview platform that equips Durable Objects with a persistent SQLite-backed virtual filesystem and pluggable execution backends for running agent code in containers, worker shells, or JavaScript environments.

The cloudflare/computer repository provides the foundational infrastructure for Cloudflare Computer, giving AI agents and serverless functions a durable workspace that survives Durable Object restarts. It combines a virtual filesystem interface with interchangeable execution environments, allowing developers to choose between full Linux containers or lightweight worker-based runtimes depending on their workload requirements.

Core Architecture and Purpose

Cloudflare Computer centers on the Workspace abstraction, which exposes two primary interfaces: workspace.fs for filesystem operations and workspace.runtime for code execution. According to the source code in packages/computer/README.md, all files are stored in the Durable Object's SQLite database, ensuring persistence across isolates without external storage dependencies.

The architecture separates storage from execution. While the Durable Object maintains the authoritative state in SQLite, actual command execution happens in one of three interchangeable backends that synchronize with the workspace over Cap'n Proto RPC channels.

The Three Execution Backends

Developers can select from three distinct execution environments based on performance and compatibility needs.

Container Backend

The Container backend mounts the workspace as a real FUSE filesystem inside a sandbox container running the computerd daemon. Implemented in packages/computer/backends/container/index.ts, this backend executes full Linux user-land commands and syncs changes back to the Durable Object via a Cap'n Proto-based RPC channel. This is the most compatible option for complex tooling or native dependencies.

Worker-Shell Backend

The Worker-shell backend provides a lightweight alternative using the just-bash runtime inside a Dynamic Worker. As defined in packages/computer/backends/worker-shell/index.ts, all filesystem operations forward directly to the Durable Object, eliminating the sync round-trip required by the container approach. This backend is ideal for fast, stateless shell commands.

Worker-JavaScript Backend

The Worker-JavaScript backend evaluates ECMAScript modules in a fresh Dynamic Worker, offering a Node-like fs/promises API alongside safe ws:git and ws:artifacts modules. The implementation in packages/computer/backends/worker-javascript/index.ts allows agents to execute JavaScript code directly against the workspace without container overhead.

The Workspace API

Filesystem Interface

The workspace.fs object mirrors the Node.js fs/promises API, providing methods like readFile, writeFile, mkdir, readdir, rm, and grep. All operations target the SQLite-backed VFS provided by the @cloudflare/dofs package, ensuring atomicity and durability. Files survive Durable Object restarts because the storage lives in the object's SQLite database rather than ephemeral memory.

Runtime Execution

The workspace.runtime.exec(source, options) method serves as the single entry point for running code. Depending on the selected backend, the source parameter accepts either shell commands or ECMAScript modules. The method returns a handle that must be properly disposed using the using keyword to prevent memory leaks in long-living isolates, as documented in the stub disposal guidelines.

Package Structure

The repository organizes functionality into tightly-coupled packages:

• @cloudflare/dofs: Provides the SQLite-backed virtual filesystem and sync protocol primitives
• @cloudflare/computer-rpc: Contains Cap'n Proto wire types and client/server helpers shared between the Durable Object and computerd
• @cloudflare/computerd: The daemon that mounts the VFS via FUSE and exposes an HTTP/WebSocket RPC server
• @cloudflare/computer: The high-level façade exporting Workspace, filesystem methods, runtime execution, and optional Git helpers
• @cloudflare/computer-computerd-linux-x64: Docker image providing the pre-built computerd binary for container deployments

RPC and Synchronization

The capnweb RPC contract specified in docs/08_capnweb_interface.md defines how the Durable Object and computerd exchange state updates, command results, and stub lifecycle events. This protocol ensures that filesystem changes in the container propagate back to the SQLite database and that execution results return correctly to the invoking worker.

Additional Capabilities

Git Integration

The optional workspace.git interface provides isomorphic-git glue that operates directly on the SQLite VFS without requiring a backend. This allows agents to clone, commit, and push repositories stored entirely within the Durable Object.

Assets and Artifacts

Helper functions enable publishing workspace files to external storage. The createAssets function uploads to Cloudflare R2, while createArtifact publishes to Cloudflare Artifacts, facilitating artifact generation and distribution workflows.

Observability

A pluggable observer interface emits spans for every operation, compatible with Cloudflare tracing, OpenTelemetry, or custom test recorders. This enables detailed performance monitoring and debugging across all backends.

Implementation Examples

Creating a minimal workspace requires extending a Durable Object with the withWorkspace mixin and retrieving the workspace via getWorkspace:

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>;

To run shell commands using the Worker-shell backend, configure the backend in the Durable Object constructor:

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],
      }),
    ],
  })
) {}

For full Linux container execution, specify the sandbox backend when calling exec:

using ws = await getWorkspace(env.Agent.get(id));
using run = await ws.runtime.exec("cat /workspace/notes.md", { backend: "sandbox" });
const { stdout } = await run.result();

Summary

• The cloudflare/computer repository provides Cloudflare Computer, a platform giving Durable Objects persistent SQLite-backed filesystems and flexible execution environments.
• Three backends—Container, Worker-shell, and Worker-JavaScript—allow trade-offs between compatibility and performance.
• The Workspace API exposes standard filesystem methods and a unified exec interface regardless of backend choice.
• Files persist in the Durable Object's SQLite database via the @cloudflare/dofs package, surviving restarts without external storage.
• Cap'n Proto RPC enables synchronization between the Durable Object and containerized execution environments.
• Built-in Git integration, asset publishing, and observability hooks support complete agent workflows.

Frequently Asked Questions

What is the primary purpose of the cloudflare/computer repository?

The repository implements Cloudflare Computer, a preview platform that enables AI agents and workers to maintain persistent state across executions using a SQLite-backed virtual filesystem. It solves the ephemeral storage limitation of serverless environments by storing data directly in Durable Objects while supporting multiple execution backends.

How does the cloudflare/computer repository differ from standard Durable Object storage?

Unlike standard Durable Object key-value storage, this repository provides a complete virtual filesystem interface (fs/promises API) and pluggable execution environments. Agents can execute shell commands or JavaScript modules against the stored files using backends that range from lightweight workers to full Linux containers, with automatic synchronization handled via Cap'n Proto.

What are the execution backends available in cloudflare/computer?

The repository offers three backends: the Container backend for full Linux compatibility via FUSE and computerd, the Worker-shell backend for fast bash execution using just-bash, and the Worker-JavaScript backend for running ECMAScript modules with Node-like filesystem access. Each backend is implemented in packages/computer/backends/ and selectable at runtime.

How does file persistence work in cloudflare/computer?

All files are stored in the Durable Object's SQLite database through the @cloudflare/dofs package. The workspace.fs methods interact with this SQLite-backed VFS, ensuring that data survives Durable Object restarts and hibernation without requiring external databases or object storage.

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