Object storage and static assets
Where generated images and videos live, and where the site's static assets are loaded from. Both use S3-compatible storage; our own production environment uses Cloudflare R2, but that is not a hard dependency.
← Documentation index · See also: Cloudflare in front · Environment variables
1. Who uses it, and what breaks without it
| Consumer | Setting | What happens if it is not set |
|---|---|---|
mcp-vision, mcp-motion |
STORAGE_* (seven variables) |
Generated results come back as the model provider's temporary URLs, which expire within hours — images and videos in conversation history turn into broken links |
thia-web |
staticCdnUrl + staticAssetVersion |
Showcase assets (the homepage 3D avatar, the avatar docs page, the demo sections) fail to load and fall back to 2D or blank; sign-in, chat and the console are unaffected |
Only mcp-vision and mcp-motion upload; everything is read through a public address. The bucket
must therefore allow anonymous reads — signed URLs expire, and an expired address is a dead message in
someone's history.
2. Pick a provider
Any S3-compatible storage works: Cloudflare R2, AWS S3, Alibaba Cloud OSS, Tencent Cloud COS, MinIO.
The STORAGE_* variables describe how to connect over the S3 protocol; they do not bind you to a vendor.
3. Cloudflare R2 as the example
- Create a bucket: dashboard → R2 → Create bucket; its name is
STORAGE_BUCKET. - Enable public read: buckets are private by default. For production use a custom domain
(a domain in the same Cloudflare account, which brings caching and WAF); the
r2.devdevelopment URL is rate-limited and only suitable for trials. - Create an API token: R2 → Manage R2 API Tokens, permission
Object Read & Write; note the Access Key ID and Secret Access Key. - Fill in the variables (one set each for
mcp-visionandmcp-motion):
| Variable | Value on R2 |
|---|---|
STORAGE_ENDPOINT |
https://<account-id>.r2.cloudflarestorage.com |
STORAGE_REGION |
auto — R2 has no region to choose |
STORAGE_BUCKET |
the bucket from step 1 |
STORAGE_ACCESS_KEY_ID / STORAGE_SECRET_ACCESS_KEY |
the AK / SK from step 3, in a Secret |
STORAGE_PUBLIC_URL |
the public domain prefix from step 2, no trailing slash |
STORAGE_ACL |
leave empty (see below) |
STORAGE_FORCE_PATH_STYLE |
false; set true for implementations that only support path-style, such as MinIO |
⚠️
STORAGE_ACLmust be explicitly set to an empty string. Its default ispublic-read, and R2 does not support object ACLs, so uploading with the default is rejected — the symptom is that every generation succeeds and the upload step returns 500. Public access is decided by the bucket setting in step 2, never by an object ACL.
Other providers follow the same shape: swap the endpoint, region and bucket, and enable public read with a bucket policy rather than an object ACL.
4. Site assets (staticCdnUrl)
staticCdnUrl points at the public domain of the bucket (or any static site); pages load assets from
paths such as <prefix>/models/.... staticAssetVersion is a version parameter appended to those
addresses — bump it and the CDN serves the new files immediately.
The assets are not shipped in the images — public/ does not contain them. With no assets, leave it
empty: showcase sections fall back to 2D or blank, and nothing functional is affected.
5. Verification
# 1. Anonymous read: expect 200, not 403 / 404
curl -sI "$STORAGE_PUBLIC_URL/<an-object-you-uploaded>" | head -3
# 2. Generate an image in a conversation: the returned address should start with $STORAGE_PUBLIC_URL
# (not the model provider's temporary domain), and should still display in a fresh incognito window