how-to-guide

How to Contribute to the Cloudflare Computer Project: A Complete Developer Guide

August 9, 2026 cloudflare/computer ↗

Contribute to the cloudflare/computer project by opening public issues for bugs or discussions for features, waiting for explicit maintainer invitation before submitting pull requests, and following Cloudflare's security disclosure process for vulnerabilities.

The cloudflare/computer repository is an open-source monorepo that implements a virtual filesystem (VFS) runtime for Cloudflare Containers. Before you contribute to the cloudflare/computer project, you must understand its distributed architecture spanning Durable Objects, Cap'n Proto RPC, and container-side daemons.

Understand the Cloudflare Computer Architecture

The repository is organized into several interconnected packages. Grasping these boundaries ensures your contributions target the correct layer.

@cloudflare/dofs: The SQLite Storage Layer

The dofs package provides the persistent storage backend for the VFS. It defines the SQLite schema that stores files, directories, and metadata nodes. All filesystem operations ultimately resolve to queries against this schema.

Key paths:

@cloudflare/computer: The Public API and Workspace

The computer package exposes the primary developer interface through the Workspace class. This class provides methods like runtime.exec() for command execution and fs helpers for file operations. It manages the lifecycle of the VFS and coordinates with backends such as CloudflareContainerBackend.

Key paths:

Cap'n Proto RPC and the Sync Protocol

Communication between the Durable Object (host side) and the container-side daemon uses Cap'n Proto serialization. The rpc package implements the message contracts, while the sync protocol guarantees eventual consistency between the DO-side VFS and the container's view after each execution.

Key documentation:

computerd: The In-Container Daemon

The computerd package contains the daemon that runs inside Cloudflare Containers. It mounts the VFS via FUSE (or a compatibility shim) at /workspace, executes commands issued through runtime.exec(), and pushes/pulls changes to maintain synchronization.

Key paths:

The Contribution Workflow for cloudflare/computer

The project maintains a strict, maintainer-driven workflow defined in [CONTRIBUTING.md](https://github.com/cloudflare/computer/blob/main/CONTRIBUTING.md).

Step 1: Open an Issue or Discussion

All contributions start in public channels. File a GitHub Issue for bugs or start a Discussion for feature ideas. Unsolicited pull requests are not accepted and will be closed immediately.

Step 2: Wait for Maintainer Invitation

Submit code only after a maintainer explicitly requests a patch. This prevents wasted effort on designs that conflict with the project's roadmap.

Step 3: Development and Testing

Once invited, follow the collaborator guidelines in [COLLABORATORS.md](https://github.com/cloudflare/computer/blob/main/COLLABORATORS.md):

  1. Fork the repository and create a feature branch from main.
  2. Run the workspace-wide build: npm run build.
  3. Modify code only within the relevant package (e.g., packages/computer, packages/dofs, or packages/rpc).
  4. Add or update unit tests in the same package.
  5. Execute tests: npm test --workspace <package-name>.
  6. Write commit messages using the imperative mood and scoped prefixes (e.g., fix(computer): handle null workspace id).

Security Disclosure Process

Never report security vulnerabilities through public issues. Follow the process documented at Cloudflare's security.txt or email the security team directly.

Practical Code Example: Initializing a Workspace

The following TypeScript example demonstrates the standard pattern for creating a Workspace instance and reading a file from the VFS:

import { Workspace } from '@cloudflare/computer';
import { CloudflareContainerBackend } from '@cloudflare/computer/backends/container';

// Initialize workspace with Durable Object storage and container backend
const ws = new Workspace({
  storage: ctx.storage,                     // Durable Object storage handle
  backends: [
    new CloudflareContainerBackend({
      container: () => this,                // Container-side interface
      workspace: { binding: 'MyApp', id: ctx.id.toString() },
    }),
  ],
  useThink: true,                           // Enable Think runtime helpers
});

// Read a text file from the mounted VFS
async function readProjectConfig() {
  const data = await ws.fs.readFile('/workspace/config.json', 'utf8');
  return JSON.parse(data);
}

readProjectConfig().catch(console.error);

This pattern aligns with the VFS layout described in [docs/01_vfs.md](https://github.com/cloudflare/computer/blob/main/docs/01_vfs.md).

Key Files and Directories

Reference these paths when navigating the codebase:

Summary

  • The cloudflare/computer monorepo consists of four main components: the dofs storage layer, the computer API, the rpc messaging layer, and the computerd container daemon.
  • Contributions must start as GitHub Issues or Discussions; pull requests are only accepted after maintainer invitation.
  • Development requires running npm run build and npm test --workspace <package> to validate changes.
  • Security vulnerabilities must be reported through Cloudflare's private security channel, never through public issues.
  • The Workspace class in packages/computer/src/workspace.ts serves as the primary entry point for filesystem operations.

Frequently Asked Questions

Can I submit a pull request directly to cloudflare/computer without opening an issue first?

No. The project only accepts pull requests after a maintainer explicitly requests a patch. Unsolicited PRs will be closed immediately and redirected to an issue or discussion thread to align with the project's design goals.

How do I report a security vulnerability in the cloudflare/computer project?

Do not use public GitHub issues for security reports. Follow the instructions at Cloudflare's security.txt to disclose vulnerabilities privately to the security team.

What testing commands should I run before submitting a contribution?

Execute npm run build to compile the entire workspace, then run npm test --workspace <package-name> (replacing <package-name> with computer, dofs, rpc, or computerd) to ensure your changes pass the package-specific test suite.

Where is the Virtual File System schema defined in the source code?

The SQLite schema defining nodes, directory entries, and mount points resides in packages/dofs/src/schema/. This schema powers the VFS accessed through the Workspace API.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →