How to Set Up the Cloudflare Computer Development Environment

To set up the Cloudflare Computer development environment, clone the repository, run npm install from the root to install all workspaces, then execute npm run build and npm test to verify the installation.

Cloudflare Computer is a monorepo implementing a virtual filesystem backed by a Durable Object. This guide walks you through the complete setup process based on the official source code at cloudflare/computer, including prerequisites, build steps, and how to run the end-to-end examples.

Prerequisites

Before setting up the Cloudflare Computer development environment, ensure you have:

• Node.js 22+ — Required version declared in packages/computerd/package.json
• npm — The repository uses npm workspaces exclusively; pnpm and yarn are not supported
• Linux with FUSE — Required only for running the computerd daemon end-to-end; other packages build on any platform
• Docker — Optional, used by the examples/container demonstration

Repository Structure

Cloudflare Computer consists of four publishable packages and runnable examples. Understanding this structure helps navigate the codebase during development:

Package	Purpose	Main Entry Point
@cloudflare/dofs	SQLite-backed VFS, sync primitives	packages/dofs/src/index.ts
@cloudflare/computer-rpc	Cap'n Web wire protocol between Durable Object and daemon	packages/rpc/src/interface.ts
@cloudflare/computerd	In-container daemon that mounts VFS via FUSE	packages/computerd/src/fuse/driver.ts
@cloudflare/computer	Public façade (Workspace) for workers	packages/computer/src/workspace.ts

The repository layout is documented in docs/10_project_layout.md and the high-level overview appears in README.md.

Step-by-Step Cloudflare Computer Setup

1. Clone the Repository

Start by cloning the official repository:

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

2. Install All Workspaces

Run a single npm install from the repository root. This resolves every package and creates one lockfile, avoiding the nested-lockfile problems described in COLLABORATORS.md:

npm install

3. Build the Workspace

Choose between standard build or full build with native components:

# Standard library build (fast)

npm run build

# Full build including computerd binary and Docker images (slow)

npm run build:all

The computerd binary in packages/computerd requires the full build if you plan to test FUSE mount functionality.

4. Verify Code Quality

Cloudflare Computer uses Biome for formatting and linting. These checks must pass before any commit:

npm run format
npm run check   # must exit with code 0

5. Run the Test Suite

Execute tests across all workspaces or target a specific package:

# Full test suite

npm test

# Single package

npm test --workspace @cloudflare/dofs

Platform note: Tests in packages/computerd that require real FUSE mounts are automatically skipped on non-Linux platforms. On Linux, ensure /dev/fuse exists and you have sufficient privileges; otherwise these tests skip.

Running Cloudflare Computer Examples

Container Backend Example

The examples/container directory demonstrates a complete end-to-end setup:

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

npm run dev      # starts local dev server communicating with computerd

This example spawns a sandbox container, mounts the VFS via computerd, and communicates over Cap'n Web.

Worker-Based Examples

Two additional examples run backends inside Dynamic Workers instead of full containers:

• examples/worker-shell — Shell backend
• examples/worker-javascript — JavaScript runtime backend

Both follow the same pattern: npm install then npm run dev.

Essential Files for Cloudflare Computer Development

File	Purpose
packages/computer/src/workspace.ts	Workspace façade implementation used by Workers
packages/computer/src/backend.ts	Backend interface for command vs. JavaScript runtimes
packages/dofs/src/fs	Core VFS operations (readFile, writeFile, ls, etc.)
packages/rpc/src/interface.ts	Cap'n Web RPC contract between DO and computerd
packages/computerd/src/fuse/driver.ts	FUSE driver exposing VFS to host filesystem
docs/01_vfs.md	Virtual filesystem design specification
docs/08_capnweb_interface.md	Detailed RPC contract for cross-process modifications
COLLABORATORS.md	Official contributor guide with conventions
README.md	High-level overview and quick-start

Troubleshooting Cloudflare Computer Setup

FUSE Tests Skipped Unexpectedly

If computerd tests skip on Linux, verify:

1. /dev/fuse device exists
2. Your user has CAP_SYS_ADMIN or membership in the fuse group
3. The fusermount binary is in your PATH

Build Failures on Non-Linux Systems

The computerd package includes native dependencies for FUSE. On macOS or Windows:

• Library code in packages/dofs, packages/rpc, and packages/computer builds normally
• Only computerd binary and container examples require Linux
• Use npm run build instead of npm run build:all to skip native components

Summary

• Clone with git clone https://github.com/cloudflare/computer.git
• Install once with npm install from the repository root
• Build with npm run build (libraries) or npm run build:all (with native components)
• Verify with npm run format, npm run check, and npm test
• Experiment using examples/container, examples/worker-shell, or examples/worker-javascript

Frequently Asked Questions

What Node.js version does Cloudflare Computer require?

Cloudflare Computer requires Node.js 22 or higher, as specified in packages/computerd/package.json. This version ensures compatibility with the native module build process and the npm workspace configuration used throughout the monorepo.

Can I develop Cloudflare Computer on macOS or Windows?

Yes, with limitations. The core packages (@cloudflare/dofs, @cloudflare/computer-rpc, @cloudflare/computer) build and test on any platform. However, the computerd daemon and FUSE-based tests require Linux. Non-Linux platforms skip these tests automatically, and you can still develop the TypeScript libraries and Web Worker backends.

Why does the repository use npm instead of pnpm or yarn?

The Cloudflare Computer repository uses npm workspaces with a single lockfile to avoid dependency resolution conflicts between packages. The COLLABORATORS.md guide specifically documents this choice to prevent the "nested-lockfile problem" that can occur when mixing package managers or installing in subdirectories.

How do I contribute code to Cloudflare Computer?

Follow the workflow in COLLABORATORS.md: format with npm run format, pass linting with npm run check, ensure npm test succeeds, and adhere to the commit conventions documented there. All changes must include passing tests and maintain the monorepo's single-lockfile structure.

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