Where to Find cloudflare/computer Documentation: Complete Guide

The official cloudflare/computer documentation resides in the docs/ directory of the repository, with docs/README.md serving as the primary entry point covering architecture, installation, and API usage.

The cloudflare/computer repository provides a cloud-based workspace environment for AI agents and automated workflows. Understanding where to find the documentation is essential for implementing the Virtual File System (VFS), runtime interfaces, and sync protocols correctly. This guide maps the documentation structure and links design documents to their source code implementations.

cloudflare/computer Documentation Structure

The repository maintains nineteen comprehensive markdown files in the docs/ directory, organized sequentially from high-level concepts to specific implementation details.

Core Architecture and Concepts

Start with docs/README.md for the high-level overview, architecture diagrams, and quick-start examples. This file explains the package purpose and provides a minimal Workspace implementation.

For the underlying storage mechanism, docs/01_vfs.md details the Virtual File System layout, including workspace tree structure, reserved paths, and mount points. The synchronization logic is documented in docs/02_sync_protocol.md, which explains how the Durable Object-backed VFS synchronizes with the sandbox container, while docs/03_filesystem_schema.md covers the SQLite schema underlying the virtual filesystem.

API and Interface Documentation

The filesystem operations are specified in docs/04_filesystem_interface.md, documenting the Workspace.fs API including readFile, writeFile, mkdir, and grep methods. For command execution, refer to docs/05_runtime_interface.md, which defines the Workspace.runtime API (exec, getExec, killExec, disposeExec) and backend routing logic.

Mount interfaces for external storage are covered in docs/06_mount_interface.md (R2-backed, Artifacts, GitHub), while docs/07_injected_service.md describes the in-container computerd service providing FUSE and shell access. The RPC wire protocol between the Durable Object and sandbox is detailed in docs/08_capnweb_interface.md. For AI SDK integration, docs/09_tool_interface.md documents the ready-made tools for @cloudflare/agents.

Advanced Topics and Integrations

Project organization is explained in docs/10_project_layout.md, while lifecycle management appears in docs/11_lifecycle.md (DO incarnations, container lifetime, hibernation). The just-bash Dynamic Worker backend is covered in docs/12_worker_backend.md.

Integration guides include docs/13_git_interface.md for workspace.git and isomorphic-git, docs/14_assets_interface.md for sharing workspace files to R2 and obtaining presigned URLs, and docs/15_artifacts_interface.md for the Cloudflare Artifacts binding (createArtifact).

Execution environments are detailed in docs/16_code_execution.md (runtime architecture) and docs/17_isolate_javascript.md (ECMAScript module isolation with durable imports). Migration guidance resides in docs/18_runtime_migration.md, and performance benchmarks are available in docs/19_performance.md.

Mapping Documentation to Source Implementation

The design documents reference specific implementation files in packages/computer/src/:

