# What Is the cloudflare/computer Repository? Understanding Cloudflare Computer

> Discover the cloudflare/computer repository, a preview platform for Durable Objects. It offers a virtual filesystem and pluggable backends for running agent code efficiently.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: getting-started
- Published: 2026-08-09

---

**The cloudflare/computer repository implements Cloudflare Computer, a preview platform that equips Durable Objects with a persistent SQLite-backed virtual filesystem and pluggable execution backends for running agent code in containers, worker shells, or JavaScript environments.**

The cloudflare/computer repository provides the foundational infrastructure for Cloudflare Computer, giving AI agents and serverless functions a durable workspace that survives Durable Object restarts. It combines a virtual filesystem interface with interchangeable execution environments, allowing developers to choose between full Linux containers or lightweight worker-based runtimes depending on their workload requirements.

## Core Architecture and Purpose

Cloudflare Computer centers on the **Workspace** abstraction, which exposes two primary interfaces: `workspace.fs` for filesystem operations and `workspace.runtime` for code execution. According to the source code in [`packages/computer/README.md`](https://github.com/cloudflare/computer/blob/main/packages/computer/README.md), all files are stored in the Durable Object's SQLite database, ensuring persistence across isolates without external storage dependencies.

The architecture separates storage from execution. While the **Durable Object** maintains the authoritative state in SQLite, actual command execution happens in one of three interchangeable backends that synchronize with the workspace over Cap'n Proto RPC channels.

## The Three Execution Backends

Developers can select from three distinct execution environments based on performance and compatibility needs.

### Container Backend

The **Container backend** mounts the workspace as a real FUSE filesystem inside a sandbox container running the `computerd` daemon. Implemented in [`packages/computer/backends/container/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/backends/container/index.ts), this backend executes full Linux user-land commands and syncs changes back to the Durable Object via a Cap'n Proto-based RPC channel. This is the most compatible option for complex tooling or native dependencies.

### Worker-Shell Backend

The **Worker-shell backend** provides a lightweight alternative using the *just-bash* runtime inside a Dynamic Worker. As defined in [`packages/computer/backends/worker-shell/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/backends/worker-shell/index.ts), all filesystem operations forward directly to the Durable Object, eliminating the sync round-trip required by the container approach. This backend is ideal for fast, stateless shell commands.

### Worker-JavaScript Backend

The **Worker-JavaScript backend** evaluates ECMAScript modules in a fresh Dynamic Worker, offering a Node-like `fs/promises` API alongside safe `ws:git` and `ws:artifacts` modules. The implementation in [`packages/computer/backends/worker-javascript/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/backends/worker-javascript/index.ts) allows agents to execute JavaScript code directly against the workspace without container overhead.

## The Workspace API

### Filesystem Interface

The `workspace.fs` object mirrors the Node.js `fs/promises` API, providing methods like `readFile`, `writeFile`, `mkdir`, `readdir`, `rm`, and `grep`. All operations target the SQLite-backed VFS provided by the `@cloudflare/dofs` package, ensuring atomicity and durability. Files survive Durable Object restarts because the storage lives in the object's SQLite database rather than ephemeral memory.

### Runtime Execution

The `workspace.runtime.exec(source, options)` method serves as the single entry point for running code. Depending on the selected backend, the `source` parameter accepts either shell commands or ECMAScript modules. The method returns a handle that must be properly disposed using the `using` keyword to prevent memory leaks in long-living isolates, as documented in the stub disposal guidelines.

## Package Structure

The repository organizes functionality into tightly-coupled packages:

- **@cloudflare/dofs**: Provides the SQLite-backed virtual filesystem and sync protocol primitives
- **@cloudflare/computer-rpc**: Contains Cap'n Proto wire types and client/server helpers shared between the Durable Object and `computerd`
- **@cloudflare/computerd**: The daemon that mounts the VFS via FUSE and exposes an HTTP/WebSocket RPC server
- **@cloudflare/computer**: The high-level façade exporting `Workspace`, filesystem methods, runtime execution, and optional Git helpers
- **@cloudflare/computer-computerd-linux-x64**: Docker image providing the pre-built `computerd` binary for container deployments

## RPC and Synchronization

The **capnweb RPC contract** specified in [`docs/08_capnweb_interface.md`](https://github.com/cloudflare/computer/blob/main/docs/08_capnweb_interface.md) defines how the Durable Object and `computerd` exchange state updates, command results, and stub lifecycle events. This protocol ensures that filesystem changes in the container propagate back to the SQLite database and that execution results return correctly to the invoking worker.

## Additional Capabilities

### Git Integration

The optional `workspace.git` interface provides `isomorphic-git` glue that operates directly on the SQLite VFS without requiring a backend. This allows agents to clone, commit, and push repositories stored entirely within the Durable Object.

### Assets and Artifacts

Helper functions enable publishing workspace files to external storage. The `createAssets` function uploads to Cloudflare R2, while `createArtifact` publishes to Cloudflare Artifacts, facilitating artifact generation and distribution workflows.

### Observability

A pluggable `observer` interface emits spans for every operation, compatible with Cloudflare tracing, OpenTelemetry, or custom test recorders. This enables detailed performance monitoring and debugging across all backends.

## Implementation Examples

Creating a minimal workspace requires extending a Durable Object with the `withWorkspace` mixin and retrieving the workspace via `getWorkspace`:

```typescript
import { withWorkspace, getWorkspace } from "@cloudflare/computer";
import { DurableObject } from "cloudflare:workers";

export class Agent extends withWorkspace(
  class extends DurableObject<Env> {},
  (self) => ({ storage: self.ctx.storage })
) {}

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

    await ws.fs.writeFile("/notes.md", "- [ ] ship it\n");
    const notes = await ws.fs.readFile("/notes.md", "utf8");
    return new Response(notes);
  },
} satisfies ExportedHandler<Env>;

