What Is @cloudflare/computerd? Understanding the Cloudflare Computer Daemon

The @cloudflare/computerd package implements the computerd daemon—a FUSE-backed virtual filesystem server that exposes an HTTP/WebSocket interface enabling remote file operations and command execution for Cloudflare Computer workloads.

The @cloudflare/computerd package serves as the server-side runtime for Cloudflare Computer, bridging local filesystem resources with remote Durable Objects. It creates a virtual workspace that can be manipulated both through standard POSIX operations and through a programmatic RPC interface, making it possible to run development environments and CI pipelines that seamlessly sync with Cloudflare's edge infrastructure.

Core Architecture

The daemon performs three primary functions: virtual filesystem management, HTTP service exposure, and process execution. These capabilities are implemented across several TypeScript modules in the packages/computerd directory of the cloudflare/computer repository.

FUSE-Backed Virtual Filesystem

On startup, computerd initializes a virtual file system (VFS) backed by @platformatic/vfs (referenced as @cloudflare/dofs in the codebase). The implementation in src/fuse/driver.ts handles the low-level filesystem operations, translating between FUSE callbacks and the underlying storage provider.

The daemon supports multiple mounting strategies via the FUSE_MOUNT environment variable:

• Native FUSE: Uses the fuse-native library to create a kernel-level filesystem mount on Linux or macOS with kernel extensions installed.
• Userspace Shim: When kernel FUSE is unavailable, the shim layer in src/shim/index.ts materializes the VFS subtree onto the host filesystem and maintains bidirectional synchronization.
• No Mount: Runs entirely in-memory with no host filesystem exposure.

The mount point defaults to /workspace but is configurable through the MOUNT_POINT environment variable.

HTTP Server and RPC Surface

The createHTTPServer function defined in src/cli/computerd.ts launches an HTTP server (default port 45678) that exposes several introspection endpoints:

• GET /health – Returns service status (unprotected)
• GET /__computerd/info – Returns backend type and mount configuration
• GET /__computerd/stats – Aggregates SQLite table counts and memory usage statistics from the DOFS provider
• WS /api – WebSocket endpoint that upgrades to the capnweb RPC protocol

Through the capnweb connection, remote clients—typically Cloudflare Durable Objects—can drive filesystem operations and query workspace metadata without direct filesystem access.

Remote Execution Engine

The package includes a lightweight process runner implemented in src/exec/runner.ts. When a client initiates an exec call via the RPC channel, the runner spawns child processes with the mount point as the current working directory. Output streams (stdout, stderr) and exit codes are forwarded over the WebSocket connection, enabling remote command execution against the mounted workspace.

Configuration and Security

FUSE Backend Selection

Control the filesystem backend through the FUSE_MOUNT environment variable with options including auto, fuse, macfuse, shim, or none. The shim mode is particularly useful for CI environments or macOS systems where kernel FUSE modules are unavailable, as documented in packages/computerd/README.md.

Bearer Token Authorization

When the RPC_CLIENT_SECRET environment variable is set, all HTTP routes except /health require authorization via Bearer token, and the WebSocket upgrade request must include valid authentication headers. This protects the daemon from unauthorized access when exposed on network interfaces.

Runtime Monitoring

The /__computerd/stats endpoint provides observability into the virtual filesystem, exposing SQLite table counts from the DOFS provider and current process memory usage. This helps diagnose storage growth or memory pressure during long-running sync sessions.

Running the computerd Daemon

Start the daemon with environment variables to configure the mount point and port:

# Run with default settings (port 45678, mount /workspace)

npx -p @cloudflare/computerd computerd

# Custom configuration

PORT=45678 MOUNT_POINT=/tmp/workspace FUSE_MOUNT=shim npx -p @cloudflare/computerd computerd

Query the daemon's status via HTTP:

import fetch from "node-fetch";

const info = await fetch("http://localhost:45678/__computerd/info").then(r => r.json());
console.log(info);   
// { backend: "fuse", mountPoint: "/tmp/workspace", port: 45678 }

Connect via the capnweb RPC protocol to manipulate files and execute commands:

import { createWorkspaceClient } from "@cloudflare/computer-rpc/client";

const ws = new WebSocket("ws://localhost:45678/api");
const client = await createWorkspaceClient(ws);

// Read a file from the VFS
const data = await client.readFile("/workspace/example.txt");
console.log(data.toString());

// Execute a command in the mounted workspace
const exec = client.exec({ cmd: ["node", "--version"], cwd: "/workspace" });
exec.stdout.on("data", chunk => console.log("STDOUT:", chunk.toString()));
await exec.done();

Summary

• @cloudflare/computerd implements a server-side daemon that creates a FUSE-backed virtual filesystem using @platformatic/vfs and exposes it via HTTP/WebSocket on port 45678.
• The daemon supports multiple mount strategies including native FUSE via fuse-native and a userspace shim for environments without kernel FUSE support.
• Remote clients connect through the capnweb RPC protocol over the /api WebSocket endpoint to perform file operations and execute shell commands with the mount point as the working directory.
• Security is enforced through optional Bearer token authentication using the RPC_CLIENT_SECRET environment variable.
• Runtime metrics and health checks are available through dedicated HTTP endpoints defined in src/cli/computerd.ts.

Frequently Asked Questions

How does computerd handle filesystem operations on systems without FUSE support?

When kernel FUSE is unavailable, set FUSE_MOUNT=shim to enable the userspace shim implementation. This mode, located in src/shim/index.ts, mirrors the virtual filesystem subtree onto the host filesystem and maintains synchronization between the two layers, allowing the daemon to function in CI environments and on macOS without kernel extensions.

What authentication mechanism protects the computerd HTTP endpoints?

If the RPC_CLIENT_SECRET environment variable is configured, every HTTP route except /health requires a valid Bearer token in the Authorization header. The WebSocket upgrade request to /api also undergoes token validation before establishing the capnweb RPC connection, preventing unauthorized access to the filesystem and execution capabilities.

Which RPC protocol does computerd use for client communication?

The daemon uses capnweb, a Cap'n Proto-based RPC protocol, over a WebSocket connection at the /api endpoint. This protocol enables bidirectional communication for file operations, workspace introspection, and streaming execution results from the runner defined in src/exec/runner.ts.

How can I check if the computerd daemon is functioning correctly?

Query the GET /health endpoint for a basic status check, or use GET /__computerd/stats for detailed diagnostics including SQLite table counts from the DOFS provider and current memory usage. These endpoints are implemented in the HTTP server setup within src/cli/computerd.ts and help verify that the FUSE mount and RPC layer are operating normally.

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