Configuring R2

1. Create a bucket

Create an R2 bucket in Cloudflare.

Note your account ID in the Cloudflare dashboard; you’ll need it for both the profile and the endpoint.

2. Create an API token

Create an R2 API token with Object Read & Write, scoped to the bucket. Cloudflare issues it as an S3-style pair — an access key ID and a secret access key.

3. Set credentials

R2 is supported via the S3 API, so the credentials can be set using the same environment variables:

export AWS_ACCESS_KEY_ID={r2_access_key_id}
export AWS_SECRET_ACCESS_KEY={r2_secret_access_key}

Or pass them explicitly with --access-key-id and --secret-access-key.

4. Create the profile

loonfs --no-input profile create r2 production \
  --bucket {bucket_name} \
  --account-id {account_id} \
  --endpoint-url https://{account_id}.r2.cloudflarestorage.com

loonfs profile use production

Both --account-id and --endpoint-url are required. Optional: --key-prefix.

The Cloudflare R2 endpoint supports direct GET, direct PUT with SHA-256, and direct multipart transfers.

CORS

For browser clients, configure CORS on the bucket to allow the returned methods and signed headers from your application origin.

It’s also best practice to setup an R2 lifecycle rule that aborts incomplete multipart uploads and prevent abandoned sessions from taking up storage.

5. Verify

loonfs maintenance store probe

The R2 compare-and-swap limit

Cloudflare rate-limits compare-and-swap to roughly one concurrent write per second to the same object key.

LoonFS uses these conditional object writes to coordinate namespace metadata. This limit can therefore impact maximum commit latency for a busy namespace, and some writes can take up to ~1s before acknowledgement.

See Tradeoffs and Write-ahead log.