Cloudflare/Computer Example Usages: Running the Built-in Demo Projects

The cloudflare/computer repository ships four production-ready demo projects—Think chat, Worker-Shell, Container runtime, and tutorial helpers—that demonstrate how to implement Durable Object-based workspaces with virtual filesystems and tool-based command execution.

The cloudflare/computer platform provides a TypeScript SDK for building persistent, stateful compute environments on Cloudflare's edge infrastructure. This guide examines the official cloudflare/computer example usages, detailing how to run the AI-driven Think chat interface, lightweight Worker-Shell backend, and full Linux Container backend implementations locally.

Available Demo Projects in cloudflare/computer

The repository organizes example code into distinct architectural patterns, each targeting different backend capabilities and deployment scenarios.

Think Chat Example

The Think chat example (examples/think/) demonstrates an AI-driven conversational interface built atop a Durable Object with a virtual filesystem (VFS). This example showcases the @cloudflare/computer/tools toolbox, implementing the exec tool with both shell and container back-ends, and integrates with the AI SDK v7 client UI. The architecture routes WebSocket requests through a Worker to a Durable Object that maintains persistent state across conversations.

Worker-Shell Example

The Worker-Shell example (examples/worker-shell/) implements a lightweight just-bash shell running entirely inside a Dynamic Worker loaded via env.LOADER. This demo requires no Docker dependencies, leveraging the WorkerShellBackend class to execute textual tooling commands (cat, grep, ls, etc.) within the JavaScript runtime. It illustrates the simplest pattern for command execution without containerization overhead.

Container Example

The Container example (examples/container/) launches a full Linux container running the computerd daemon, exposing a production-grade VFS via FUSE. This implementation uses the CloudflareContainerBackend class to establish a capnweb RPC session between the Durable Object and the container, enabling execution of real Linux binaries including git, npm, and python. This pattern suits workloads requiring native toolchain compatibility.

Tutorial and Helper Projects

Additional minimal starters in examples/assets and examples/artifacts provide project scaffolding templates. The think-compare-runtimes UI visualizes agent execution metrics across different backend configurations, serving as a reference for performance benchmarking.

Common Architecture Pattern

All cloudflare/computer example usages share a unified five-layer request flow implemented in the source code:

1. Client → Worker – HTTP or WebSocket requests hit a Cloudflare Worker entry point.
2. Worker → Durable Object – The Worker forwards requests to a DO instance that owns a Workspace.
3. Workspace → Backend – The Workspace abstraction routes calls to either a Worker-Shell backend (lightweight) or a Container backend (full Linux).
4. Backend → Runtime – The shell backend executes commands within the Dynamic Worker, while the container backend communicates with computerd via the capnweb binary-compatible RPC protocol.
5. Tools – The @cloudflare/computer/tools package (located in packages/computer/src/tools.ts) supplies standardized read, ls, write, edit, and exec capabilities.

The capnweb contract defined in docs/08_capnweb_interface.md ensures consistent VFS semantics across both backends, maintaining a single source-of-truth SQLite store in packages/dofs.

Running the Examples Locally

All demos require Node.js ≥ 20 and npm install executed at the repository root. Individual examples have specific infrastructure requirements.

Think Demo Setup

The Think example requires Docker for the container backend and a second terminal for the AI SDK client.

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

npm run chat         # Launches AI SDK TUI connecting to the dev server

Worker-Shell Setup

This example runs without Docker dependencies, executing entirely within the Worker runtime.

cd examples/worker-shell
npm run dev          # Starts the Worker and Durable Object

# Test execution via curl:

curl -X POST http://127.0.0.1:8787/c/demo/exec \
     -H 'content-type: application/json' \
     -d '{"command":"cat hello.txt && wc -l hello.txt","encoding":"utf8"}'

Container Setup

Docker is required to build the image containing the computerd daemon.

cd examples/container
npm run dev          # Builds container image and starts Worker + DO

# Basic workflow:

curl -X PUT --data-binary @- http://127.0.0.1:8787/c/demo/file/workspace/hello.txt <<<"hello"
curl http://127.0.0.1:8787/c/demo/file/workspace/hello.txt
curl -X POST http://127.0.0.1:8787/c/demo/exec \
     -H 'content-type: application/json' \
     -d '{"command":"cat /workspace/hello.txt && uname -a","encoding":"utf8"}'