• packages/computer/src/workspace.ts — Implements the Workspace, WorkspaceFilesystem, and WorkspaceRuntime classes documented in the interface guides.
• packages/computer/src/backend/container.ts — Contains CloudflareContainerBackend and the withWorkspaceContainer mixin for Durable Object integration.
• packages/computer/src/backend/worker-shell.ts — Provides the just-bash WorkerShellBackend referenced in docs/12_worker_backend.md.
• packages/computer/src/backend/worker-javascript.ts — Implements the isolated JavaScript runtime (WorkerJavaScriptBackend).
• packages/computer/src/git.ts — Glue layer for isomorphic-git integration (docs/13_git_interface.md).
• packages/computer/src/artifacts.ts — Facade for the Cloudflare Artifacts binding (docs/15_artifacts_interface.md).
• packages/computer/src/tools.ts — AI-SDK tools (read, write, ls, exec, publish) documented in the tool interface guide.
• packages/rpc/src/* — Cap'n-Proto RPC wire definitions supporting the Capnweb interface.

cloudflare/computer Usage Examples

The documentation includes runnable TypeScript examples demonstrating common patterns. Below is a complete setup showing how to initialize a workspace and execute filesystem operations:

// 1️⃣ Install the package
// npm install @cloudflare/computer

// 2️⃣ Create a workspace inside a Durable Object
import { Workspace } from "@cloudflare/computer";
import {
  CloudflareContainerBackend,
  withWorkspaceContainer,
} from "@cloudflare/computer/backends/container";

export class Agent extends withWorkspaceContainer(
  class extends DurableObject<Env> {}
) {
  readonly workspace = new Workspace({
    storage: this.ctx.storage,
    backends: [
      new CloudflareContainerBackend({
        container: () => this,
        workspace: { binding: "Agent", id: this.ctx.id.toString() },
      }),
    ],
  });

  async initialize() {
    await this.workspace.ready();                         // ⏳ ensure the VFS is loaded
    await this.workspace.fs.mkdir("/workspace", {        // 📂 create root folder
      recursive: true,
    });
  }

  // 3️⃣ Write a file
  async addTodo() {
    await this.workspace.fs.writeFile(
      "/workspace/todo.txt",
      "- [ ] ship the new feature\n"
    );
  }

  // 4️⃣ Run a shell command in the sandbox
  async listFiles() {
    const exec = await this.workspace.runtime.exec(
      "ls -la /workspace",
      { encoding: "utf8" }
    );
    const { stdout, exitCode } = await exec.result();
    console.log(stdout, exitCode);
  }
}

For streaming large files efficiently without buffering:

const stream = await this.workspace.fs.readFile("/workspace/uploads/big.csv");
return new Response(stream);   // streamed directly to the client

To search the filesystem tree using case-insensitive grep:

const hits = await this.workspace.fs.grep("TODO", "/workspace", {
  ignoreCase: true,
});
hits.forEach(hit => console.log(`${hit.path}:${hit.line}: ${hit.text}`));

For executing long-running commands with Server-Sent Events:

async fetch(request: Request) {
  const exec = await this.workspace.runtime.exec("npm test", { encoding: "utf8" });
  const sse = exec.pipeThrough(
    new TransformStream({
      transform(event, controller) {
        const frame = `event: ${event.name}\ndata: ${JSON.stringify(event.value)}\n\n`;
        controller.enqueue(new TextEncoder().encode(frame));
      },
    })
  );
  return new Response(sse, {
    headers: {
      "content-type": "text/event-stream",
      "cache-control": "no-cache",
      "connection": "keep-alive",
    },
  });
}

Summary

• Primary Location: All cloudflare/computer documentation lives in the repository's docs/ directory, starting with docs/README.md and extending through docs/19_performance.md.
• Architecture Guides: Files 01_vfs.md through 03_filesystem_schema.md explain the Virtual File System, sync protocol, and SQLite storage layer.
• API References: Files 04_filesystem_interface.md and 05_runtime_interface.md document the Workspace.fs and Workspace.runtime APIs.
• Implementation Mapping: Source files in packages/computer/src/ directly implement the patterns described in the documentation, with workspace.ts serving as the main entry point.
• Integration Topics: Specialized guides cover Git (13_git_interface.md), Artifacts (15_artifacts_interface.md), JavaScript isolation (17_isolate_javascript.md), and runtime migration (18_runtime_migration.md).

Frequently Asked Questions

Where is the main entry point for cloudflare/computer documentation?

The main entry point is docs/README.md in the repository root. This file provides the high-level architecture overview, installation instructions, and a navigable table of contents linking to all nineteen specialized topics including the Virtual File System, sync protocols, and runtime interfaces.

How do I find the implementation details for a specific API mentioned in the docs?

Each documentation file in docs/ references specific source files in packages/computer/src/. For example, docs/04_filesystem_interface.md describes the API implemented in packages/computer/src/workspace.ts, while backend-specific logic for containers resides in packages/computer/src/backend/container.ts.

What documentation covers the AI agent tools integration?

The AI SDK tools are documented in docs/09_tool_interface.md, which covers the read, write, ls, exec, and publish tools for @cloudflare/agents. The corresponding implementation is located in packages/computer/src/tools.ts.

Is there documentation for migrating from preview APIs to the stable workspace runtime?

Yes, migration guidance is provided in docs/18_runtime_migration.md, which details the transition path from preview-API surfaces to the stable workspace.runtime interface, including changes to backend initialization and execution methods.

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