Set up file storage and uploads
Users can upload files and download them through time-limited links, stored in your own S3-compatible bucket or R2 binding.
User uploads and AI-generated media are stored in one bucket. The server writes the files, and the browser never uploads to the bucket directly, so the bucket stays private and needs no CORS rule. Storage is configured in the admin console and needs no environment variables.
Before you begin
- An admin account with
config.readandconfig.write. - A bucket, or an app running on Cloudflare Workers with an R2 bucket bound as
BUCKET.
Choose the driver by where the app runs:
| Driver | Use it when | What you set up |
|---|---|---|
| S3-compatible endpoint | Any runtime: Node, Docker, Cloudflare Workers. | A bucket and an access key. |
| Native bucket binding | The app runs on Cloudflare Workers with an R2 bucket bound as BUCKET. | The binding only, no keys. |
Create the bucket with the storage provider
| Provider | Choose it for |
|---|---|
| Cloudflare R2 | A Workers bucket binding or R2 over S3 |
| Amazon S3 | Private AWS bucket with regional signing |
| MinIO | Self-hosted object storage |
Connect the bucket
Create the bucket and an access key
In your provider's console, create a bucket and an API key that can read, write and delete objects in it.
Use the field mapping in your provider’s guide above.
Go to Settings → Storage Config (/admin/config/storage), tick Enable uploads and select S3-compatible endpoint. Then fill in:
- Connection → Bucket name: the bucket you created.
- Connection → Region: the signing region in the provider guide. It defaults to
us-east-1. - Connection → S3 endpoint: the endpoint from the provider guide, without the bucket name.
- Credentials → Access Key ID and Secret Access Key: the key pair.
On a first setup the S3 option stays greyed out until these fields are saved. Saving still uses it.
Save
Click Save storage config. The page shows Storage configuration saved., and under Storage driver in the Runtime panel, Read access shows sigv4.
Credential fields are empty every time the page loads. Leave a field blank to keep the saved value.
Set limits and a public domain
Limit file size
Under Limits and MIME types, set Max file size bytes. The default is 10485760 (10 MB).
Limit file types
Edit Image MIME types, Video MIME types, Audio MIME types and File MIME types as comma-separated content types. The defaults are image/png, image/jpeg, image/webp, image/gif; video/mp4, video/webm; audio/mpeg, audio/wav, audio/ogg; and application/pdf, text/plain.
Add a public domain (optional)
If a CDN or custom domain already serves the bucket's objects, fill in Connection → CDN or public access domain, for example https://assets.example.com. Each new upload records a public link made of this domain and the object path. The app does not make the bucket public, and earlier files keep the link they were saved with.
Save
Click Save storage config.
Unticking Enable uploads and saving turns uploads off without removing the saved credentials.
Upload over the API
Users upload from /app/assets/upload. Scripts use a session cookie or an API key with Upload files. The endpoint accepts multipart/form-data (a file field) or JSON (a base64 field). Without folderId the file goes to the user's /uploads folder.
curl -X POST https://your-domain.example/api/assets/upload \
-H "Authorization: Bearer $API_KEY" \
-F "file=@./report.pdf" \
-F "resourceType=file"
# 201 => { "ok": true, "file": { "id": "file_...", "objectKey": "...", "publicUrl": null, ... } }Each user has three folders: /, /uploads and /generated, where AI output goes. Uploads to any other folder are rejected. Signed download links expire after at most 24 hours.
Before storage is configured
There is no fallback storage. Uploads fail with S3-compatible storage credentials are not configured. (HTTP 503 from /api/assets/upload), signed links cannot be created, and /setup lists Object storage as not ready.
Verify
Check the upload page
Open /app/assets/upload as any signed-in user. The badge next to the title reads R2 ready once a driver is usable (the label is the same for every provider), or Storage not configured.
Upload a file
Pick a Resource type, choose a File that matches its allowed types, and click Upload. The form shows Uploaded and the file name, or the provider's error.
Download it
Open the file from /app/assets and click Generate signed URL. Open the URL under the button in a new tab. The file loads.
Check the admin view
Platform → Assets (/admin/assets) lists the file under its owner, and /setup lists Object storage as ready.
pnpm validate:files checks the wiring for both drivers. pnpm validate:storage-drivers writes, reads and deletes real objects in your bucket.
Troubleshooting
Upload returns "Content type ... is not allowed"
The file's type is not in the list for the resource type you sent. Add it to the matching MIME list on Storage Config, or send the correct resource type.
Upload returns "Folder does not exist"
The folder id is not one of the caller's own folders. Omit folderId on /api/assets/upload to use /uploads.
S3 upload fails with "Storage upload failed (403)"
The error shows the provider's own code and message. Check the access key, secret and bucket name, and that Region matches what the endpoint expects for signing.
A signed link from the binding driver returns 503
Links on your own site only serve files while the binding driver is selected and the BUCKET binding is present. A link issued before switching drivers cannot be served. Generate a new one.