# What Is the @cloudflare/computer Package? Architecture and Virtual Filesystem for Durable Objects

> Discover the @cloudflare/computer package. It turns Durable Objects into persistent sandboxes with a virtual filesystem, fs APIs, and pluggable runtimes for robust development.

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

---

**The `@cloudflare/computer` package serves as the central library that transforms Cloudflare Durable Objects into persistent development sandboxes by providing a durable SQLite-backed virtual filesystem, Node-style `fs` APIs, and pluggable execution backends including container, shell, and JavaScript runtimes.**

The `@cloudflare/computer` package is the core library within the `cloudflare/computer` repository that enables stateful, long-running computation inside Cloudflare's edge infrastructure. By wrapping Durable Object storage with a virtual filesystem and execution layer, this package allows developers to run commands, manage files, and execute AI agents with complete data persistence across invocations and restarts.

## Core Architecture: The Workspace Class and Virtual Filesystem

At the heart of the package is the **`Workspace`** class defined in [`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts). This class wraps a Durable Object's `ctx.storage` and exposes a Node-compatible filesystem API that persists all data to the DO's built-in SQLite database.

### SQLite-Backed Persistence

Unlike ephemeral Workers storage, the `@cloudflare/computer` virtual filesystem survives Durable Object restarts. All file operations—`readFile`, `writeFile`, `mkdir`, `readdir`, `rm`, and `grep`—write directly to the DO's durable SQLite instance, ensuring that your development environment maintains state exactly like a local filesystem.

### Node-Style API Surface

The `Workspace` exposes familiar Node.js filesystem methods that require no learning curve for JavaScript developers. According to the source in [`packages/computer/README.md`](https://github.com/cloudflare/computer/blob/main/packages/computer/README.md), you can interact with files using standard async patterns:

```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>;

```

## Execution Backends: Three Runtime Options

The package provides a **`workspace.runtime.exec`** layer capable of running commands or JavaScript modules against the same virtual filesystem. The architecture supports three interchangeable backends defined in the `backends/` directory.

### Container Backend

The **Container backend** spins up a full Linux container via the `computerd` daemon, enabling execution of real binaries like `npm` and `node`. This backend requires container infrastructure but provides the most authentic Linux environment.

### Worker-Shell Backend

For lightweight operations, the **Worker-shell backend** ([`packages/computer/src/backends/worker-shell/worker-shell.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backends/worker-shell/worker-shell.ts)) runs a Bash interpreter called `just-bash` entirely inside a Cloudflare Worker. This requires no container infrastructure and executes shell commands with minimal overhead:

```typescript
import { withWorkspace, getWorkspace } from "@cloudflare/computer";
import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
import curlModules from "@cloudflare/computer/shell/curl";

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],
      }),
    ],
  })
) {}

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

    using run = await ws.runtime.exec("curl https://example.com");
    const { stdout, exitCode } = await run.result();
    return new Response(stdout, { status: exitCode === 0 ? 200 : 500 });
  },
} satisfies ExportedHandler<Env>;

```

### Worker-JavaScript Backend

The **Worker-JavaScript backend** executes ECMAScript modules inside a dynamic Worker using the same virtual filesystem storage. This enables high-performance JavaScript execution without the overhead of containerization.

## AI-Ready Tooling and Utilities

Beyond filesystem and execution capabilities, `@cloudflare/computer` bundles high-level utilities designed specifically for AI agents. The package exports AI-SDK-ready tools including `read`, `ls`, `find`, `grep`, `write`, `edit`, and `delete`, plus optional `exec` and `publish` capabilities.

### Git Integration and R2 Mounts

The package includes a dedicated Git client (`@cloudflare/computer/git`) for repository operations, R2 read-only mounts for object storage integration, and artifact publishing workflows. These tools allow AI agents to clone repositories, modify files, commit changes, and deploy artifacts without leaving the Durable Object environment.

## Package Entry Points and RPC Architecture

The main entry point at [`packages/computer/src/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/index.ts) re-exports the `Workspace` wrapper, backend factories, and proxy classes. Notably, the actual RPC plumbing (capnweb) lives in the sibling package `@cloudflare/computer-rpc`, keeping the core package focused on filesystem semantics while delegating network communication to a dedicated dependency.

## Summary

- **`@cloudflare/computer`** transforms Cloudflare Durable Objects into persistent development sandboxes via a SQLite-backed virtual filesystem.
- The **`Workspace`** class in [`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts) provides Node-style `fs` APIs that survive DO restarts.
- Three execution backends—**Container**, **Worker-shell**, and **Worker-JavaScript**—offer flexible runtime options ranging from full Linux containers to lightweight Worker-based execution.
- Built-in utilities include AI-SDK tools, a Git client (`createGitClient`), R2 mounts, and artifact publishing capabilities.
- The package entry point ([`packages/computer/src/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/index.ts)) cleanly separates core filesystem logic from RPC concerns handled by `@cloudflare/computer-rpc`.

## Frequently Asked Questions

### How does `@cloudflare/computer` persist data across Durable Object restarts?

All filesystem operations write to the Durable Object's built-in SQLite database via `ctx.storage`. The `Workspace` class wraps this storage layer, ensuring that files created via `writeFile` or `mkdir` remain available even when the DO hibernates or restarts, as implemented in [`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts).

### Which execution backend should I choose for my application?

Choose the **Container backend** when you need real Linux binaries like `npm` or `node`. Use the **Worker-shell backend** ([`packages/computer/src/backends/worker-shell/worker-shell.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backends/worker-shell/worker-shell.ts)) for lightweight Bash scripting without container overhead. Select the **Worker-JavaScript backend** for executing ECMAScript modules at maximum performance within the Worker runtime.

### Can I use `@cloudflare/computer` without container infrastructure?

Yes. The **Worker-shell backend** runs entirely within Cloudflare Workers using the `just-bash` interpreter, requiring no `computerd` daemon or container runtime. This backend supports common shell commands and can be extended with module loaders like `curlModules` for network operations.

### How do AI agents interact with the filesystem through this package?

AI agents consume the high-level tools exported by `@cloudflare/computer`, including `read`, `write`, `edit`, `ls`, and `grep`. These tools map directly to the `Workspace` filesystem API, allowing agents to manipulate files persistently. The package also provides `createGitClient` for version control operations and R2 integration for object storage access.