How to Set Up R2-Backed Read-Only Mounts in Cloudflare Computer

To configure an R2-backed read-only mount in Cloudflare Computer, use the R2Bucket mount factory in your Workspace configuration, mapping an absolute VFS path to your R2 bucket binding; mounts default to read-only mode and utilize lazy loading to fetch objects on first access.

Cloudflare Computer enables direct integration with Cloudflare R2 object storage through its virtual filesystem interface. By leveraging the R2Bucket mount factory implemented in packages/computer/src/workspace.ts, you can expose bucket contents as read-only filesystem paths that stream data on demand. This architecture is ideal for serving static assets, machine learning models, and pre-computed datasets without write-back overhead.

Understanding the R2Bucket Mount Interface

The R2Bucket factory follows the mount interface specification defined in docs/06_mount_interface.md (lines 41-53). It accepts a binding and an optional configuration object, returning a mount factory that the Workspace class consumes during initialization.

According to the Cloudflare Computer source code, R2Bucket implements a lazy mount strategy. During workspace setup, the mount's list() method enumerates the bucket contents once to insert stub nodes into the VFS without downloading actual data. When a file is first accessed, the fetch(relPath) method retrieves the specific object from R2 and streams it into the filesystem (lines 141-156). This design ensures that large buckets do not consume memory until files are explicitly read.

Configuring Read-Only Permissions and Options

By default, R2Bucket mounts operate in read-only mode unless you explicitly specify mode: "read-write". Any write operation attempted on a read-only mount results in an EROFS (read-only filesystem) error, as documented in docs/06_mount_interface.md (lines 103-108).

You can customize mount behavior using these options (lines 107-118):

• prefix: Strips a leading prefix from R2 object keys when computing relative paths within the mount.
• ignore: Excludes specific path segments or patterns from appearing in both the Durable Object environment and the workspace view.
• maxBytes and maxEntries: Enforce hard caps on total size and object count during the indexing phase to prevent resource exhaustion.

Implementing R2 Mounts in Your Application

To mount an R2 bucket, import the R2Bucket factory from @cloudflare/computer and include it in the mounts map of your Workspace constructor. The following example, based on packages/computer/README.md (lines 191-196), demonstrates a typical configuration:

import { Workspace, R2Bucket } from "@cloudflare/computer";

const ws = new Workspace({
  mounts: {
    "/workspace/r2": R2Bucket(env.Bucket, {
      prefix: "public/",
      ignore: [".cache", ".tmp"],
      maxBytes: 1 << 30, // 1 GiB limit
    }),
  },
  ignore: ["node_modules", ".git"],
});

Durable Object Integration

In Durable Object environments, access the R2 binding through the environment object and construct the workspace within your fetch handler. The pattern shown in examples/container/README.md (lines 88-91) illustrates this approach:

export class MyDO extends DurableObject {
  async fetch(request: Request) {
    const { Bucket } = this.env;
    
    const ws = new Workspace({
      mounts: {
        "/workspace/r2": R2Bucket(Bucket), // Defaults to read-only
      },
    });

    const file = await ws.fs.readFile("/workspace/r2/example.txt", "utf8");
    return new Response(file);
  }
}

Summary

• Configure R2-backed mounts using R2Bucket(binding, options?) in the Workspace constructor's mounts map.
• Mounts default to read-only mode and throw EROFS on write attempts unless explicitly configured with mode: "read-write".
• The lazy loading mechanism uses list() for indexing and fetch(relPath) for on-demand retrieval, minimizing memory usage for large buckets.
• Control resource exposure and limits through prefix, ignore, maxBytes, and maxEntries options.
• Implementation details are found in docs/06_mount_interface.md, packages/computer/src/workspace.ts, and examples/container/README.md.

Frequently Asked Questions

What is the default access mode for R2 mounts in Cloudflare Computer?

R2 mounts default to read-only mode. Unless you explicitly set mode: "read-write" in the mount options, any attempt to write to the mounted path will throw an EROFS (read-only filesystem) error. This safety mechanism is documented in docs/06_mount_interface.md (lines 103-108).

How does R2Bucket handle buckets containing thousands of objects?

R2Bucket employs a lazy mounting strategy where the list() method only inserts lightweight stub nodes into the virtual filesystem during initialization. The actual fetch(relPath) operation occurs only when a specific file is first read, ensuring efficient memory usage regardless of bucket size. This behavior is defined in docs/06_mount_interface.md (lines 141-156).

Can I mount multiple R2 buckets in a single Workspace?

Yes. The mounts configuration accepts multiple entries mapping different absolute VFS paths to distinct R2Bucket instances. You can mount separate buckets or the same bucket with different prefix configurations at paths like /workspace/models and /workspace/data, each with independent ignore patterns and quota limits.

What happens if I try to write to a read-only R2 mount?

Any write operation—including creating files, modifying contents, or deleting objects—will fail with an EROFS error. The mount explicitly forbids modifications to protect your R2 data integrity. To enable write operations, you must explicitly configure the mount with mode: "read-write", though this changes consistency guarantees and performance characteristics.

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