How to Use Cloudflare Computer for AI Agents with a Portable Working Directory

Cloudflare Computer provides AI agents with a durable, SQLite-backed virtual filesystem inside a Durable Object that persists across restarts and exposes a Node.js-compatible fs/promises API through the workspace.fs interface.

Cloudflare Computer enables developers to give AI agents a portable working directory that travels with the agent across any Cloudflare runtime. According to the cloudflare/computer source code, the architecture combines a Durable Object-based virtual filesystem with pluggable execution backends, creating a consistent environment where agents can read, write, and execute code regardless of whether they run in a Worker, container, or chat interface.

Understanding the Three-Layer Architecture

The portable working directory in Cloudflare Computer is implemented through three distinct layers, as defined in the codebase.

Storage Layer: Durable Object Filesystem (DOFS)

At the foundation, the Durable Object owns a SQLite-backed virtual filesystem provided by @cloudflare/dofs. All files are persisted across DO restarts in a single SQLite database. This layer mimics the Node.js fs/promises API and is documented in packages/dofs/README.md and docs/04_filesystem_interface.md.

Workspace Abstraction

The middle layer is the Workspace class defined in packages/computer/src/workspace.ts. This wrapper bundles the VFS and adds an execution surface via workspace.runtime. It exposes two primary surfaces:

• workspace.fs – File operations (read, write, grep, ls) against the SQLite-backed store
• workspace.runtime – Command execution through the exec method, documented in docs/05_runtime_interface.md

Execution Backends

The top layer consists of pluggable backends that implement the exec interface. As implemented in cloudflare/computer, you can choose between:

• computerd – A full Linux container backend
• just-bash (Worker-Shell) – A fast in-Worker shell that starts instantly without container overhead
• Worker-JavaScript – An isolated JavaScript runtime

The Worker-Shell backend is recommended for AI agents because it avoids a second store, making file operations a single RPC hop. Backend selection is documented in packages/computer/README.md and packages/computer/backends/worker-shell/README.md.

Creating a Portable Working Directory for an AI Agent

To equip an AI agent with a portable working directory, you create a Durable Object that mixes in the Workspace functionality and attach a fast backend.

Define a Durable Object with the Workspace Mixin

Use the withWorkspace helper from @cloudflare/computer to install the plumbing that creates a stub to the DO and wires the VFS:

import { withWorkspace, getWorkspace } from "@cloudflare/computer";
import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
import { createAITools } from "@cloudflare/computer/tools";
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: [], // Add command groups like curl, python here
      }),
    ],
  })
) {}

This pattern, defined in packages/computer/src/workspace.ts, ensures the agent has a durable filesystem that survives Durable Object hibernation and migration.

Configure the Worker-Shell Backend

The Worker-Shell Backend provides the best latency characteristics for AI agents. Because it runs inside the Worker rather than a separate container, file operations require only a single RPC hop to the DO's SQLite store. This backend is instantiated as shown in the previous example and documented in packages/computer/backends/worker-shell/README.md.

Initialize AI-SDK Tools

Expose the workspace to your LLM using createAITools from @cloudflare/computer/tools. This function builds a toolbox that an LLM can call, including read, ls, grep, write, edit, delete, and optionally exec and publish:

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

    // Initialize AI tools with workspace reference
    const tools = createAITools({
      workspace: ws,
      read: { maxBytes: 64 * 1024 },
      shell: {
        defaultBackend: "shell",
        backends: { 
          shell: { description: "Fast in-Worker shell." } 
        },
      },
    });

    // The agent can now use tools that operate on the portable working directory
    const result = await model.generateText({
      tools,
      prompt: "Read /prompt.txt and write a poem.",
    });

    return new Response(JSON.stringify(result), { status: 200 });
  },
} satisfies ExportedHandler<Env>;

The tool interface is detailed in docs/09_tool_interface.md.

Working with Files and Commands

Once initialized, the AI agent can interact with the portable working directory through the filesystem and runtime APIs.

File System Operations

The workspace.fs object provides methods that mirror the Node.js fs/promises API. All operations are persisted to the SQLite database in the Durable Object:

using ws = await getWorkspace(env.Agent.get(id));

