Environment Variables Reference
For AI agents: All required variables must be set before starting the CMS API. Missing required variables will cause startup to fail with an explicit error message.
This page documents every environment variable and Cloudflare binding used by LumiBase.
Core runtime
| Variable | Required | Default | Description |
|---|---|---|---|
LUMIBASE_ENV | ✓ | — | Environment label: development, staging, production |
LUMIBASE_RUNTIME | Docker only | cloudflare | docker for Node.js/Docker; Cloudflare Workers infers from bindings |
CORS_ALLOWED_ORIGINS | ✓ in production | — | Comma-separated browser origins allowed to call the API; * is rejected in production. On Docker, when unset, the image entrypoint uses this deployment's own origin (LUMIBASE_PUBLIC_URL, then the platform's public URL) — the Studio is served from that origin. A value with no host, such as https://, counts as unset |
LUMIBASE_PUBLIC_URL | ✗ | — | Public origin of this deployment, e.g. https://cms.example.com. Read by the image entrypoint to default CORS_ALLOWED_ORIGINS and to print the setup wizard URL. Without it the entrypoint uses RENDER_EXTERNAL_URL, RAILWAY_PUBLIC_DOMAIN or FLY_APP_NAME when the platform sets them. See One-click deploys. The server also uses it to build the MCP OAuth resource URI (<origin>/api/v1/mcp…) that a token's aud must match. Without it that origin comes from the request (upgraded to https by X-Forwarded-Proto), so set it behind a TLS-terminating proxy when you use the remote MCP connector |
JWT_SECRET | ✓ | — | Secret for signing/verifying application JWTs. Min 32 chars. For Cloudflare production, set with wrangler secret put JWT_SECRET --env production; never commit or place in [env.production.vars]. |
LUMIBASE_DEV_AUTH | Local dev only | false | Set to true to bypass Logto auth in local dev. Never enable in production; pnpm release:check fails if production resolves to true. |
LUMIBASE_ALLOW_ORG_SIGNUP | Optional | unset | Set to true to allow authenticated Studio users to create organizations. Bootstrap instance operators may create organizations without this flag. Site creation and deletion use the organization API; the legacy admin site-management routes and their test-only flag have been removed. |
LUMIBASE_MCP_ORG_TOOLS | Optional | on | Set to off to disable organization MCP globally, regardless of contentOs.mcp.allowOrganizationTools. Any other value leaves the per-organization setting authoritative; that setting defaults to false. This does not disable site MCP. |
LUMIBASE_REALTIME_ENABLED | ✗ | — | Not implemented. Nothing reads this yet; setting it has no effect. Tracked as the "explicit enablement" goal in realtime implementation. |
VITE_LUMIBASE_ALLOW_ADMIN_PATH_REDIRECT | Setup/debug only | false | Client-side opt-in that allows convenience redirects to the private admin path. Keep unset in production except for a temporary controlled setup/debug window. |
The admin path is not configured by an environment variable. It is chosen during the Setup Wizard and stored in the database, so it can be rotated without a redeploy — and so it never sits in a build artifact.
It is private operational state. Do not expose it through VITE_* environment
variables or client build metadata, and do not automatically redirect
public/setup routes to it in production. See
Private admin path.
First-run setup
| Variable | Required | Default | Description |
|---|---|---|---|
LUMIBASE_REQUIRE_SETUP_TOKEN | ✗ (Node/Docker only) | off | true, 1 or yes makes POST /api/v1/setup/complete demand a one-time setup token. Turn it on for any instance that someone other than you can reach before setup is finished — otherwise whoever reaches the port first creates the admin account. |
With the flag on, every process that serves HTTP (LUMIBASE_PROCESS_ROLE web or
all) mints the token as it starts, before it accepts requests, and prints it once:
[lumibase-cms] SETUP_TOKEN=<token>
Paste it into the setup wizard, or send it as setupToken to /setup/complete. Only
its SHA-256 hash is stored, and the hash is cleared when setup completes.
A restart does not print a new token: the stored hash is kept so a token you already have stays valid, and the startup log says so instead. If you lost the line, clear the hash and restart — the next start prints a fresh token:
UPDATE lumibase_system_state SET setup_token_hash = NULL WHERE id = 'singleton';
Several replicas starting at once print exactly one token between them, so read it from whichever replica printed it.
Cloudflare Workers: not supported. A Worker has no process start to mint the token
in, so with the flag on /setup/complete answers 503 SETUP_TOKEN_NOT_ISSUED with an
explanation instead of accepting a token. Leave the flag unset there and complete setup
right after deploying.
Encryption
| Variable | Required | Default | Description |
|---|---|---|---|
ENCRYPTION_KEY | Before first use | — | Base64 of 32 random bytes (openssl rand -base64 32). Wraps encrypted item fields and TOTP two-factor seeds. Resolved as key version v0. Production requires standard, padded base64 of 16, 24 or 32 bytes; the value is used exactly as supplied (CDC derives its key from the string), so never re-encode an existing key. Set as a secret (wrangler secret put ENCRYPTION_KEY --env production); never commit it or place it in [env.production.vars] |
ENCRYPTION_KEY_<id> | ✗ | — | Versioned key material, e.g. ENCRYPTION_KEY_v1, used for rotation |
ENCRYPTION_ACTIVE_KEY_ID | ✗ | only configured key, else v0 | Which key version encrypts new data |
ENCRYPTION_KEY[_<id>]_FILE | ✗ | — | Path to read the key from instead of the variable (Docker secrets). The direct variable wins |
"Before first use" means before anyone enrolls in 2FA or writes an encrypted
field — not before boot. Without a key, enrollment fails closed with a 500
rather than a typed error.
Once seeds exist, a key can never be removed. TOTP seeds pin the key version that wrapped them and are not re-wrapped by the envelope migration, so retiring an old key locks those users out of their second factor. Rotation is also not a remedy for a leaked key. See Encryption key operations.
Authentication (Logto)
| Variable | Required | Description |
|---|---|---|
LOGTO_ENDPOINT | ✓ | Logto instance URL (e.g., https://your-tenant.logto.app) |
LOGTO_APP_ID | ✓ | Logto application ID |
LOGTO_APP_SECRET | ✓ | Logto application secret |
LOGTO_JWKS_URI | ✗ | Override JWKS URL (auto-derived from LOGTO_ENDPOINT if not set) |
CF_ACCESS_CERTS_URL | CF Access only | Cloudflare Access JWKS URL for admin tunnel auth |
CF_ACCESS_AUDIENCE | CF Access only | Cloudflare Access application audience tag |
Database
| Variable | Required | Description |
|---|---|---|
DATABASE_URL | Docker only | PostgreSQL connection string (e.g., postgres://user:pass@host:5432/lumibase) |
DATABASE_POOL_MIN | ✗ | Minimum DB pool connections (default: 2) |
DATABASE_POOL_MAX | ✗ | Maximum DB pool connections (default: 10) |
DATABASE_SSL | ✗ | true to require SSL for DB connection |
LUMIBASE_DB_RLS | ✗ | Request-path RLS scope: off (default) or enforce. Any other value fails closed (startup error on Docker, 503 RLS_MISCONFIGURED on Workers). See Request-path RLS scope |
LUMIBASE_OPS_TOKEN | ✗ | Static bearer secret (≥ 32 chars) for the read-only ops diagnostics plane /api/v1/ops/* and error capture lookup. Unset or shorter: the plane answers 404 everywhere. See Ops diagnostics |
DATABASE_SYSTEM_URL | With LUMIBASE_DB_RLS=enforce (Docker) | Connection string of the system role (BYPASSRLS) used by workers, cron and system routes. Unset: those paths use DATABASE_URL. Also read from DATABASE_SYSTEM_URL_FILE |
For Cloudflare Workers, use the HYPERDRIVE binding (see Cloudflare Bindings).
Cache
| Variable | Required | Description |
|---|---|---|
REDIS_URL | Docker only | Redis connection string (e.g., redis://localhost:6379) |
CACHE_TTL_SCHEMA | ✗ | Schema cache TTL in seconds (default: 60) |
CACHE_TTL_PERMISSIONS | ✗ | Permission cache TTL in seconds (default: 300) |
CACHE_TTL_SETTINGS | ✗ | Settings cache TTL in seconds (default: 60) |
Object storage
| Variable | Required | Description |
|---|---|---|
S3_ENDPOINT | Docker/S3 only | S3-compatible endpoint URL (e.g., MinIO: http://localhost:9000) |
S3_ACCESS_KEY_ID | Docker/S3 only | S3 access key |
S3_SECRET_ACCESS_KEY | Docker/S3 only | S3 secret key |
S3_BUCKET | Docker/S3 only | Storage bucket name (default: lumibase-media) |
S3_REGION | ✗ | S3 region (default: us-east-1) |
S3_PUBLIC_URL | ✗ | Public base URL for assets (e.g., CDN URL pointing to the bucket) |
Search (MeiliSearch)
| Variable | Required | Description |
|---|---|---|
MEILISEARCH_HOST | If search enabled | MeiliSearch instance URL, e.g. http://meilisearch:7700 |
MEILISEARCH_API_KEY | If search enabled | MeiliSearch master or search API key |
AI Copilot
| Variable | Required | Description |
|---|---|---|
LLM_PROVIDER | ✗ | LLM provider: openai, anthropic, claude, gemini, nvidia, vertex, workers-ai, echo (default: echo) |
OPENAI_API_KEY | If openai provider | OpenAI API key |
ANTHROPIC_API_KEY | If anthropic / claude provider | Anthropic API key |
GEMINI_API_KEY | If gemini provider | Google Gemini API key |
NVIDIA_API_KEY | If nvidia provider | NVIDIA hosted-inference key (build.nvidia.com / NIM). Billed by NVIDIA. |
NVIDIA_BASE_URL | ✗ | Override the NVIDIA endpoint — e.g. a self-hosted NIM container (http://nim:8000/v1). Defaults to https://integrate.api.nvidia.com/v1. |
VERTEX_ACCESS_TOKEN | If vertex provider | Google Cloud OAuth 2.0 bearer (gcloud auth print-access-token). Tokens expire (~1h). Billed to Google Cloud, not AWS. |
VERTEX_PROJECT_ID | If vertex provider | Google Cloud project id that owns the Vertex AI models. |
VERTEX_LOCATION | ✗ | Vertex AI region (default: us-central1). |
LLM_MODEL | ✗ | Model name override (e.g., gpt-4.1-nano, claude-3-5-haiku-latest, gemini-3.5-flash, meta/llama-3.1-8b-instruct) |
WORKERS_AI_GATEWAY | Workers AI only | CF Workers AI gateway URL |
Provider ↔ billing:
nvidiaandvertexcall external clouds — NVIDIA and Google Cloud respectively — so their usage is not covered by AWS credit.nvidia(or a self-hosted NIM viaNVIDIA_BASE_URL) and MeiliSearch are the pieces that pair naturally with AWS-hosted infrastructure.
Decision model (TypeSafe Jev)
Backs POST /api/v1/ai/decisions: typed noul / choice / score answers with probabilities instead of generated text. Independent of LLM_PROVIDER; unset means the endpoint answers 503 DECISION_NOT_CONFIGURED.
| Variable | Required | Description |
|---|---|---|
DECISION_PROVIDER | ✗ | typesafe (TypeSafe Jev, direct), openrouter (same System One API via OpenRouter, billed to OpenRouter), or llm (reuses LLM_PROVIDER in structured decision mode, no tools; answers are flagged calibrated: false). A configured choice, not an automatic failover. Unset = disabled. |
DECISION_MODEL | ✗ | Model override. Defaults to jev-latest (typesafe) or ~typesafe/jev-latest (openrouter). |
TYPESAFE_API_KEY | If typesafe provider | TypeSafe API key. |
TYPESAFE_BASE_URL | ✗ | TypeSafe endpoint override. Defaults to https://api.typesafe.ai/v1. |
OPENROUTER_API_KEY | If openrouter provider | OpenRouter API key. |
DECISION_TIMEOUT_MS | ✗ | Total deadline per decision in ms, retries and backoff included (default 20000, range 1000–120000). |
DECISION_ATTEMPT_TIMEOUT_MS | ✗ | Timeout of one upstream attempt in ms (default 8000, range 500–120000), capped by what remains of the deadline. |
DECISION_MAX_RETRIES | ✗ | Retries after the first attempt for 429/503/529, network errors and attempt timeouts (default 2, range 0–5). |
DECISION_MAX_INPUT_BYTES | ✗ | UTF-8 byte cap on the serialized state + questions (default 131072). Over the cap → 413 DECISION_INPUT_TOO_LARGE before any provider call. |
DECISION_MAX_INPUT_TOKENS | ✗ | Estimated token budget for the same payload (default 24000). The estimate counts ~4 ASCII chars or 1 non-ASCII code point per token; it is not the provider's tokenizer. |
DECISION_LLM_MAX_OUTPUT_TOKENS | ✗ | llm only: cap on the estimated size of the complete answer (default 4096, range 256–32768), the same on every provider. Over it → 413 DECISION_INPUT_TOO_LARGE before the call. The cap sent upstream is that estimate, at least 256 tokens. |
DECISION_LLM_THINKING_TOKENS | ✗ | llm on Gemini/Vertex only: thinking headroom added to the cap sent upstream, not part of the 413 check (default 1024, range 0–32768). Raise it when DECISION_PARSE_FAILED repeats on Gemini/Vertex; keep the sum of both variables below the model's output limit (an upstream 400 is 422 DECISION_VALIDATION). Headroom is 0 for OpenAI/NVIDIA/Anthropic/Workers AI, whose default models do not reason; a reasoning LLM_MODEL shares the same cap and may fail with DECISION_PARSE_FAILED — not supported in this version. |
DECISION_SITE_REQUESTS_PER_HOUR | ✗ | Platform ceiling on admitted decisions per site per clock hour (default 600, range 0–1000000). Over it → 429 DECISION_QUOTA_EXCEEDED. |
DECISION_SITE_MAX_CONCURRENT | ✗ | Platform ceiling on decisions in flight per site (default 4, range 1–1000). Over it → 429 DECISION_CONCURRENCY_LIMITED. |
DECISION_SITE_TOKENS_PER_DAY | ✗ | Platform ceiling on estimated tokens per site per UTC day, every attempt included (default 2000000, range 0–1000000000). |
DECISION_REVIEW_RETENTION_DAYS | ✗ | Days a draft review run and its feedback are kept before the hourly purge deletes them (default 180, range 1–3650; empty or invalid → default). Review profiles are kept. |
DECISION_REFUSAL_AUDIT_WINDOW_SECONDS | ✗ | Window for aggregating refused (403 FORBIDDEN) decision requests in the audit log (#564): one ai_decision event per site, caller and reason per window, then at counts 10, 100, 1000 … (default 300, range 0–86400; 0 = one event per refusal). The exact total is in lumibase_ai_decision_refusals_total. See Hono API spec — AI decisions. |
Invalid values in these variables are ignored with a warning and the default applies. A site can tighten the three DECISION_SITE_* ceilings, never raise them, through its aiDecisions setting. Decisions are also off for a site until a site admin opts in there (see API spec → Governance).
Email (Resend)
| Variable | Required | Description |
|---|---|---|
RESEND_API_KEY | If email enabled | Resend API key for transactional email |
EMAIL_FROM | If email enabled | Sender address (e.g., [email protected]) |
SCIM provisioning
| Variable | Required | Description |
|---|---|---|
SCIM_TOKEN | If SCIM enabled | Bearer token for /scim/v2/ endpoint authentication |
Pressure limiter (Docker / Node.js)
The Docker CMS process includes an overload guard for the Node.js event loop. When enabled and the process is saturated, API requests fail fast with HTTP 503, a SERVICE_UNAVAILABLE JSON envelope, Retry-After, and X-Lumi-Overload instead of queueing until the container becomes unresponsive. The guard bypasses /health and /metrics by default so operators can still inspect the instance.
| Variable | Required | Default | Description |
|---|---|---|---|
LUMIBASE_PRESSURE_LIMITER_ENABLED | Docker only | true | Enables the Node.js overload guard. Set false only as a temporary mitigation while you scale or optimize the overloaded path. |
LUMIBASE_PRESSURE_LIMITER_SAMPLE_INTERVAL | ✗ | 250 | Sampling interval in milliseconds for event-loop pressure checks. |
LUMIBASE_PRESSURE_LIMITER_MAX_EVENT_LOOP_DELAY | ✗ | 1000 | Maximum observed event-loop delay in milliseconds before API traffic receives 503. Set false to disable this threshold. |
LUMIBASE_PRESSURE_LIMITER_MAX_EVENT_LOOP_UTILIZATION | ✗ | false | Optional utilization threshold such as 0.99. Disabled by default because sustained useful CPU work can otherwise produce noisy rejections. |
LUMIBASE_PRESSURE_LIMITER_RETRY_AFTER | ✗ | 5 | Seconds advertised in the Retry-After response header. |
LUMIBASE_PRESSURE_LIMITER_EXCLUDED_PATHS | ✗ | /health,/metrics | Comma-separated path prefixes that should keep serving during overload checks. |
Rate limiting
A fixed-window throttle guards the authenticated API. It keys per principal (user → API key → IP) and is scoped per site. When exceeded it returns HTTP 429 with a RATE_LIMITED envelope plus X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After. It fails open if the cache is unavailable, so it is defence-in-depth rather than a hard quota.
Large imports can trip the default budget. Raise LUMIBASE_RATE_LIMIT_MAX and prefer the bulk endpoint — see Data import.
| Variable | Required | Default | Description |
|---|---|---|---|
LUMIBASE_RATE_LIMIT_MAX | ✗ | 300 | Max requests per window per principal, per site. |
LUMIBASE_RATE_LIMIT_WINDOW_S | ✗ | 60 | Window length in seconds. |
LUMIBASE_RATE_LIMIT_DISABLED | ✗ | (unset) | Set to true to disable the throttle entirely. |
LUMIBASE_DELIVER_RATE_LIMIT | ✗ | 1200 | Max requests per minute per client IP on the public Delivery API (/api/v1/deliver/*). 0 disables. See Caching — penetration. |
LUMIBASE_AI_IP_RATE_LIMIT | ✗ | 300 | Max requests per minute per client IP per site on /api/v1/ai/*, checked before authentication (#564). Over it → 429 RATE_LIMITED with Retry-After. 0 disables; skipped when the client IP is unknown. Store failure follows LUMIBASE_RATE_LIMIT_FAIL_CLOSED. |
LUMIBASE_NEGATIVE_CACHE_TTL | ✗ | 30 | Tombstone TTL (seconds) for confirmed absences on public read paths, before ±20% jitter. 0 disables. |
Imports
Background collection imports (POST /api/v1/imports, see Data import). The same values apply on Workers (bindings) and Docker (environment).
| Variable | Required | Default | Description |
|---|---|---|---|
IMPORT_TIMEOUT | ✗ | 3600 | Seconds a job may run, from its first step. Past it the job ends as timed_out; rows already written stay. |
IMPORT_MAX_CONCURRENCY | ✗ | 20 | Jobs running at once per site. Further jobs stay queued until one finishes. |
IMPORT_MAX_BYTES | ✗ | 52428800 | Largest accepted upload, in bytes (50 MiB). Larger files get 413 PAYLOAD_TOO_LARGE. |
IMPORT_CHUNK_SIZE | ✗ | 500 | Rows written per step (max 5000). Smaller steps react faster to cancel; larger ones finish sooner. |
GraphQL
Every GraphQL operation is validated before it runs against a depth limit and a static cost limit, rejecting abusively deep or wide queries at parse time (CWE-770). Depth is a compile-time constant (12); cost is tunable. Raise LUMIBASE_GQL_MAX_COST if a legitimate query is rejected. See graphql-api-spec.md.
| Variable | Required | Default | Description |
|---|---|---|---|
LUMIBASE_GQL_MAX_COST | ✗ | 1000 | Max static cost accepted per operation. |
LUMIBASE_GQL_DEFAULT_LIST_SIZE | ✗ | 20 | Cost multiplier for a list field with no literal pagination argument (or a variable one). |
LUMIBASE_GQL_MAX_LIST_MULTIPLIER | ✗ | 100 | Upper clamp on any single list field's cost multiplier. |
Observability
| Variable | Required | Description |
|---|---|---|
PROMETHEUS_ENABLED | Docker only | true to expose /metrics endpoint |
LOG_LEVEL | ✗ | Log level: debug, info, warn, error (default: info) |
LOG_FORMAT | ✗ | json (default) or pretty (local dev) |
Usage telemetry
Anonymous usage telemetry is off by default and has no built-in endpoint. See Activation milestones and usage telemetry for exactly what is sent.
| Variable | Required | Default | Description |
|---|---|---|---|
LUMIBASE_TELEMETRY_ENABLED | ✗ | (unset) | Set true to opt in. Nothing is sent unless LUMIBASE_TELEMETRY_ENDPOINT is also set. |
LUMIBASE_TELEMETRY_ENDPOINT | ✗ | (unset) | URL that receives the events. https: only, or http: to localhost. |
LUMIBASE_TELEMETRY_DISABLED | ✗ | (unset) | Set true to turn telemetry off. Wins over LUMIBASE_TELEMETRY_ENABLED. |
DO_NOT_TRACK | ✗ | (unset) | 1 turns telemetry off, same as LUMIBASE_TELEMETRY_DISABLED. |
Cloudflare Bindings
Configure these in apps/cms/wrangler.toml (not environment variables):
| Binding | Type | Purpose |
|---|---|---|
HYPERDRIVE | Hyperdrive | Pooled PostgreSQL connections |
HYPERDRIVE_SYSTEM | Hyperdrive (optional) | System role (BYPASSRLS) for scheduled/queue handlers and system routes; required with LUMIBASE_DB_RLS=enforce |
CONFIG_CACHE | KV Namespace | Schema, permission, and settings cache |
MEDIA | R2 Bucket | Media/file object storage |
SITE_ROOM | Durable Object | Per-site WebSocket coordination (realtime) |
AI | Workers AI | Workers AI binding for workers-ai LLM provider |
# wrangler.toml excerpt
[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id>"
[[kv_namespaces]]
binding = "CONFIG_CACHE"
id = "<your-kv-namespace-id>"
[[r2_buckets]]
binding = "MEDIA"
bucket_name = "lumibase-media"
[durable_objects]
bindings = [{ name = "SITE_ROOM", class_name = "SiteRoom" }]
Security checklist
Before deploying to production, verify:
-
JWT_SECRETis at least 32 characters and stored as a Wrangler Secret or Docker secret -
LUMIBASE_DEV_AUTHis NOT set totrue -
LUMIBASE_ALLOW_ORG_SIGNUPis enabled only when organization signup is intended - Database credentials are stored as secrets, not in
.envfiles committed to git -
S3_SECRET_ACCESS_KEYis stored as a secret -
RESEND_API_KEYis stored as a secret - CORS is configured to allow only your Studio and consumer domains