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 .env for local development. In production, set these in your hosting platform's environment settings - a local .env file 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 with openssl rand -hex 32.
  • SITE_URL - on Vercel you can omit it; the platform-provided VERCEL_PROJECT_PRODUCTION_URL is 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 - when SITE_URL is unset, the site origin used for canonicals, hreflang, and og:url comes from the request's Host header. Behind a reverse proxy that rewrites Host (nginx, Traefik), set this so x-forwarded-host is used instead. Leave it off on platforms that already pass the public host through, since a client can send any x-forwarded-host it 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 to public/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

© ChaiBuilder. All rights reserved.

ChaiBuilderMade withChaiBuilder