Core API Implementation Examples

The following snippets from the repository demonstrate essential patterns for initializing backends and routing requests.

Think Agent Entry Point

Located in examples/think/src/index.ts, this pattern handles WebSocket upgrades for AI agent communication:

import { routeAgentRequest } from "@cloudflare/think";
export default {
  async fetch(req, env, ctx) {
    const url = new URL(req.url);
    if (url.pathname.startsWith("/agents/assistant/")) {
      return routeAgentRequest(req, env, ctx);
    }
    return new Response("Use the AI SDK client to talk to the agent.", {status: 200});
  },
};

Worker-Shell Backend Configuration

From examples/worker-shell/src/index.ts, this instantiates the lightweight shell backend:

import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
export default {
  async fetch(req, env, ctx) {
    const cwd = "/workspace";
    const workspace = new Workspace({
      backend: new WorkerShellBackend({
        loader: env.LOADER,
        workspace: { binding: "ContainerExample", id: ctx.id.toString() },
        ctx,
        commands: [/* import optional command groups here */],
      }),
    });
  },
};

Container Backend Initialization

From examples/container/src/index.ts, this configures the full Linux container backend:

import { CloudflareContainerBackend } from "@cloudflare/computer/backends/container";
export default {
  async fetch(req, env, ctx) {
    const workspace = new Workspace({
      backend: new CloudflareContainerBackend({
        loader: env.CONTAINER,
        workspace: { binding: "ContainerExample", id: ctx.id.toString() },
        ctx,
      }),
    });
  },
};

Key Source Files Reference

File	Role
packages/computer/README.md	High-level overview of the Computer SDK, Workspace API, and backend implementations.
packages/computer/src/tools.ts	Default implementations of read, ls, write, edit, and exec tools used across demos.
packages/computer/backends/worker-shell/index.ts	Core implementation of the just-bash shell backend.
packages/computer/backends/container/index.ts	Container backend launching computerd and managing capnweb sessions.
examples/think/README.md	Complete walkthrough of the chat example including deployment flags.
examples/worker-shell/README.md	Architecture explanation and quick-start for the shell backend.
examples/container/README.md	Detailed container setup guide including Docker configuration.
docs/08_capnweb_interface.md	Specification of the capnweb RPC protocol powering container communication.

Summary

• The Think example (examples/think/) demonstrates AI chat with dual backend support via routeAgentRequest and the tools API.
• The Worker-Shell example (examples/worker-shell/) provides Docker-free command execution using WorkerShellBackend and env.LOADER.
• The Container example (examples/container/) enables full Linux environments through CloudflareContainerBackend and capnweb RPC.
• All examples require Node.js ≥ 20 and follow the Client → Worker → Durable Object → Workspace → Backend architecture.
• The capnweb interface (docs/08_capnweb_interface.md) standardizes communication between the Durable Object and container runtime.

Frequently Asked Questions

What are the main cloudflare/computer example usages?

The repository provides four primary examples: the Think chat interface for AI-driven conversations with tool use, the Worker-Shell for lightweight bash execution without containers, the Container example for full Linux environments with computerd, and tutorial helpers for scaffolding new projects. Each demonstrates different backend configurations of the Workspace API.

Do I need Docker to run all cloudflare/computer examples?

No. Only the Think and Container examples require Docker to run the container backend. The Worker-Shell example runs entirely within the Cloudflare Worker JavaScript runtime using the WorkerShellBackend, making it suitable for environments without containerization infrastructure.

How does the Workspace API work in these examples?

The Workspace class acts as an abstraction layer between the Durable Object and execution backends. In packages/computer/src/tools.ts, the API exposes methods for filesystem operations and command execution. The Durable Object initializes a Workspace instance with either a WorkerShellBackend (for lightweight tasks) or CloudflareContainerBackend (for full Linux compatibility), routing all tool calls through this interface.

Where is the RPC protocol for container communication defined?

The capnweb RPC protocol is formally specified in docs/08_capnweb_interface.md. This binary-compatible protocol defines how the Durable Object-side WorkspaceProxy exchanges filesystem and runtime calls with the container-side computerd daemon. The implementation ensures consistent VFS semantics and SQLite state management across the network boundary.

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