Hosting an Agent-Built Website on Cloudflare R2

By Cory LaViska on November 20, 2026

Your agent wrote the website. Here’s how to put the files in a Cloudflare R2 bucket, serve them on your own domain, and connect Surreal CMS so your client can edit them.

This is the setup I recommend when you’re starting fresh. R2 stores the files, Cloudflare serves them on your domain, and Surreal CMS writes to the bucket when someone publishes. It doesn’t matter if the files came from Claude Code, another coding agent, or you wrote them by hand. You just need a folder of HTML, CSS, and images.

The R2 guide in the docs has every click in the Cloudflare dashboard. This post takes you from that folder to a live, editable website, and covers a few things the guide doesn’t: getting the files into the bucket from the command line, keeping your key separate from Surreal CMS’s, and changing the site later without losing your client’s edits.


Before you start

You need a Cloudflare account with R2 turned on, which takes a payment method even though the free tier applies. Your domain has to be an Active zone on that same account, because the custom domain and the rules below only work when Cloudflare handles its DNS. Plan on one bucket per website. A custom domain makes the whole bucket readable, so nothing private goes in it.

You’ll also need rclone, version 1.59 or later, to upload the files. It’s the tool Cloudflare recommends for copying a whole folder into R2. Wrangler, Cloudflare’s own command line tool, uploads one file at a time. On a Mac, brew install rclone does it, or ask your agent to install it.


Get the folder ready

Look over the folder before you upload it.

  • index.html is at the top level, and every folder that should open at its own address, like /blog/, has an index.html of its own. Links to those folders end with a slash, /blog/. Without it, R2 won’t find the page.
  • There’s an uploads folder holding the images your client will change, and nothing else. This becomes the site’s upload folder, the one place editors can add, rename, and delete files. Put at least one file in it, because empty folders don’t get uploaded. Here’s why it should be a folder of its own.
  • There’s a 404.html if you want a custom not-found page. On Cloudflare that needs a paid plan on the domain.
  • Stylesheets, scripts, and images are linked with relative paths or over https://. The editor runs on a secure connection and won’t load stylesheets or scripts served over plain HTTP.
  • The folder holds only the website. Agents often leave a .git folder, a CLAUDE.md, or an .env file next to the pages, and everything you upload becomes public.

If the agent hasn’t made the site editable yet, this is the time. Everything after this step touches the live files.

Read https://www.surrealcms.com/skills/surreal-cms/SKILL.md and make this website editable in Surreal CMS. Keep the images my client will change in an uploads folder, and run the checker on every page.

Create the bucket and two tokens

In the Cloudflare dashboard, go to R2 and create a bucket. Pick a name like my-website, choose the location closest to most of your visitors, and leave the storage class on Standard. The name and location can’t be changed later. The docs walk through the form.

Next, open API Tokens from the R2 overview page and create two Account API tokens, or User API tokens if your role can’t create those, each with Object Read & Write permission and scoped to this one bucket. Name one surreal-cms and the other after your computer. Surreal CMS gets the first. The second stays on your machine for rclone and for your agent. Either can be revoked without touching the other, and neither can create or delete buckets, change bucket settings, or list your other buckets. Don’t hand an agent an Admin token for a job like this.

Copy each token’s Access Key ID and Secret Access Key when they’re shown. The secret only appears once. You’ll also need your Account ID, which is on the R2 overview page.


Upload the files with rclone

rclone needs to know about the bucket once. Run rclone config file to find its config file, and add this to it with your account ID and the second token’s keys. Don’t paste the keys anywhere else, including your chat with the agent.

[r2]
type = s3
provider = Cloudflare
access_key_id = YOUR_ACCESS_KEY_ID
secret_access_key = YOUR_SECRET_ACCESS_KEY
region = auto
endpoint = https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com
acl = private
no_check_bucket = true

The last line is there because rclone tries to check for or create the bucket before it uploads, and a token that’s limited to objects isn’t allowed to.

Now copy the folder up. Add --dry-run to the end of the command for a trial run that lists what would change, then run it for real.

rclone copy ./site r2:my-website --header-upload "Cache-Control: no-cache" --progress

Two things about that command. copy adds and replaces files but never deletes anything in the bucket, which is what you want for a website other people edit. And the header gives your files the same no-cache rule Surreal CMS puts on every file it publishes. Cloudflare caches stylesheets, scripts, and images for your domain, and that header tells it to check the bucket each time, so a replaced file shows up right away instead of when the cache expires. rclone sets each file’s content type from its extension, so HTML arrives as HTML.

Check the result with rclone ls r2:my-website. You should see index.html, your other pages, and the files in uploads/.

If you’d rather have the agent do it, tell it where the remote is and what not to do.

The rclone remote named r2 points at my R2 bucket, my-website. Copy the ./site folder into the root of the bucket with rclone copy and the header Cache-Control: no-cache. Do a dry run first and show me the list. Don’t use rclone sync, and don’t delete anything.

Put it on your domain

Open the bucket’s Settings and connect a custom domain, such as www.example.com. Cloudflare creates the DNS record and the certificate. Once the domain is active, https://www.example.com/index.html loads your homepage. Don’t use the r2.dev address for anything. It’s rate limited, and the rules below don’t apply to it.