```

To run shell commands using the Worker-shell backend, configure the backend in the Durable Object constructor:

```typescript
import { withWorkspace, getWorkspace } from "@cloudflare/computer";
import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
import curlModules from "@cloudflare/computer/shell/curl";
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: [curlModules],
      }),
    ],
  })
) {}

```

For full Linux container execution, specify the sandbox backend when calling `exec`:

```typescript
using ws = await getWorkspace(env.Agent.get(id));
using run = await ws.runtime.exec("cat /workspace/notes.md", { backend: "sandbox" });
const { stdout } = await run.result();

```

## Summary

- The cloudflare/computer repository provides Cloudflare Computer, a platform giving Durable Objects persistent SQLite-backed filesystems and flexible execution environments.
- Three backends—**Container**, **Worker-shell**, and **Worker-JavaScript**—allow trade-offs between compatibility and performance.
- The **Workspace** API exposes standard filesystem methods and a unified `exec` interface regardless of backend choice.
- Files persist in the Durable Object's SQLite database via the `@cloudflare/dofs` package, surviving restarts without external storage.
- Cap'n Proto RPC enables synchronization between the Durable Object and containerized execution environments.
- Built-in Git integration, asset publishing, and observability hooks support complete agent workflows.

## Frequently Asked Questions

### What is the primary purpose of the cloudflare/computer repository?

The repository implements Cloudflare Computer, a preview platform that enables AI agents and workers to maintain persistent state across executions using a SQLite-backed virtual filesystem. It solves the ephemeral storage limitation of serverless environments by storing data directly in Durable Objects while supporting multiple execution backends.

### How does the cloudflare/computer repository differ from standard Durable Object storage?

Unlike standard Durable Object key-value storage, this repository provides a complete virtual filesystem interface (`fs/promises` API) and pluggable execution environments. Agents can execute shell commands or JavaScript modules against the stored files using backends that range from lightweight workers to full Linux containers, with automatic synchronization handled via Cap'n Proto.

### What are the execution backends available in cloudflare/computer?

The repository offers three backends: the **Container backend** for full Linux compatibility via FUSE and `computerd`, the **Worker-shell backend** for fast bash execution using *just-bash*, and the **Worker-JavaScript backend** for running ECMAScript modules with Node-like filesystem access. Each backend is implemented in `packages/computer/backends/` and selectable at runtime.

### How does file persistence work in cloudflare/computer?

All files are stored in the Durable Object's SQLite database through the `@cloudflare/dofs` package. The `workspace.fs` methods interact with this SQLite-backed VFS, ensuring that data survives Durable Object restarts and hibernation without requiring external databases or object storage.