# How to Use AI SDK Tools with a Cloudflare Computer Workspace: Complete Integration Guide

> Integrate AI SDK tools with Cloudflare Computer Workspace. Learn how to use virtual file-system operations like read, write, and exec for seamless cloud-based AI development.

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

---

**Cloudflare Computer exposes a virtual file-system through a `Workspace` class that integrates with the AI SDK via `createAITools()`, providing tools like `read`, `write`, and `exec` that operate across both a fast Worker shell backend and a full Linux container backend.**

Cloudflare Computer provides a deterministic virtual file-system (VFS) that can be accessed from Durable Objects, enabling AI agents to manipulate files and execute commands safely. By integrating the AI SDK with a Cloudflare Computer Workspace, you can build intelligent agents that interact with a persistent filesystem using standard AI tools. This integration leverages the `@cloudflare/computer` package to bridge the AI SDK's tool-calling interface with Cloudflare's edge infrastructure.

## Architecture of AI SDK Integration

The integration between AI SDK tools and a Cloudflare Computer Workspace relies on three core components working together:

- **Workspace** ([`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts)): The core class that holds the VFS and exposes multiple backends for command execution.
- **AI Tools Factory** ([`packages/computer/src/tools/ai.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/ai.ts)): The `createAITools()` function that builds a `ToolSet` compatible with the AI SDK.
- **Think Agent** ([`examples/src/agent.ts`](https://github.com/cloudflare/computer/blob/main/examples/src/agent.ts)): A Durable Object extending the `Think` chat agent that wires the workspace and tools together.

When a request arrives at `/agents/assistant/<name>`, the Worker entry point ([`examples/src/index.ts`](https://github.com/cloudflare/computer/blob/main/examples/src/index.ts)) routes it to the `Assistant` Durable Object. This DO initializes a `Workspace` with two backends: a lightweight **WorkerShellBackend** for fast bash operations and a full **CloudflareContainerBackend** for Linux environments. The `Assistant` overrides `getTools()` to return the AI SDK-compatible `ToolSet`, allowing the AI SDK v7 TUI (`@ai-sdk/tui`) to interact with the filesystem over WebSocket.

## Setting Up Workspace Backends

Before creating AI tools, you must configure the workspace with appropriate backends. The `Workspace` class accepts an array of backends that determine where commands execute:

```typescript
import { Workspace } from "@cloudflare/computer";
import { WorkerShellBackend, CloudflareContainerBackend } from "@cloudflare/computer";

const ws = new Workspace({
  storage: myDOState.storage,
  backends: [
    new WorkerShellBackend({ 
      /* lightweight bash environment */
      backendName: "shell"
    }),
    new CloudflareContainerBackend({ 
      /* full Linux container via capnweb */
      backendName: "container"
    })
  ],
  useThink: true,
});

```

The **WorkerShellBackend** provides a "just-bash" environment inside a Dynamic Worker with fast startup and no public network access, ideal for simple text manipulation and git operations. The **CloudflareContainerBackend** runs a full Linux container via `computerd` over capnweb, providing access to npm, node, python, and any binary available on `$PATH`.

## Creating AI SDK Tools with createAITools()

The `createAITools()` function in [`packages/computer/src/tools/ai.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/ai.ts) constructs a `ToolSet` that conforms to the AI SDK specification. This factory function accepts a workspace instance and configuration options:

```typescript
import { createAITools } from "@cloudflare/computer/tools";
import type { ToolSet } from "ai";

const tools: ToolSet = createAITools({
  workspace: ws,
  shell: {
    defaultBackend: "shell",
    backends: {
      shell: { description: "just-bash in a Dynamic Worker" },
      container: { description: "full Linux container via computerd" },
    },
  },
  readonly: false,  // Set true to disable write operations
  assets: true,     // Enables the optional publish tool
});

```

The resulting `ToolSet` includes **filesystem tools** (`read`, `ls`, `find`, `grep`, `write`, `edit`) and **execution tools** (`exec`, `publish`). Each tool implementation directly uses the workspace's `WorkspaceFileStore` to perform operations.

## Executing Commands Across Backends

The `exec` tool, implemented in [`packages/computer/src/tools/exec.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/exec.ts), supports backend selection through its parameters. By default, commands execute on the fast shell backend, but you can force container execution:

```typescript
// The model can request:
// { name: "exec", arguments: { cmd: "npm install", backend: "container" } }

await model.chat({
  messages: [{ role: "user", content: "Run `npm install`" }],
  tools,
});

```

When `backend: "container"` is specified, the call routes through the `CloudflareContainerBackend`, which communicates over a capnweb WebSocket at the `/ws` endpoint. The system prompt (defined in `getSystemPrompt()` within [`examples/src/agent.ts`](https://github.com/cloudflare/computer/blob/main/examples/src/agent.ts)) encourages models to prefer the fast shell backend before falling back to the container for complex operations.

## Configuring Read-Only and Restricted Toolsets

For scenarios requiring immutable access, pass `readonly: true` to `createAITools()`:

```typescript
import { createReadTool } from "@cloudflare/computer/tools/fs/read";

const restrictedTools = createAITools({
  workspace: ws,
  readonly: true,   // Disables write, delete, exec, and publish
});

```

In read-only mode, only `read`, `ls`, `find`, and `grep` tools are exposed. This configuration is essential when the workspace must not be mutated by AI interactions. The `assets` flag separately controls the optional `publish` tool for deployment operations.

## Running the Complete Example

To see the integration in action locally:

```bash

# From the repository root

npm install
cd examples
npm run dev           # Starts Wrangler dev server on http://127.0.0.1:8787

npm run chat          # Launches the AI-SDK v7 terminal UI

```

The terminal UI connects via WebSocket to `/agents/assistant/<name>`, creates a fresh `Assistant` instance, and streams the chat protocol defined by the `Think` base class. When the model requests file operations, the AI SDK automatically invokes the appropriate tool from the `ToolSet`, which executes against the workspace's VFS.

## Summary

- **Cloudflare Computer** provides a virtual file-system through the `Workspace` class that aggregates multiple execution backends.
- **`createAITools()`** builds an AI SDK-compatible `ToolSet` with filesystem and execution tools backed by the workspace.
- **Backend selection** allows choosing between a fast `WorkerShellBackend` or a full `CloudflareContainerBackend` for command execution.
- **Read-only configurations** restrict the toolset to safe operations when mutation is prohibited.
- The **Think Agent** pattern demonstrates how to wire these components together in a Durable Object for production AI applications.

## Frequently Asked Questions

### How do I choose between the shell backend and container backend?

The **WorkerShellBackend** is optimized for fast startup and simple bash operations without network access, making it ideal for file manipulation and git commands. The **CloudflareContainerBackend** provides a full Linux environment with access to npm, python, and system binaries, but incurs higher latency. According to the source code in [`examples/src/agent.ts`](https://github.com/cloudflare/computer/blob/main/examples/src/agent.ts), the system prompt encourages the model to prefer the shell backend and only request `backend: "container"` when necessary for complex operations.

### Can I restrict the AI from modifying files in the workspace?

Yes. Pass `readonly: true` to `createAITools()` in [`packages/computer/src/tools/ai.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/ai.ts). This configuration exposes only read-only tools (`read`, `ls`, `find`, `grep`) and removes `write`, `edit`, `exec`, and `publish` from the `ToolSet`. This is implemented by filtering the available tools before returning the set to the AI SDK.

### What is the relationship between the Assistant Durable Object and the workspace?

The **Assistant** Durable Object (defined in [`examples/src/agent.ts`](https://github.com/cloudflare/computer/blob/main/examples/src/agent.ts)) extends the `Think` chat agent and acts as the orchestrator. It creates and owns the `Workspace` instance, configures the backends, and overrides `getTools()` to provide the AI SDK-compatible toolset. The DO maintains the workspace state across requests, persisting the virtual filesystem in Durable Object storage while handling WebSocket connections from the AI SDK TUI.

### How does the AI SDK TUI communicate with the Cloudflare Computer workspace?

The AI SDK v7 TUI (`@ai-sdk/tui`) connects to the Cloudflare Worker via WebSocket at the `/agents/assistant/<name>` endpoint. The Worker entry ([`examples/src/index.ts`](https://github.com/cloudflare/computer/blob/main/examples/src/index.ts)) routes this to the `Assistant` Durable Object. The DO handles the chat protocol, receives tool calls from the model, executes them against the workspace VFS, and returns results through the streaming WebSocket connection.