Build Requirements for cloudflare/computer: Node.js 22, FUSE, and Native Toolchain

To build the cloudflare/computer monorepo, you need Node.js 22, npm for workspace management, a Linux host with FUSE support, and the C toolchain including libfuse-dev headers; optional Docker is required only for the container examples.

Cloudflare Computer is a monorepo containing inter-dependent packages that require specific system-level dependencies beyond standard Node.js tooling. Understanding the build requirements for cloudflare/computer ensures you can compile the TypeScript libraries, build the native computerd daemon, and run the containerized examples without encountering runtime errors.

Core Runtime Requirements

Node.js Version 22

The repository requires Node.js 22 or later, as declared in packages/computerd/package.json. This version requirement ensures compatibility with the modern JavaScript features used across the npm workspaces. Older Node versions will fail during the dependency installation phase or when executing the build scripts.

npm Workspaces

Unlike repositories that use pnpm or yarn, cloudflare/computer relies strictly on npm for workspace management. The monorepo structure is defined using npm workspaces, which resolves all inter-package dependencies in a single pass when you run npm install from the root directory.

System-Level Build Dependencies

Linux and FUSE Kernel Module

The computerd daemon—located in packages/computerd—implements a FUSE-backed virtual filesystem backend. Consequently, you must build on a Linux host with the FUSE kernel module present. The daemon mounts virtual filesystems via FUSE, making this a hard requirement for the backend functionality, not merely a runtime preference.

C Toolchain and libfuse Headers

Because packages/computerd depends on the native addon fuse-native, you need a complete C build environment. Install gcc or clang along with the libfuse2 development files. On Debian or Ubuntu systems, this means installing build-essential and libfuse-dev.

# Debian/Ubuntu example

sudo apt-get update
sudo apt-get install -y build-essential libfuse-dev

These headers allow node-gyp to compile the native bindings during npm install.

Platform-Specific Build Instructions

Arm64 Workaround for fuse-native

The pre-built fuse-native library bundled with the repository ships only for x64 architectures. If you are building on an arm64 host, you must manually replace the bundled library with your system's version and trigger a rebuild.

Execute these commands before running the main build:

# Replace bundled libfuse with system library

sudo cp /usr/lib/aarch64-linux-gnu/libfuse.so.2 \
    node_modules/fuse-shared-library-linux/libfuse/lib/libfuse.so

# Rebuild the native addon

cd node_modules/fuse-native && npx node-gyp rebuild

This workaround is documented in AGENTS.md and is essential for successful compilation on ARM-based Linux machines.

Optional Docker Support

Docker is not required for the core library build, but you need it to run the examples/container demo. This example launches computerd inside a container environment and communicates with Durable Objects via capnweb. Install Docker only if you intend to test the containerized backend workflow.

Build Commands and Workflow

After installing system dependencies, follow this sequence to build the repository. First, clone and install npm dependencies:

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

Then execute the appropriate build script based on your target output:

• npm run build: Compiles all TypeScript packages to their respective dist/ folders and runs type checking across workspaces.
• npm run build:all: Runs the full pipeline including build, build:bin (compiles the computerd daemon binary for linux-x64), and build:docker (creates the container image).

For development workflows, you can also run:

npm run typecheck    # Runs tsc --noEmit across all workspaces

npm run format       # Formats the codebase

npm run check        # Runs linting checks

Key Configuration Files

Several documentation files in the repository root define these requirements:

• COLLABORATORS.md: Specifies the core runtime requirements including Node.js 22, npm, Linux+FUSE, and optional Docker.
• AGENTS.md: Details the native build toolchain, libfuse header requirements, and the arm64 workaround procedures.
• packages/computerd/README.md: Describes the daemon architecture and its native dependency on fuse-native.
• packages/computer/README.md: Serves as the entry point for the top-level @cloudflare/computer package, explaining how backends are constructed.

Summary

• Node.js 22 is the minimum required runtime, specified in packages/computerd/package.json.
• You must use npm (not pnpm or yarn) to resolve the monorepo workspaces.
• Linux with FUSE support is mandatory for building the computerd daemon.
• Install build-essential and libfuse-dev to compile the fuse-native addon.
• On arm64 architectures, manually replace the bundled x64 libfuse library with your system's version and run npx node-gyp rebuild.
• Docker is optional and only needed for the examples/container demonstration.
• Use npm run build for libraries or npm run build:all to include the binary and Docker image.

Frequently Asked Questions

Do I need Linux to build cloudflare/computer?

Yes. Because the computerd daemon relies on FUSE (Filesystem in Userspace) to mount virtual filesystems, you must build on a Linux host with the FUSE kernel module available. The native addon fuse-native requires Linux-specific headers and cannot compile on macOS or Windows without a Linux container or VM.

Can I use pnpm or yarn instead of npm?

No. The repository is configured specifically for npm workspaces. While the code itself might work with other package managers, the build scripts and workspace resolution in package.json are designed around npm's workspace implementation. Using pnpm or yarn may result in incorrect dependency linking or failed builds.

How do I fix build errors on an ARM64 machine?

If you encounter errors about missing or incompatible binaries on arm64, you need to replace the pre-built x64 libfuse library bundled in node_modules/fuse-shared-library-linux with your system's arm64 version. Copy /usr/lib/aarch64-linux-gnu/libfuse.so.2 to the bundle location, then navigate to node_modules/fuse-native and run npx node-gyp rebuild to compile the native addon for your architecture.

What is the difference between npm run build and npm run build:all?

npm run build compiles the TypeScript source files across all packages to their dist/ directories and performs type checking. npm run build:all extends this by also running build:bin (which compiles the computerd daemon binary for linux-x64) and build:docker (which constructs the Docker image). Use build:all only when you need the container backend or standalone binary.

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