Environment & License
All deployment configuration lives in environment variables - database, secrets, object storage, email, and your license key. This page is the reference for what each variable does and how the license check behaves at runtime.
The scaffolder writes a working
.envfor local development. In production, set these in your hosting platform's environment settings - a local.envfile is not read on most platforms.
Core
# Database connection - Postgres or libSQL/Turso URL
DATABASE_URL=postgresql://user:password@host:5432/dbname
# Secret used by Payload to sign auth tokens. Long random string; never reuse across apps.
PAYLOAD_SECRET=your-long-random-secret
# Site identifier - which site (row in the apps table) this deployment serves.
# One database can host unlimited sites; this pins a single-site deployment to its site.
CHAIBUILDER_APP_KEY=my-app
# Canonical site URL, used for licensing and absolute URL generation.
SITE_URL=https://www.example.com
Notes:
PAYLOAD_SECRET- changing it invalidates all existing sessions. Generate withopenssl rand -hex 32.SITE_URL- on Vercel you can omit it; the platform-providedVERCEL_PROJECT_PRODUCTION_URLis used to build the base URL when set.NEXT_PUBLIC_SERVER_URL- optional fallback origin for scripts and tests when no request host is available; not needed on most deployments.
License
# ChaiBuilder license key - optional during the 30-day trial, required after it
CHAIBUILDER_LICENSE_KEY=your_license_key_here
The license key is read only from this environment variable - it cannot be set in code or config. An empty value means trial mode, which starts the moment you deploy. The app validates the license automatically in the background; allow outbound HTTPS from your deployment. An expired trial or license shows a notice in the builder to renew or to downgrade to the last eligible version - published pages keep serving. See Trial & Licensing for how the trial and license periods work.
Object storage (media)
BUCKET_NAME=your-bucket
AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key
S3_REGION=auto
S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com
Required for media uploads to persist in production. The first three switch storage on;
S3_REGION defaults to auto and S3_ENDPOINT is optional (omit it on AWS S3). Full setup
and per-provider values: Storage Configuration.
Email (optional)
EMAIL_FROM_ADDRESS=noreply@example.com
EMAIL_FROM_NAME=My Site
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=smtp-user
SMTP_PASS=smtp-password
Used for password resets and transactional email. When SMTP_HOST is unset in development,
a disposable test inbox is used automatically so email flows still work locally.
Admin panel URL (optional)
# Custom admin path, no leading slash. Server-side value wins.
PAYLOAD_ADMIN_ROUTE=cms-a8f3k2m9
By default the CMS admin panel and the visual builder live under /admin. Setting this
moves both, along with the revalidation route, password reset links, and the robots.txt
disallow entry. The value must be at least 4 characters and is validated at build time, so
a bad value fails the deploy. NEXT_PUBLIC_PAYLOAD_ADMIN_ROUTE is derived automatically -
you do not set it yourself.
The change takes effect on the next build, not on restart alone. Requests to /admin
then redirect to the custom path, which makes this hardening against scanners rather than
access control. Full rules, wiring, and helpers for building admin URLs in your own code:
Admin Route.
Revalidation token (optional)
# Bearer token for the manual revalidation route. Unset = route disabled.
REVALIDATE_TOKEN=your-random-token
Required only if an external system needs to purge page caches via
POST /admin/api/revalidate - see
Caching & Revalidation.
Postgres schema (optional)
# Create all tables in a named schema instead of "public"
CHAIBUILDER_POSTGRESS_SCHEMA=chaibuilder
Note the spelling: the variable is POSTGRESS with a double S. CHAIBUILDER_POSTGRES_SCHEMA
is not read, and the tables silently land in public. See
Database Setup.
AI providers (optional)
# Default route: the Vercel AI Gateway
AI_GATEWAY_API_KEY=your_key_here
OpenRouter, OpenAI-compatible endpoints, and Cloudflare Workers AI each have their own variables. The full list and how ChaiBuilder picks between them is in AI Setup.
Stock photo search (optional)
PEXELS_API_KEY=your_pexels_key
UNSPLASH_ACCESS_KEY=your_unsplash_access_key
PIXABAY_API_KEY=your_pixabay_key
Each key switches on one provider in the media manager's stock search. Set any combination; with more than one, a search is split across them. See Media and Images.
Runtime behavior (optional)
# Believe x-forwarded-host when building the site URL. Only behind a proxy you control.
CHAI_TRUST_PROXY_HEADERS=true
# Where a link to a page with no translation in the current language points:
# primary (default) = the page in the primary language, home = the language home, none = "#"
CHAI_UNTRANSLATED_LINK_FALLBACK=primary
# Stream data-provider blocks through Suspense instead of rendering them inline
CHAI_DISABLE_INLINE_DATA_PROVIDERS=true
# Location of the global stylesheet used to de-duplicate page CSS
CHAI_GLOBAL_CSS_PATH=./public/chaistyles.css
CHAI_TRUST_PROXY_HEADERS- whenSITE_URLis unset, the site origin used for canonicals, hreflang, andog:urlcomes from the request'sHostheader. Behind a reverse proxy that rewritesHost(nginx, Traefik), set this sox-forwarded-hostis used instead. Leave it off on platforms that already pass the public host through, since a client can send anyx-forwarded-hostit likes.CHAI_UNTRANSLATED_LINK_FALLBACK- see Multilingual.CHAI_DISABLE_INLINE_DATA_PROVIDERS- blocks with a data provider render inline by default. Set this to fall back to streaming if a slow, uncached provider on a dynamic route holds up the whole page. It is read at request time, so it can be flipped without a code change.CHAI_GLOBAL_CSS_PATH- published pages inline only the CSS their blocks add on top of your global stylesheet. That reference file is generated before build (by default topublic/chaistyles.css); set this only if you write it somewhere else.
Per-environment checklist
| Variable | Local dev | Production |
|---|---|---|
DATABASE_URL |
scaffolder-written | required |
PAYLOAD_SECRET |
scaffolder-written | required, unique |
CHAIBUILDER_APP_KEY |
scaffolder-written | required |
SITE_URL |
optional | recommended (omit on Vercel) |
CHAIBUILDER_LICENSE_KEY |
optional | required after trial |
BUCKET_NAME + S3 vars |
optional | required for media |
SMTP_* |
optional (test inbox) | required for email |
PAYLOAD_ADMIN_ROUTE |
optional | optional |
AI_GATEWAY_API_KEY (or another AI provider) |
optional | required for AI features |
| Stock photo keys | optional | optional |
Related
- Trial & Licensing - the trial, the Pro license, and the license period.
- Database Setup -
DATABASE_URLdetails and pooling. - Storage Configuration - the S3 variables in depth.

