Images and files you upload in ChaiBuilder - through the builder's media manager or the CMS admin - are stored as a Payload upload collection (media). Each item is a database record (filename, alt text, sizes, and metadata) whose binary file lives in a storage backend you configure.

Images need object storage. By default Payload writes uploaded files to the local filesystem, which is fine for local development but doesn't persist on serverless or containerised hosts (Vercel, Cloudflare, most Docker deploys) - files vanish between deploys and don't exist across multiple instances. For anything beyond local dev, point the media collection at an S3-compatible object store. See Storage Configuration.

The media collection

Media is a standard Payload collection with upload enabled. Out of the box it carries:

• The file itself - uploaded through the media manager or the Payload admin.
• alt - alt text (required, localized), used for accessibility and by the AI image alt text helper.
• Image sizes - Payload generates resized variants via sharp during upload.

Because it's a normal collection, media records are queryable and reference-able from your pages and other collections like any structured content.

How uploads flow

1. An editor uploads an image in the builder's media manager (or in the Payload admin).
2. Payload processes it - generating resized variants with sharp - and writes a media record to your database.
3. The binary file is written to your configured storage backend:
   • No storage adapter → local filesystem (dev only).
   • S3 adapter configured → your object store (S3, Cloudflare R2, MinIO, Spaces, …).
4. Pages and content reference the record; the public file URL resolves to wherever the file is stored.

Using media in the builder

Inside the builder, the media manager is where editors browse, upload, and pick images for blocks and fields. Image blocks and any upload-typed field draw from the same media collection, so an asset uploaded once is reusable everywhere. For editing images in place, see Media & Images in the visual-builder docs.

ChaiBuilder Cloud

If you deploy from ChaiBuilder Cloud, object storage is provisioned for you - an S3 bucket is set up and wired to the media collection automatically, so uploads persist with no manual configuration. Self-hosting? Configure it yourself - see below.

Next

• Storage Configuration - wire the media collection to S3 (or an S3-compatible store) via the Payload S3 plugin.
• Media & Images - the media manager and image editor inside the builder.