// Write a file that persists across DO restarts
await ws.fs.writeFile("/prompt.txt", "Write a short poem about clouds.");

// Read file contents
const content = await ws.fs.readFile("/prompt.txt", "utf-8");

// List directory contents
const entries = await ws.fs.ls("/");

These methods are implemented in the DOFS layer and documented in docs/04_filesystem_interface.md.

Shell Execution

Execute commands against the working directory using workspace.runtime.exec. This routes to the configured backend (in this case, the Worker-Shell):

using ws = await getWorkspace(env.Agent.get(id));
await ws.fs.writeFile("/data.txt", "42\n");

// Execute command in the portable working directory
using run = await ws.runtime.exec("cat /data.txt");
const { stdout, exitCode } = await run.result(); 
// stdout === "42\n"

The runtime interface supports streaming events and is documented in docs/05_runtime_interface.md.

Advanced Workflows: Git and Asset Publishing

Cloudflare Computer extends the portable working directory with Git integration and asset publishing capabilities.

Version Control with Git

Use createGitClient to enable version control within the workspace:

import { createGitClient } from "@cloudflare/computer/git";

const ws = new Workspace({
  storage: ctx.storage,
  git: createGitClient(),
  defaultGitIdentity: { 
    name: "Agent", 
    email: "agent@example.test" 
  },
});

// Clone repositories into the durable filesystem
await ws.git.clone({ url: "https://github.com/example/repo.git" });
await ws.fs.writeFile("/notes.md", "Hello world");
await ws.git.add({ paths: ["notes.md"] });
await ws.git.commit({ message: "Add notes" });

Publishing Results via Assets API

Share agent outputs using the Assets API, creating time-expiring URLs:

import { createAssets } from "@cloudflare/computer/assets";

const assets = createAssets(env.ASSETS);

// Publish a file from the working directory
const url = await assets.share(ws, "/output.png", { expiry: 3600 });
console.log("Shareable URL:", url);

Summary

• Cloudflare Computer provides a portable working directory for AI agents through a Durable Object-hosted SQLite filesystem (@cloudflare/dofs).
• The Workspace class (packages/computer/src/workspace.ts) unifies filesystem operations (workspace.fs) and command execution (workspace.runtime).
• The Worker-Shell Backend offers the lowest latency for agents by executing commands within the Worker rather than a separate container.
• AI-SDK Tools (createAITools) expose filesystem operations to LLMs without requiring custom tool implementations.
• All data persists across Durable Object restarts, making the working directory truly durable and portable across Workers, containers, and chat runtimes.

Frequently Asked Questions

How does Cloudflare Computer ensure data persists across agent sessions?

Data persistence is handled by the Durable Object's SQLite-backed virtual filesystem in the @cloudflare/dofs package. When an AI agent writes files via workspace.fs, the data is stored in a SQLite database within the Durable Object. Because Durable Objects maintain state across restarts and migrations, the working directory contents remain available indefinitely until explicitly deleted.

What is the difference between the Worker-Shell and Container backends?

The Worker-Shell Backend (just-bash) executes commands directly within the Cloudflare Worker process, requiring no container startup time and minimizing latency to a single RPC hop. The Container Backend (computerd) launches a full Linux container environment, which provides complete system compatibility but introduces cold-start latency. For AI agents performing file operations and shell commands, the Worker-Shell backend is generally preferred for its speed.

Can the same working directory be accessed from different runtime environments?

Yes. The workspace architecture is designed so that the same portable working directory can be accessed from any Cloudflare runtime, including standard Workers, Linux Containers, or the think chat-agent interface. The Durable Object acts as the single source of truth for the filesystem, while the workspace abstraction provides consistent APIs regardless of which runtime originates the request.

How do I limit what files an AI agent can access within the working directory?

When creating AI tools via createAITools, you can configure constraints such as read: { maxBytes: 64 * 1024 } to limit file sizes. Additionally, the workspace itself operates within the Durable Object's sandbox, and you can implement access controls in your tool calling logic before invoking workspace.fs methods. For stricter isolation, you can instantiate separate Durable Objects with distinct IDs for different agents or users.

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