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

> Learn to set up R2-backed read-only mounts in Cloudflare Computer using the R2Bucket mount factory. Mount an R2 bucket as a read-only VFS path with lazy loading for efficient object access.

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

---

**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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/packages/computer/README.md) (lines 191-196), demonstrates a typical configuration:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/examples/container/README.md) (lines 88-91) illustrates this approach:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/docs/06_mount_interface.md), [`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts), and [`examples/container/README.md`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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.