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

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): The core class that holds the VFS and exposes multiple backends for command execution.
• AI Tools Factory (packages/computer/src/tools/ai.ts): The createAITools() function that builds a ToolSet compatible with the AI SDK.
• Think Agent (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) 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:

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 constructs a ToolSet that conforms to the AI SDK specification. This factory function accepts a workspace instance and configuration options:

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, supports backend selection through its parameters. By default, commands execute on the fast shell backend, but you can force container execution:

// 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) 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():

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:

# 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, 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. 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) 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) 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.

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