# How to Install cloudflare/computer: A Complete Setup Guide

> Install cloudflare/computer with npm and configure Wrangler for command execution. Follow our complete setup guide to get started.

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

---

**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`](https://github.com/cloudflare/computer/blob/main/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:

```bash
npm install @cloudflare/computer

```

This command installs the core Workspace API, the `withWorkspace` mixin, and filesystem bindings documented in [`packages/computer/README.md`](https://github.com/cloudflare/computer/blob/main/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:

```jsonc
{
  "compatibility_flags": ["nodejs_compat"]
}

```

According to the source code in [`packages/computer/package.json`](https://github.com/cloudflare/computer/blob/main/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`:

```ts
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`:

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

```

As implemented in the repository and documented in [`docs/12_worker_backend.md`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/packages/computer/package.json):

```bash
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:

```bash
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`](https://github.com/cloudflare/computer/blob/main/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:

```ts
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:

```ts
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`:

```ts
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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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.