https://www.example.com/ doesn’t work yet, because R2 has no idea that a folder should serve its index.html. Switch into your domain in the dashboard and add the URL rewrite rule from the docs. It appends index.html to any path that ends in a slash. There’s a second, optional rule if you want /about to serve about.html.

While you’re in the domain’s settings, make sure Caching › Configuration › Browser Cache TTL is set to Respect Existing Headers, and that no cache rule for the hostname uses Cache Everything. Otherwise Cloudflare can override the header you just set, and visitors see old files for hours after a publish. The docs cover this too.


Let the editor load your fonts

Surreal CMS opens your page inside its own app to edit it, so the page runs on a different origin than it does for a visitor, and its requests for web fonts and JavaScript modules become cross-origin. Browsers block those unless the server allows them. Without that permission, the editor shows your site in a fallback font, and any type="module" script stays silent. Visitors aren’t affected.

In the bucket’s Settings, under CORS Policy, add this policy on the JSON tab. It allows read requests from anywhere, which is what a public website already permits. The docs have the same step.

[
  {
    "AllowedOrigins": ["*"],
    "AllowedMethods": ["GET"]
  }
]

If the domain has been serving traffic already, purge Cloudflare’s cache for it once so the cached files pick up the header. You can check with curl, using the path of a font your site loads. Cloudflare only sends the header when the request has an Origin, so include one.

curl -s -o /dev/null -D - -H "Origin: https://example.org" https://www.example.com/fonts/body.woff2 | grep -i access-control-allow-origin

Connect Surreal CMS

Log in, choose New Site, and pick Cloudflare R2 as the protocol. The URL is your custom domain, https://www.example.com/, not the R2 endpoint. Enter your Account ID, the bucket name, and the keys from the surreal-cms token. Leave the home folder empty, since the site is at the root of the bucket, and set the upload folder to uploads. Select Test Connection. The docs describe each field.

Then open Enable Pages and use Scan for Pages. It finds every file with content regions and lets you enable them at once. Open one in the editor, change a word, publish, and reload the page on your domain. The change should be there right away. Surreal CMS writes the file straight to the bucket, and Cloudflare doesn’t cache HTML by default.

On a paid plan, your agent can do this part with an agent token: create the site, enable the pages, and invite your client. Creating the site through the API means giving the agent the Surreal CMS key, so if you’d rather keep that out of the chat, let it create the site without credentials and enter the keys yourself under Edit Site. The API can’t test the connection or publish, so you’ll still do those yourself.


Change the site later

Once a client is editing, the bucket is the only current copy of the site. The folder on your computer is out of date the moment they publish. So before you or the agent change anything, pull the live site down into a new, empty folder. An empty folder matters: if you pull into the old one, files your client deleted are still there and go back up with the next push.

rclone copy r2:my-website ./site

Make the change, then copy the folder back up with the same command you used the first time, and read the --dry-run list before the real run. It should name only the files you changed. If it lists a page you didn’t touch, the client published in the meantime, so pull again. Pull right before you push, and if the client is working on the site, ask them to hold off until you’re done. Never use rclone sync toward the bucket. It makes the bucket match your folder, which means deleting everything your client added. If a page needs to go, remove it in Surreal CMS first so it isn’t left pointing at a missing file, then delete the file in the Cloudflare dashboard if it’s still there.

The agent prompt is the same idea.

Pull the live site from r2:my-website into a new, empty ./site folder with rclone copy before you change anything. Then add a Services page that matches the other pages, run the Surreal CMS checker, and copy the folder back up with Cache-Control: no-cache. Don’t sync, and don’t delete anything.

A few more habits. Don’t overwrite a page the client has edited with an old copy, and don’t delete a page in Surreal CMS and add it again. The first throws away their edits, the second the page’s revision history too. When you add a page, keep its header and footer identical to the other pages, because Surreal CMS copies shared includes to every enabled page when one is published, and a page with a stale copy overwrites the rest. Then enable the new page under Enable Pages, and add it to your client’s permissions if they’re limited to specific pages.


What it costs

R2 charges for storage and operations, not bandwidth, and a typical brochure website stays inside the free tier. Publishing a page is a write, or one for every enabled page when a shared header or footer is involved. A page view is a read for the page plus one for each file it loads, because no-cache makes Cloudflare check the bucket every time, and the free tier covers 10 million reads a month. The docs have the current numbers and the trade-offs, the main one being that HTML is served from the bucket’s region rather than from Cloudflare’s edge.


Checklist

  • A folder with index.html at the top, an uploads folder, nothing private, and clean checker results
  • One bucket for this website, in the region closest to your visitors
  • Two Object Read & Write tokens scoped to the bucket: one for Surreal CMS, one for you
  • Files copied up with rclone and Cache-Control: no-cache
  • A custom domain, the directory index rule, and Browser Cache TTL on Respect Existing Headers
  • A CORS policy on the bucket allowing GET from any origin
  • Surreal CMS connected with the surreal-cms token and uploads as the upload folder
  • A test edit published and visible on the domain
  • Pull into an empty folder before every push, and never rclone sync toward the bucket

When everything works, hand it off. If you get stuck, contact us and tell us where it stopped.

So simple, it’s Surreal

Free for personal, educational, and non-profit websites.

By signing up, you agree to the terms of service.