> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare R2

> Virtualize a Cloudflare R2 bucket from Node or the browser.

`R2VFS` mounts one Cloudflare R2 bucket: every object becomes a file and every
`/` in a key a folder. It reaches R2 through its S3-compatible API at
`https://<accountId>.r2.cloudflarestorage.com`. Set up credentials as in [R2 setup](https://docs.mirage.strukto.ai/home/setup/r2.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { MountMode, R2VFS, Workspace } from '@struktoai/mirage-node'

const r2 = new R2VFS({
  bucket: process.env.R2_BUCKET!,
  accountId: process.env.R2_ACCOUNT_ID!,
  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
})
const ws = new Workspace({ '/r2': r2 }, { mode: MountMode.WRITE })

const result = await ws.shell("ls /r2 && find /r2 -name '*.csv'")
console.log(result.stdoutText)
await ws.close()
```

A bucket in a jurisdiction has its own endpoint, such as
`https://<accountId>.eu.r2.cloudflarestorage.com`; set `endpoint` to it. A mount
takes `MountMode.READ`, `WRITE` or `EXEC`.

### Fields

**bucket** `string` *required*

Name of the bucket to mount.

**accessKeyId** `string`

Access key ID; set it with `secretAccessKey`. Unset uses the AWS SDK credential chain.

**secretAccessKey** `string`

Secret access key paired with `accessKeyId`.

**sessionToken** `string`

Session token for temporary credentials, sent with the access key pair.

**profile** `string`

Named profile in the shared AWS config and credentials files that supplies credentials when no access key pair is given.

**forcePathStyle** `boolean`

Address the bucket in the URL path (`<endpoint>/<bucket>/<key>`) instead of as a subdomain of the endpoint.

**keyPrefix** `string`

Key prefix inside the bucket that the mount treats as its root; keys outside it are not visible. Leading slashes are dropped and a trailing `/` is added.

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

**proxy** `string`

Proxy URL for every HTTP and HTTPS request to the endpoint.

**region** `string` (default: 'auto')

Region requests are signed for; R2 addresses a bucket by account, not by region.

**endpoint** `string`

Endpoint URL that replaces the one the provider derives.

**accountId** `string`

Cloudflare account ID. It builds the endpoint `https://<accountId>.r2.cloudflarestorage.com` unless `endpoint` is set; one of the two is required.

Fields marked secret are redacted in snapshots.

## Authentication

Credentials come from `accessKeyId` and `secretAccessKey`, an R2 API token's key
pair, with `sessionToken` for temporary credentials. Without them, the AWS SDK
reads its own chain: environment variables, `~/.aws/credentials`, then the
instance or container role.

The token needs **Object Read only** on the bucket, or **Object Read & Write**
to write. A request the credentials may not make answers `Permission denied`.

## Layout

```text theme={null}
/r2/
  data/
    config.json
    file.txt
  reports/
    q1.csv
    q2.csv
```

`/r2/data/file.txt` is the key `data/file.txt`. Folders come from the `/` in
keys; R2 stores no folder objects.

## Behavior

* **Key prefix:** `keyPrefix: 'users/42/'` mounts only that part of the bucket,
  so `/r2/notes.md` is the key `users/42/notes.md`.

## Browser

The browser `R2VFS` from `@struktoai/mirage-browser` keeps credentials off the
page: a server signs a URL for each S3 call with the R2 keys, and the browser
fetches it.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { MountMode, R2VFS, Workspace } from '@struktoai/mirage-browser'

const r2 = new R2VFS({
  bucket: 'my-bucket',
  presignedUrlProvider: async (path, op, opts) => {
    const r = await fetch('/presign', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ path, op, opts }),
    })
    return ((await r.json()) as { url: string }).url
  },
})
const ws = new Workspace({ '/r2': r2 }, { mode: MountMode.READ })
```

* The bucket's CORS rules must allow the page's origin, exactly as served.
* A browser mount cannot declare `write: conditional`, and any HTTP 403 from a
  signed URL, an expired one included, answers `Permission denied`.
* `keyPrefix` set in the browser is no security boundary: enforce the prefix in
  the signing server.
* `accountId` and `endpoint` only name the mount's storage location: requests go
  to the host each signed URL names.

> [accordion] Signing server
>
> An Express route that signs URLs:
>
> ```ts theme={null}
> import {
>   CopyObjectCommand,
>   DeleteObjectCommand,
>   GetObjectCommand,
>   HeadObjectCommand,
>   ListObjectsV2Command,
>   PutObjectCommand,
>   S3Client,
> } from '@aws-sdk/client-s3'
> import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
>
> const client = new S3Client({
>   region: 'auto',
>   endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
>   credentials: {
>     accessKeyId: process.env.R2_ACCESS_KEY_ID!,
>     secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
>   },
> })
> const BUCKET = process.env.R2_BUCKET!
>
> app.post('/presign', async (req, res) => {
>   const { path, op, opts } = req.body as {
>     path: string
>     op: 'GET' | 'PUT' | 'HEAD' | 'DELETE' | 'LIST' | 'COPY'
>     opts?: Record<string, unknown>
>   }
>   const key = path.replace(/^\/+/, '')
>   const ttl = typeof opts?.ttlSec === 'number' ? opts.ttlSec : 300
>   let cmd
>   switch (op) {
>     case 'GET':    cmd = new GetObjectCommand({ Bucket: BUCKET, Key: key }); break
>     case 'PUT':    cmd = new PutObjectCommand({ Bucket: BUCKET, Key: key, ContentType: opts?.contentType as string | undefined }); break
>     case 'HEAD':   cmd = new HeadObjectCommand({ Bucket: BUCKET, Key: key }); break
>     case 'DELETE': cmd = new DeleteObjectCommand({ Bucket: BUCKET, Key: key }); break
>     case 'LIST':   cmd = new ListObjectsV2Command({
>       Bucket: BUCKET,
>       Prefix: opts?.listPrefix as string | undefined,
>       Delimiter: opts?.listDelimiter as string | undefined,
>       ContinuationToken: opts?.listContinuationToken as string | undefined,
>     }); break
>     case 'COPY':   cmd = new CopyObjectCommand({
>       Bucket: BUCKET,
>       Key: key,
>       CopySource: `${BUCKET}/${opts?.copySource as string}`,
>     }); break
>   }
>   const url = await getSignedUrl(client, cmd, { expiresIn: ttl })
>   res.json({ url })
> })
> ```
>
> Sign only the operations the app needs: a viewer needs `GET`, `HEAD` and `LIST`.

> [accordion] Bucket CORS rules
>
> R2 accepts the S3 CORS call only from a token with **Admin Read & Write** on the
> bucket; an object token gets `Access Denied`. Without one, set the policy in the
> [Cloudflare dashboard](https://dash.cloudflare.com/): **R2**, the bucket,
> **Settings** > **CORS Policy**, with the page's origins, methods
> `GET,PUT,HEAD,DELETE,POST` and allowed headers `*`. With an admin token:
>
> ```json theme={null}
> {
>   "CORSRules": [
>     {
>       "AllowedOrigins": ["http://localhost:5173", "https://app.example.com"],
>       "AllowedMethods": ["GET", "PUT", "HEAD", "DELETE", "POST"],
>       "AllowedHeaders": ["*"],
>       "ExposeHeaders": ["ETag", "Content-Length", "Content-Type", "Last-Modified"]
>     }
>   ]
> }
> ```
>
> ```bash theme={null}
> aws s3api put-bucket-cors --bucket $R2_BUCKET \
>   --endpoint-url https://$R2_ACCOUNT_ID.r2.cloudflarestorage.com \
>   --cors-configuration file://cors.json
> ```

> [accordion] Browser fields
>
> **bucket** `string` *required*
>
> Name of the bucket to mount.
>
> **presignedUrlProvider** `function` *required*
>
> Function `(path, operation, options)` that returns a signed URL for each S3 operation; your server signs it, so the browser holds no keys.
>
> **region** `string` (default: 'auto')
>
> Region of the bucket; R2 addresses a bucket by account, not by region.
>
> **endpoint** `string`
>
> Endpoint URL that replaces the one the provider derives. Requests go to the host each presigned URL names; the mount uses it to name its storage location.
>
> **defaultContentType** `string` (default: 'application/octet-stream')
>
> `Content-Type` stored with every object the mount writes.
>
> **keyPrefix** `string`
>
> Key prefix the mount treats as its root. The browser can change it before a URL is signed, so enforce the prefix on the signing server.
>
> **timeout** `number` (default: DEFAULT\_TIMEOUT)
>
> Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
>
> **accountId** `string`
>
> Cloudflare account ID. It builds the endpoint `https://<accountId>.r2.cloudflarestorage.com` unless `endpoint` is set.
>
> Fields marked secret are redacted in snapshots.

## Integration

R2 answers these commands through its own API, so fewer objects are read. See
[Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `md5sum`: the object's ETag, when it is the MD5 (a single-part upload,
  unencrypted or under SSE-S3).
* `find`: one recursive listing.
* `du`: one recursive listing.
* `ls -R` and `tree`: one recursive listing.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with R2 mounted at `/<path>`.
`<mode>` is the mount's mode: `read`, `write` or `exec`. The commands shown are
those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `<mode>` |
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Almost all Unix commands. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `<mode>` |
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Almost all Unix commands. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.