Environment variable reference

Every variable the ErmisAI application reads, grouped by concern, with its default and what happens when it is unset. Paths are relative to the app repository root (the directory is named hermesai; the package is ermisai).

Most of the failure modes here are silent. A missing key rarely crashes the build — it turns a capability off while pnpm build, pnpm typecheck and pnpm test all stay green. That is why every table below carries a "when unset" column.

The ten launch-critical keys

src/lib/platform/launch-readiness.ts:28-103 declares ten entries whose absence fails silently in a deployed environment. They are reported by GET /api/health under config, and printed once to stderr at boot by src/instrumentation.ts (Node runtime, deployed environments only), starting with:

[launch-readiness] WARNING: launch-critical environment variables are unset in this deployed
environment. These fail SILENTLY (build/typecheck/tests stay green while the capability is off):

config.ready is true only when missing is empty. It does not change the HTTP status — /api/health still returns 200 with config.ready: false (src/app/api/health/route.ts:144-149). It is a go-public gate you have to read, not an alarm.

Precedence rules that surprise people

1. Persisted admin config beats env seeds. ERMIS_AI_GUARDRAILS_MODE, ERMIS_AI_METERING_ENABLED, ERMIS_AI_PAUSED, ERMIS_SIGNUPS_PAUSED, ERMIS_WAITLIST_ENABLED, ERMIS_PLATFORM_AI_*_CAP_CENTS, the per-stage model variables, ERMIS_ALLOW_CHAT_MODEL_OVERRIDE, ERMIS_CHAT_STREAM_MODE, ERMIS_AI_REASONING_EFFORT and ERMIS_AI_DEEPSEEK_FLASH_REASONING seed the AI runtime config only on a fresh state store (src/lib/platform/ai-runtime-config.ts:515-588). Once an operator has written platform:admin:ai-runtime-config through PUT /api/admin/ai/config, changing the env var and redeploying does nothing.
2. ERMIS_AI_PROVIDER_MODE is the one exception — it beats the database. normalizeProviderMode re-applies the env value on every normalize pass (src/lib/platform/ai-runtime-config.ts:132-141). Setting it in Vercel makes the provider-mode dropdown on /admin/ai cosmetically settable but functionally inert.
3. ERMIS_MODEL_OVERRIDE beats everything, including per-stage models and per-request model selection. It is validated only for provider-prefix support, not against the model catalog (src/lib/ai/providers.ts:99-112).
4. ERMIS_FORCE_INMEMORY_STORE is inert whenever VERCEL_ENV is set — production and preview (src/lib/platform/shared/persistence.ts:16-22). It is a local-only switch.

App URLs and origins

Clerk

@clerk/nextjs reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY itself — they do not appear in a process.env read anywhere in src/, but the app cannot boot without them. ErmisAI ships no auth form of its own.

There is no NEXT_PUBLIC_CLERK_WAITLIST_URL — the waitlist URL is set in code (src/components/layout/ClerkAppProvider.tsx:22).

Postgres

CapyDB port convention: :6432 pooled for the app runtime, :5432 direct for DDL only.

Production has no in-memory fallback for shared state. If platform_state is unreachable or unmigrated, every authenticated surface 503s and /api/health reports database.migrated: false with the detail "platform_state unreachable (run db:migrate before serving traffic)".

If a connection string fails to parse and contains REDIS_URL= or UPSTASH_REDIS_, the error adds "appears to contain another environment variable. Check for a missing newline in your env file." (src/lib/db/client.ts:81-89) — a missing newline in .env is the usual cause.

Object storage

Provider selection (src/lib/storage/object-storage.ts:101-117): explicit OBJECT_STORAGE_PROVIDER wins; otherwise Supabase if a Supabase URL and service-role key are both present; otherwise Vercel Blob if BLOB_READ_WRITE_TOKEN or BLOB_STORE_ID is present; otherwise null.

Redis (Upstash)

Redis holds rate limits, AI guardrail windows, the AI ledger retry queue and DLQ, the feed build lock and short caches. It is never application state. Without it: edge rate limiting fails open, guardrail windows fall back to a per-process counter that is not cross-instance coherent, the in-flight spend reservation is skipped, and the ledger retry queue cannot enqueue at all.

Billing (Polar)

Product id mapping — first non-empty wins per plan (src/lib/db/billing-repository.ts:294-306). Duplicate ids across plans throw at seed time.

A plan with no product id cannot be checked out — the route returns 409 POLAR product mapping missing for plan <id>.

Email (Resend)

pnpm email:campaign runs node --env-file=.env.production, so it reads .env.production, not .env (package.json).

Security and operational secrets

