How to Install cloudflare/computer: A Complete Setup Guide

You can install the core package with npm install @cloudflare/computer, enable the nodejs_compat compatibility flag in your Wrangler configuration, and optionally configure execution backends like worker-shell to enable command execution within your Durable Objects.

The cloudflare/computer repository provides a persistent, SQLite-backed virtual filesystem for Cloudflare Durable Objects, enabling file operations and pluggable execution backends directly at the edge. Installing this package allows you to add POSIX-like filesystem capabilities to your Workers with minimal configuration. This guide covers how to install cloudflare/computer and configure it for production use according to the source code in packages/computer/README.md.

Prerequisites

Before installing, ensure you have a Cloudflare Workers project initialized with Wrangler and Node.js 18+ installed locally. The package is distributed via npm and integrates directly with the Cloudflare Workers runtime.

Step 1: Install the Core Package

The main entry point is the @cloudflare/computer npm package. Install it as a dependency in your Worker project:

npm install @cloudflare/computer

This command installs the core Workspace API, the withWorkspace mixin, and filesystem bindings documented in packages/computer/README.md. The package is designed to work within the Durable Objects lifecycle, persisting files to SQLite storage automatically.

Step 2: Enable Compatibility Flags

Workers using the filesystem API require the nodejs_compat compatibility flag to access Node.js polyfills. Add it to your wrangler.jsonc configuration:

{
  "compatibility_flags": ["nodejs_compat"]
}

According to the source code in packages/computer/package.json, this flag is mandatory for filesystem operations to function correctly, as the package relies on Node.js stream and buffer APIs.

Step 3: Configure an Execution Backend (Optional)

To run shell commands or execute JavaScript modules, you must add an execution backend. The worker-shell backend requires no container infrastructure and is the easiest to start with.

Import the Worker-Shell Backend

Add the backend to your Durable Object mixin by importing from @cloudflare/computer/backends/worker-shell:

import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";

// Inside your Durable Object mixin
new WorkerShellBackend({
  loader: self.env.LOADER,
  workspace: { binding: "Agent", id: self.ctx.id.toString() },
  ctx: self.ctx,
  commands: [],               // add optional command groups such as `curl`, `python`, etc.
})

Add Required Loader Configuration

The worker-shell backend requires the experimental compatibility flag and a worker loader binding. Update your wrangler.jsonc:

{
  "compatibility_flags": ["nodejs_compat", "experimental"],
  "worker_loaders": [{ "binding": "LOADER" }]
}

As implemented in the repository and documented in docs/12_worker_backend.md, the loader binding enables dynamic module loading required by the execution backends to resolve command binaries.

Step 4: Install Optional Peer Dependencies

If you plan to use AI tooling, Git integration, or the Node-side VFS provider, install the corresponding optional packages listed in packages/computer/package.json:

npm install ai zod @platformatic/vfs

These packages are marked as optional peer dependencies in the package manifest. They are only required if you intend to use the createAITools function from @cloudflare/computer/tools or the Git-backed workspace features.

Step 5: Build the Workspace

After adding the package, run a workspace build to generate TypeScript declarations and any native add-ons required by sibling packages:

npm run build

This step ensures all internal packages in the monorepo are properly compiled, as noted in the repository's top-level README.md. The build process generates the type definitions referenced by withWorkspace and getWorkspace.

Usage Examples

Once installed, you can implement filesystem operations and command execution in your Durable Objects.

Basic Filesystem Setup

Create a Durable Object with workspace capabilities using the withWorkspace mixin:

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): Promise<Response> {
    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>;

Running Shell Commands

Add command execution by configuring the worker-shell backend in your Durable Object:

import { withWorkspace, getWorkspace } from "@cloudflare/computer";
import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
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: [],               // e.g. add `curl` group here
      }),
    ],
  })
) {}

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

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

AI Tools Integration

For AI-powered operations, import the tools bundle from @cloudflare/computer/tools:

import { createAITools } from "@cloudflare/computer/tools";

const tools = createAITools({
  workspace,
  read: { maxBytes: 32 * 1024, maxLines: 800 },
  shell: {
    defaultBackend: "shell",
    backends: {
      shell: { description: "Fast Worker shell." },
      container: { description: "Full Linux container." },
    },
  },
});

Summary

• Install the core package using npm install @cloudflare/computer to add filesystem capabilities to Durable Objects via the withWorkspace mixin.
• Enable nodejs_compat in your Wrangler configuration to activate the required Node.js compatibility layer for filesystem operations.
• Add execution backends like WorkerShellBackend by importing from @cloudflare/computer/backends/worker-shell and configuring the LOADER binding with the experimental flag.
• Install optional dependencies (ai, zod, @platformatic/vfs) only if you need AI tooling or Git integration features documented in packages/computer/README.md.
• Build the workspace after installation to ensure TypeScript declarations and native add-ons are properly generated across the monorepo.

Frequently Asked Questions

Do I need to install a container runtime to use cloudflare/computer?

No. While the repository supports container-based execution via the computerd daemon documented in packages/computerd/README.md, you can use the worker-shell backend entirely within the Workers runtime without any container infrastructure. The worker-shell backend runs directly in the V8 isolate.

What is the minimum compatibility date required for cloudflare/computer?

You must enable the nodejs_compat compatibility flag in your wrangler.jsonc. If using execution backends, you also need the experimental flag. The package relies on Node.js APIs for filesystem operations as implemented in packages/dofs, which provides the SQLite-backed virtual filesystem layer.

Can I use cloudflare/computer without execution backends?

Yes. The core @cloudflare/computer package provides a SQLite-backed virtual filesystem accessible via workspace.fs without any backend configuration. Execution backends are only required if you need to run shell commands or JavaScript modules via workspace.runtime.exec.

Where are the workspace files actually stored?

Files are persisted in SQLite databases backed by Durable Object storage, as detailed in packages/dofs/README.md. The withWorkspace mixin automatically handles storage binding and persistence across Durable Object invocations, storing data in the self.ctx.storage object provided to the mixin factory function.

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