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

> Learn how to contribute to the cloudflare/computer project. This guide covers issue reporting, PR submission, and security disclosures for developers.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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:
- Schema definitions: [`packages/dofs/src/schema/`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/schema/)
- Package documentation: [[`packages/dofs/README.md`](https://github.com/cloudflare/computer/blob/main/packages/dofs/README.md)](https://github.com/cloudflare/computer/blob/main/packages/dofs/README.md)

### @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:
- Core implementation: [[`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts)](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts)
- Public API documentation: [[`packages/computer/README.md`](https://github.com/cloudflare/computer/blob/main/packages/computer/README.md)](https://github.com/cloudflare/computer/blob/main/packages/computer/README.md)

### 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:
- RPC interface design: [[`docs/08_capnweb_interface.md`](https://github.com/cloudflare/computer/blob/main/docs/08_capnweb_interface.md)](https://github.com/cloudflare/computer/blob/main/docs/08_capnweb_interface.md)
- Sync semantics: [[`docs/02_sync_protocol.md`](https://github.com/cloudflare/computer/blob/main/docs/02_sync_protocol.md)](https://github.com/cloudflare/computer/blob/main/docs/02_sync_protocol.md)
- RPC implementation: [`packages/rpc/src/`](https://github.com/cloudflare/computer/blob/main/packages/rpc/src/)

### 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:
- FUSE driver implementation: [`packages/computerd/src/fuse/`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/)
- Daemon documentation: [[`packages/computerd/README.md`](https://github.com/cloudflare/computer/blob/main/packages/computerd/README.md)](https://github.com/cloudflare/computer/blob/main/packages/computerd/README.md)

## 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)](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)](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](https://www.cloudflare.com/.well-known/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:

```typescript
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)](https://github.com/cloudflare/computer/blob/main/docs/01_vfs.md).

## Key Files and Directories

Reference these paths when navigating the codebase:

- [[`CONTRIBUTING.md`](https://github.com/cloudflare/computer/blob/main/CONTRIBUTING.md)](https://github.com/cloudflare/computer/blob/main/CONTRIBUTING.md) – Contribution policy and workflow requirements.
- [[`COLLABORATORS.md`](https://github.com/cloudflare/computer/blob/main/COLLABORATORS.md)](https://github.com/cloudflare/computer/blob/main/COLLABORATORS.md) – Setup instructions, linting rules, and commit conventions for approved contributors.
- [`packages/dofs/src/schema/`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/schema/) – SQLite schema definitions for nodes, mounts, and error codes.
- [[`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts)](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts) – Core `Workspace` class implementation.
- [`packages/rpc/src/`](https://github.com/cloudflare/computer/blob/main/packages/rpc/src/) – Cap'n Proto RPC client and server implementations.
- [`packages/computerd/src/fuse/`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/) – FUSE filesystem driver for container-side mounting.
- [[`examples/worker-shell/src/index.ts`](https://github.com/cloudflare/computer/blob/main/examples/worker-shell/src/index.ts)](https://github.com/cloudflare/computer/blob/main/examples/worker-shell/src/index.ts) – Minimal Worker example demonstrating API usage.
- [[`docs/01_vfs.md`](https://github.com/cloudflare/computer/blob/main/docs/01_vfs.md)](https://github.com/cloudflare/computer/blob/main/docs/01_vfs.md) – Virtual File System architecture and node types.
- [[`docs/02_sync_protocol.md`](https://github.com/cloudflare/computer/blob/main/docs/02_sync_protocol.md)](https://github.com/cloudflare/computer/blob/main/docs/02_sync_protocol.md) – Sync protocol semantics and consistency guarantees.

## 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`](https://github.com/cloudflare/computer/blob/main/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](https://www.cloudflare.com/.well-known/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/`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/schema/). This schema powers the VFS accessed through the `Workspace` API.