CLERK_WEBHOOK_SIGNING_SECRET, POLAR_WEBHOOK_SECRET and RESEND_WEBHOOK_SECRET are listed with their own subsystems above. All three receivers return 503 when their secret is missing, not 401 — a missing secret is a configuration fault, not an authentication failure.

AI provider and credentials

Azure deployments are otherwise managed at runtime through the admin Azure model registry, which needs no redeploy.

AI model selection

All of these are seed defaults for the persisted runtime config, except ERMIS_MODEL_OVERRIDE.

The mode default is openai/gpt-5-mini in gateway mode and azure/gpt-5.4-mini in azure mode. Out of the box all four stages use that same model — there is no distinct shipped model per stage.

AI policy and behaviour

Guardrails, metering and spend

Ingestion pipeline tuning

All optional, all read once at module init, all clamped to the bounds below. Values outside the range are silently clamped, not rejected (src/lib/services/rss-aggregation.ts:110-244).

Kill switches and operator brakes

Localization

ERMIS_CONTENT_LOCALE is read by the code and documented in README.md but is not present in .env.example.

Readiness attestations

Operator checkboxes expressed as environment variables, surfaced in GET /api/admin/ai/usage under operationalReadiness and rendered on /admin/ai. They attest to something; they verify nothing.

The names are generated as ERMIS_${PROVIDER_UPPERCASE}_${SPEND_ALERTS|DPA}_CONFIRMED (src/app/api/admin/ai/usage/route.ts:51-57).

Public marketing configuration

Every value here is NEXT_PUBLIC_, so it is inlined into the client bundle at build time. Changing one needs a redeploy.

getBestAvailableEmail() falls through the six addresses in the order general → sales → partnerships → privacy → security → careers, so one address set keeps most pages functional. When all six are unset, the affected rows degrade to muted non-actionable text with no fallback channel.

Sentry

Platform-injected values

Set by Vercel, not by you. Listed because the code branches on them.

Read by the code but not in .env.example

These are read at runtime and have no line in the committed example file:

README.md additionally omits ERMIS_AI_GUARDRAILS_MODE, ERMIS_AI_METERING_ENABLED, ERMIS_AI_PAUSED, ERMIS_AI_REASONING_EFFORT, ERMIS_AI_DEEPSEEK_FLASH_REASONING, ERMIS_AI_EXPERIMENTAL_MODELS, ERMIS_AI_INFLIGHT_RESERVE_CENTS, ERMIS_USD_TO_EUR_RATE, ERMIS_PLATFORM_AI_{DAILY,MONTHLY}_CAP_CENTS, ERMIS_CHAT_MODEL, ERMIS_CLUSTER_MODEL, ERMIS_SYNTHESIS_MODEL, ERMIS_ALLOW_CHAT_MODEL_OVERRIDE, ERMIS_CHAT_STREAM_MODE, ERMIS_DISABLE_COMPOSE_CACHE, AI_GATEWAY_BASE_URL, AZURE_BYOK_TIMEOUT_MS, AZURE_GPT_4_1_NANO_DEPLOYMENT, AZURE_CHAT_DEPLOYMENT and AZURE_EMBEDDING_DEPLOYMENT, all of which are in .env.example.

Declared but read nowhere

Do not spend time provisioning these:

• NEXT_PUBLIC_SUPABASE_ANON_KEY and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY — present in .env.example and in the test neutralization list, but no read exists under src/ or scripts/.
• DATABASE_DIRECT_URL and DATABASE_POOL_URL — these names appear in some local .env files but no application code reads them. The app reads DATABASE_URL, SUPABASE_DATABASE_URL and MIGRATIONS_DATABASE_URL.

Checking what a live deployment actually has

.env.production is gitignored and Vercel does not read it. The only authoritative answer for a running deployment is the health endpoint:

curl -s https://ermisai.com/api/health | jq

It returns, anonymously and with Cache-Control: no-store:

• config.ready, config.missing[] and config.entries[] — the launch-critical key names and whether each is present. Values are never returned.
• controls — aiGuardrailsMode, aiPaused, signupsPaused, waitlistEnabled, platformDailySpendCapCents, platformMonthlySpendCapCents. These come from the persisted runtime config, so this is the only way to see whether an env seed was ever superseded.
• checks.database including migrated, and checks.redis (not_configured when no Upstash credentials are present).

HTTP 200 when the database check passes, 503 otherwise. Redis degradation does not fail readiness, and neither does config.ready: false.

Local minimum

To boot pnpm dev you need Clerk plus one of two storage choices — that is all:

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY
• either DATABASE_URL, or ERMIS_FORCE_INMEMORY_STORE=true

Polar, Resend, Upstash, Sentry and an AI provider are all optional for a first run. Note that src/lib/email/resend.ts throws at import when RESEND_API_KEY is missing, so any code path that touches email will fail until you set it.