How to Set Up the Cloudflare Computer Project Locally: A Complete Guide

Clone the repository, run npm install from the root to resolve all workspace packages, then execute npm run build to compile the TypeScript libraries and npm test to verify the installation.

Cloudflare Computer provides a virtual filesystem hosted inside a Durable Object, storing authoritative state in SQLite and exposing three execution back-ends via workspace.runtime.exec. Setting up the cloudflare/computer project locally requires Node.js 22+, a Linux host with FUSE support for the Container back-end, and Docker if you plan to run containerized examples.

Prerequisites for Local Development

Before cloning the repository, ensure your environment meets the baseline requirements specified in COLLABORATORS.md. You need Node.js 22 or newer, npm, and a Linux host with FUSE support if you intend to use the Container back-end. Docker is required only if you plan to run the containerized computerd daemon example.

The architecture consists of four core packages:

• packages/dofs – SQLite-backed virtual filesystem and sync protocol
• packages/rpc – capnweb wire types and shared RPC helpers
• packages/computerd – FUSE-mount daemon and HTTP/WebSocket RPC server
• packages/computer – Public @cloudflare/computer package consumed by Durable Objects

Install and Build the Workspace

Unlike multi-repo setups, cloudflare/computer uses a single root installation to prevent nested lockfiles. Navigate to the repository root and install all dependencies with one command:

git clone https://github.com/cloudflare/computer.git
cd computer
npm install

This resolves dependencies for all workspace packages simultaneously. After installation, build the libraries using:

npm run build

If you need the pre-built computerd binary or Docker images for the Container back-end, use npm run build:all instead. This command compiles the TypeScript sources and prepares the sandbox container environment.

Code Quality Checks and Testing

The repository enforces code quality through Biome. Before committing changes, run the formatting and linting commands referenced in COLLABORATORS.md:

npm run format
npm run check

These ensure the codebase passes the project's strict style rules. To verify functionality, execute the full workspace test suite:

npm test

For targeted testing of specific packages—such as the virtual filesystem layer—use the workspace flag:

npm test --workspace @cloudflare/dofs

This runs only the tests associated with that specific package.

Running the Container Back-End

The Container back-end requires additional setup compared to the Isolate variants. This back-end runs the computerd daemon inside a sandbox container, mounting the SQLite state as a real FUSE filesystem and syncing changes over a capnweb RPC channel.

To experiment with this execution mode:

cd examples/container
npm install  # Install example-specific dependencies

npm start    # Launches computerd in a container and serves the HTTP API

The computerd daemon communicates with the Durable Object using the capnweb interface specified in docs/08_capnweb_interface.md. Understanding this RPC contract is essential when debugging cross-process communication between the workspace and the container.

Three Execution Back-Ends

Once set up locally, the project exposes three distinct runtime back-ends via workspace.runtime.exec:

Container – Runs the computerd daemon in a sandbox container with FUSE filesystem access, suitable for complex workloads requiring full POSIX compatibility.

Isolate shell – Executes the just-bash shell inside a Dynamic Worker, communicating directly with the Durable Object without container overhead.

Isolate JavaScript – Runs ECMAScript modules in a Dynamic Worker, providing a node:fs/promises-compatible API backed by the workspace's virtual filesystem.

You can invoke the Container back-end from a Durable Object as follows:

import { Workspace } from '@cloudflare/computer';

async function demo(workspace: Workspace) {
  // Execute a shell command inside the container back-end
  const result = await workspace.runtime.exec('echo Hello', {
    backend: 'container',
  });
  console.log(result.stdout); // → Hello
}

Summary

• Prerequisites: Node.js 22+, npm, Linux with FUSE (for Container), and Docker (for examples).
• Installation: Single npm install at the repository root prevents nested lockfiles across the four workspace packages.
• Build: Use npm run build for libraries or npm run build:all for the computerd binary and Docker images.
• Quality: Run npm run format and npm run check to satisfy Biome linting rules.
• Testing: Execute npm test for the full suite or target specific packages with --workspace flags.
• Architecture: The project comprises dofs, rpc, computerd, and computer packages, implementing the capnweb RPC protocol detailed in docs/08_capnweb_interface.md.

Frequently Asked Questions

What Node.js version is required for cloudflare/computer?

The project requires Node.js 22 or newer, as specified in the Setup section of COLLABORATORS.md. Earlier versions may fail during the build process due to modern JavaScript features used in the workspace packages.

Do I need Docker to run the project locally?

Docker is only required if you intend to use the Container back-end or run the containerized examples. The Isolate shell and Isolate JavaScript back-ends function without Docker, communicating directly with the Durable Object through Dynamic Workers.

How do I run tests for a specific package only?

Use the workspace flag with npm test: npm test --workspace @cloudflare/dofs runs only the tests for the virtual filesystem package. This targets the specific test suite without executing the full workspace validation, saving time during development.

Where is the RPC protocol between the Durable Object and computerd documented?

The capnweb RPC interface specification resides in docs/08_capnweb_interface.md. This document details the wire format and contract used for syncing SQLite state between the Durable Object and the computerd daemon, essential for understanding the Container back-end's communication layer.

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