Bring your own bucket

Set up your bucket #

A workspace admin runs the connect wizard from the workspace settings page. Three steps on the Cloudflare dashboard, then verify before anything is saved.

1. Create an R2 bucket

Dashboard → R2 → Create bucket. Any name that follows Cloudflare's rules works (3–63 characters; lowercase letters, digits, hyphens). If the bucket is in a jurisdiction (eu or fedramp), pick that same jurisdiction in the wizard.

2. Create a bucket-scoped API token

R2 → Manage API Tokens → Create API Token, permission Object Read & Write, scoped to that one bucket. You get an Access Key ID, a Secret Access Key, and your account ID.

Scope the token to one bucket, not the whole account. uploads.sh encrypts the key pair, but a bucket-scoped token still limits the blast radius if anything goes wrong.

3. Optional: custom domain for public reads

Bucket → Settings → Public access → Custom Domains, connect a domain on a Cloudflare zone in your account, then paste the URL (for example https://media.example.com) into the wizard as the public base URL. See the serving matrix below for what this buys you.

Enter the account ID, bucket name, and key pair, then run verify. It checks the inputs, authenticates against the bucket, round-trips a test object, and (on first attach) confirms the bucket is empty unless you choose to adopt existing contents. Only a passing verify can save.

You can only connect at workspace creation or on an empty workspace — there's no migration path yet for workspaces that already have files (every published URL would break). File-size and video-size limits still apply on a BYO bucket; the storage-quota budget does not.