Your agent wrote the website. Here’s how to put the files in a private Amazon S3 bucket, serve them on your own domain through CloudFront, and connect Surreal CMS so your client can edit them.
S3 is the right choice when you’re already on AWS. It takes more steps than R2, but none of them are hard, and you end up with a setup AWS itself recommends: a bucket nobody can read directly, and a CloudFront distribution that serves it on your domain over HTTPS. 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 S3 and CloudFront guide in the docs has every click in the AWS console. 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 an AWS account with permission to manage S3, IAM, and CloudFront, and you need to be able to add
DNS records for your domain. If you want the site at example.com rather than
www.example.com, your DNS provider has to support ALIAS records or something like them. Route
53 does. Plan on one bucket per website, with nothing private in it.
You’ll also need the AWS CLI to upload the files. The console can upload files too, but the command line handles a whole folder at once, sets the caching header, and lets your agent do the work. Ask it to install the CLI if you don’t have it.
Get the folder ready
Look over the folder before you upload it.
-
index.htmlis at the top level, and every folder that should open at its own address, like/blog/, has anindex.htmlof its own. Link to those folders with a trailing slash,/blog/, so relative links inside them resolve against the right folder. -
There’s an
uploadsfolder 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.htmlif you want a custom not-found page. -
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
.gitfolder, aCLAUDE.md, or an.envfile 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 an IAM user with two keys
In the S3 console, create a bucket in the Region closest to most of your visitors. Keep the defaults:
Object Ownership on Bucket owner enforced, which disables ACLs, and all
four Block Public Access settings on. The bucket stays private. CloudFront is the only
thing that will read from it. Write down the bucket name and the Region code, such as
us-east-1, because neither can be changed and you’ll need both later. The
docs walk through the form.
Then follow the IAM step in the docs to create a user with an inline policy that can list this one bucket and read, write, and delete its objects. That’s all Surreal CMS needs, and all you need to upload. IAM allows two access keys per user, so create two. One is for Surreal CMS. The other stays on your computer for the AWS CLI and your agent. Either can be deleted without touching the other. Copy each secret when it’s shown, because AWS won’t show it again.
Upload the files with the AWS CLI
Give the CLI its own profile for this site so your other AWS credentials, if you have any, stay out of it.
The prompts ask for the second key’s ID and secret, the bucket’s Region, and an output format. Answer
json to the last one.
aws configure --profile my-website
That stores the key in a file in your home folder, so you never have to paste it anywhere else, including
your chat with the agent. Now sync the folder up. Add --dryrun to the end of the command for
a trial run that lists what would change, then run it for real.
aws s3 sync ./site s3://my-website-files --cache-control no-cache --profile my-website
Two things about that command. Without a --delete flag, sync adds and replaces
files but never removes anything from 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. It tells browsers to check for a fresh copy each time, so a replaced stylesheet shows up on the
next reload. The CLI sets each file’s content type from its extension, so HTML arrives as HTML.
Check the result with aws s3 ls s3://my-website-files --recursive --profile my-website. Their
S3 addresses return Access Denied in a browser. That’s expected, because the bucket is private. You’ll see
the site once CloudFront is in front of it.
If you’d rather have the agent do it, tell it which profile to use and what not to do.
The AWS CLI profile my-website can write to the S3 bucket my-website-files. Sync the ./site folder to the root of the bucket with aws s3 sync and --cache-control no-cache. Do a dry run first and show me the list. Never pass --delete.
Put CloudFront in front of it
This is the long part, and the docs cover each screen. In short, you
create a pay-as-you-go distribution with the bucket
as its origin and the recommended origin settings, which let CloudFront read the private bucket. Then you
switch the cache policy to CachingDisabled, so every
request goes to S3 and a publish is visible immediately, and you
add a small CloudFront function that turns / into
/index.html and /blog/ into /blog/index.html. A custom 404 page is
an optional step in the same guide.
When the distribution finishes deploying, open its cloudfront.net address in a browser. Your
homepage should load at /.
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.
CloudFront can add the permission for you, and the
docs have the same step. Open the distribution’s
Behaviors tab, edit the default behavior, and set
Response headers policy to the managed policy named SimpleCORS. It adds
Access-Control-Allow-Origin: * to responses for cross-origin requests, which is what a public
website already permits. Save, wait for the deployment, and check a font your site loads with
curl. CloudFront only adds the header when the request has an Origin, so include
one.
curl -s -o /dev/null -D - -H "Origin: https://example.org" https://d111111abcdef8.cloudfront.net/fonts/body.woff2 | grep -i access-control-allow-origin
Put it on your domain
Two more steps in the docs:
add your domain to the distribution and let CloudFront request a certificate, which means adding the CNAME records it shows you, then
point your domain at the distribution. For www that’s a
CNAME to the cloudfront.net address. For an apex domain it’s an ALIAS record. Once DNS
updates, the site is live at https://www.example.com/.
Connect Surreal CMS
Log in, choose New Site, and pick Amazon S3 as the
protocol. The URL is your own domain, https://www.example.com/, not a
cloudfront.net or amazonaws.com address. Enter the Region code, the bucket name,
and the ID and secret of the first access key, the one you set aside for Surreal CMS. Leave the
ACL option off, since the bucket has ACLs disabled and S3 rejects uploads that include
one. Leave the home folder empty, because 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. S3 is strongly consistent, and with caching disabled CloudFront asks S3 for the file on every request, so there’s nothing to invalidate.
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.
aws s3 sync s3://my-website-files ./site --exact-timestamps --profile my-website
--exact-timestamps matters too. Without it, the CLI skips a file in the bucket that’s newer
but the same size as your copy, which is what a one-character edit by your client looks like. Make the
change, then sync the folder back up with the same command you used the first time, and read the
--dryrun 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 add
--delete when you push. It removes everything from the bucket that isn’t in your folder,
including your client’s uploads. 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 S3 console if it’s still there.
The agent prompt is the same idea.
Pull the live site from s3://my-website-files into a new, empty ./site folder with aws s3 sync --exact-timestamps and the my-website profile before you change anything. Then add a Services page that matches the other pages, run the Surreal CMS checker, and sync the folder back up with --cache-control no-cache. Never pass --delete.
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
CloudFront’s pay-as-you-go plan has a monthly free allowance that covers most brochure websites, and traffic from S3 to CloudFront is free. You pay S3 for storage and requests, and with caching turned off every file a visitor loads is a request to S3. For a small site that comes to very little. The docs have the current numbers and the trade-offs, including the one that matters most: with caching off, every visitor waits on your bucket’s Region.
Checklist
-
A folder with
index.htmlat the top, anuploadsfolder, nothing private, and clean checker results - One private bucket for this website, ACLs disabled, Block Public Access on
- An IAM user limited to that bucket, with two access keys: one for Surreal CMS, one for you
- Files synced up with the AWS CLI and
--cache-control no-cache - A distribution with the recommended origin settings, CachingDisabled, and the index function
- The SimpleCORS response headers policy on the default behavior
- A certificate, your domain on the distribution, and a DNS record pointing at it
- Surreal CMS connected with ACL off and
uploadsas the upload folder - A test edit published and visible on the domain
-
Pull into an empty folder with
--exact-timestampsbefore every push, and never--delete
When everything works, hand it off. If you get stuck, contact us and tell us where it stopped.