What Is the @cloudflare/computer Package? Architecture and Virtual Filesystem for Durable Objects

The @cloudflare/computer package serves as the central library that transforms Cloudflare Durable Objects into persistent development sandboxes by providing a durable SQLite-backed virtual filesystem, Node-style fs APIs, and pluggable execution backends including container, shell, and JavaScript runtimes.

The @cloudflare/computer package is the core library within the cloudflare/computer repository that enables stateful, long-running computation inside Cloudflare's edge infrastructure. By wrapping Durable Object storage with a virtual filesystem and execution layer, this package allows developers to run commands, manage files, and execute AI agents with complete data persistence across invocations and restarts.

Core Architecture: The Workspace Class and Virtual Filesystem

At the heart of the package is the Workspace class defined in packages/computer/src/workspace.ts. This class wraps a Durable Object's ctx.storage and exposes a Node-compatible filesystem API that persists all data to the DO's built-in SQLite database.

SQLite-Backed Persistence

Unlike ephemeral Workers storage, the @cloudflare/computer virtual filesystem survives Durable Object restarts. All file operations—readFile, writeFile, mkdir, readdir, rm, and grep—write directly to the DO's durable SQLite instance, ensuring that your development environment maintains state exactly like a local filesystem.

Node-Style API Surface

The Workspace exposes familiar Node.js filesystem methods that require no learning curve for JavaScript developers. According to the source in packages/computer/README.md, you can interact with files using standard async patterns:

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

Execution Backends: Three Runtime Options

The package provides a workspace.runtime.exec layer capable of running commands or JavaScript modules against the same virtual filesystem. The architecture supports three interchangeable backends defined in the backends/ directory.

Container Backend

The Container backend spins up a full Linux container via the computerd daemon, enabling execution of real binaries like npm and node. This backend requires container infrastructure but provides the most authentic Linux environment.

Worker-Shell Backend

For lightweight operations, the Worker-shell backend (packages/computer/src/backends/worker-shell/worker-shell.ts) runs a Bash interpreter called just-bash entirely inside a Cloudflare Worker. This requires no container infrastructure and executes shell commands with minimal overhead:

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

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

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

    using run = await ws.runtime.exec("curl https://example.com");
    const { stdout, exitCode } = await run.result();
    return new Response(stdout, { status: exitCode === 0 ? 200 : 500 });
  },
} satisfies ExportedHandler<Env>;

Worker-JavaScript Backend

The Worker-JavaScript backend executes ECMAScript modules inside a dynamic Worker using the same virtual filesystem storage. This enables high-performance JavaScript execution without the overhead of containerization.

AI-Ready Tooling and Utilities

Beyond filesystem and execution capabilities, @cloudflare/computer bundles high-level utilities designed specifically for AI agents. The package exports AI-SDK-ready tools including read, ls, find, grep, write, edit, and delete, plus optional exec and publish capabilities.

Git Integration and R2 Mounts

The package includes a dedicated Git client (@cloudflare/computer/git) for repository operations, R2 read-only mounts for object storage integration, and artifact publishing workflows. These tools allow AI agents to clone repositories, modify files, commit changes, and deploy artifacts without leaving the Durable Object environment.

Package Entry Points and RPC Architecture

The main entry point at packages/computer/src/index.ts re-exports the Workspace wrapper, backend factories, and proxy classes. Notably, the actual RPC plumbing (capnweb) lives in the sibling package @cloudflare/computer-rpc, keeping the core package focused on filesystem semantics while delegating network communication to a dedicated dependency.

Summary

• @cloudflare/computer transforms Cloudflare Durable Objects into persistent development sandboxes via a SQLite-backed virtual filesystem.
• The Workspace class in packages/computer/src/workspace.ts provides Node-style fs APIs that survive DO restarts.
• Three execution backends—Container, Worker-shell, and Worker-JavaScript—offer flexible runtime options ranging from full Linux containers to lightweight Worker-based execution.
• Built-in utilities include AI-SDK tools, a Git client (createGitClient), R2 mounts, and artifact publishing capabilities.
• The package entry point (packages/computer/src/index.ts) cleanly separates core filesystem logic from RPC concerns handled by @cloudflare/computer-rpc.

Frequently Asked Questions

How does @cloudflare/computer persist data across Durable Object restarts?

All filesystem operations write to the Durable Object's built-in SQLite database via ctx.storage. The Workspace class wraps this storage layer, ensuring that files created via writeFile or mkdir remain available even when the DO hibernates or restarts, as implemented in packages/computer/src/workspace.ts.

Which execution backend should I choose for my application?

Choose the Container backend when you need real Linux binaries like npm or node. Use the Worker-shell backend (packages/computer/src/backends/worker-shell/worker-shell.ts) for lightweight Bash scripting without container overhead. Select the Worker-JavaScript backend for executing ECMAScript modules at maximum performance within the Worker runtime.

Can I use @cloudflare/computer without container infrastructure?

Yes. The Worker-shell backend runs entirely within Cloudflare Workers using the just-bash interpreter, requiring no computerd daemon or container runtime. This backend supports common shell commands and can be extended with module loaders like curlModules for network operations.

How do AI agents interact with the filesystem through this package?

AI agents consume the high-level tools exported by @cloudflare/computer, including read, write, edit, ls, and grep. These tools map directly to the Workspace filesystem API, allowing agents to manipulate files persistently. The package also provides createGitClient for version control operations and R2 integration for object storage access.

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