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

> Learn how to use Cloudflare Computer for AI agents. Explore its portable working directory and durable SQLite-backed virtual filesystem for persistent data and Node.js compatibility.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: how-to-guide
- Published: 2026-09-04

---

**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`](https://github.com/cloudflare/computer/blob/main/packages/dofs/README.md) and [`docs/04_filesystem_interface.md`](https://github.com/cloudflare/computer/blob/main/docs/04_filesystem_interface.md).

### Workspace Abstraction

The middle layer is the `Workspace` class defined in [`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/packages/computer/README.md) and [`packages/computer/backends/worker-shell/README.md`](https://github.com/cloudflare/computer/blob/main/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:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/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:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/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):

```typescript
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`](https://github.com/cloudflare/computer/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/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.