Bring your own bucket

Set up your bucket #

Point a workspace at a Cloudflare R2 bucket you already control. With your own bucket you:

• Keep files on storage you pay for and own directly — uploads.sh never holds a copy.
• Switch back to hosted storage any time, instantly and without touching existing files.
• See what’s different on a BYO bucket before you switch.

A workspace admin connects from the workspace settings page — one form, filled from three things you set up on the Cloudflare dashboard first (plus one optional cache rule). Any other S3-compatible provider works too — see Other S3-compatible providers.

1. Create an R2 bucket

Dashboard → R2 → Create bucket. Any name that follows Cloudflare’s rules works (3–63 characters; lowercase letters, digits, hyphens). Jurisdiction buckets (eu, fedramp) work too — it’s detected automatically from the endpoint URL, or probed during verification.

2. Create a bucket-scoped API token

R2 → Manage API Tokens → Create API Token, permission Object Read & Write, scoped to that one bucket. Copy the Access Key ID and Secret Access Key — and either your account ID or the S3 endpoint URL shown on the same screen. The form takes either one, and once your keys are in it looks up your buckets for you where the token allows it.

3. Give the bucket a domain

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 form as the public base URL. The settings page requires one — it’s what makes links stable and embeddable. See the serving matrix below.

4. Optional but recommended: add a cache rule for GitHub embeds

On hosted storage, a dedicated embed host serves badge-style no-cache headers that GitHub’s Camo proxy revalidates, so an overwritten image refreshes in place. Give your own domain the same behavior with one rule on your zone: Rules → Transform Rules → Modify Response Header, matching your domain’s hostname, setting Cache-Control to max-age=0, no-cache, no-store, must-revalidate. Verification checks for it and reminds you if it’s missing. Without it, everything still works — a GitHub embed can just keep showing the old bytes after an in-place overwrite.

Then Verify & save: one click checks the settings, signs in to the bucket, round-trips a test object, and fetches it through your public URL. Anything that fails is spelled out on the form; a clean pass saves. Saving never changes where uploads go — the bucket sits on your settings page as “Not in use yet” until you click Use this bucket.

5. Optional: serve SVG and XML

By default, SVG and XML uploads 415 on a BYO bucket the same way they do everywhere else — served inline with no Worker in front, either format could otherwise run a script with your bucket’s origin. Set two headers on your bucket’s public host to open them up:

Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; img-src data:; sandbox
X-Content-Type-Options: nosniff

Two things decide whether the check passes:

• The headers must cover XML, not only SVG. A rule scoped to the .svg extension leaves XML documents free to run script through an <?xml-stylesheet> XSLT. Scope yours by content type (image/svg+xml, application/xml, text/xml) or add the extensions.
• Send exactly one Content-Security-Policy header. Two are legal CSP, but repeated headers arrive comma-joined and the check can’t read them apart, so it fails closed.

Then, on the workspace settings page, open the bucket’s Serve SVG and XML details and click Check now — it uploads an inert SVG and an inert XML file, fetches both back through your public URL, checks the headers on each, and deletes them. Both have to pass. A passing check is good for 30 days; after that (or if the check ever fails) SVG and XML go back to 415ing until you check again. Checks are limited to one a minute per bucket.