Environment Variables

Environment variables override overlay.config.json. Put secrets in the runtime secret manager; keep JSON config focused on non-secret deployment shape.

Base Runtime

Variable	Required when	Notes
`NEXT_PUBLIC_APP_URL`	Deployed environments	Public browser URL for the web app.
`NEXT_PUBLIC_CONVEX_URL`	App talks to Convex	Public Convex deployment URL for the selected environment.
`DEV_NEXT_PUBLIC_CONVEX_URL`	Local dev with separate dev backend	Preferred for local work against the development Convex deployment.
`OVERLAY_CONFIG_FILE`	JSON runtime config	Absolute or repo-relative path, usually `overlay.config.json`; Docker mounts it at `/app/overlay.config.json`.
`INTERNAL_API_SECRET`	Always	Shared app-to-Convex secret. The matching Convex deployment must have the same value.
`INTERNAL_SERVICE_AUTH_SECRET`	App runtime only	Internal service auth secret. Do not put this in Convex.
`SESSION_SECRET`	Cookie sessions	Long, random, environment-specific app secret.
`SESSION_TRANSFER_KEY`	Native/session transfer flows	App runtime only.
`SESSION_COOKIE_ENCRYPTION_KEY`	Encrypted session cookie payloads	App runtime only.
`API_KEY_HASH_SECRET`	`apiKeys` enabled	HMAC pepper for API key hashes.

Provider Variables

Provider family	Variables
WorkOS auth	`WORKOS_CLIENT_ID`, `WORKOS_API_KEY`; dev fallback uses `DEV_WORKOS_CLIENT_ID`, `DEV_WORKOS_API_KEY`.
Better Auth	`BETTER_AUTH_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_DATABASE_URL`, optional `BETTER_AUTH_DEFAULT_SSO_`, `BETTER_AUTH_OIDC_`, `BETTER_AUTH_JWT_*`, and `BETTER_AUTH_JWKS_URL`.
OIDC auth	`OIDC_ISSUER_URL`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_AUDIENCE`. Use these variables for Keycloak-compatible realm issuers too.
Stripe billing	`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PAID_UNIT_PRICE_ID`, `STRIPE_TOPUP_UNIT_PRICE_ID`, `STRIPE_PORTAL_CONFIGURATION_ID`; dev fallback uses `DEV_STRIPE_SECRET_KEY`, `DEV_STRIPE_WEBHOOK_SECRET`.
R2 storage	`R2_ACCOUNT_ID`, `R2_BUCKET_NAME`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `S3_API`.
S3-compatible storage	`S3_BUCKET_NAME`, `S3_REGION`, `S3_ENDPOINT_URL`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_FORCE_PATH_STYLE`.
Models	`OPENROUTER_API_KEY`, `AI_GATEWAY_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GROQ_API_KEY`, `LLM_API_KEY_ENV_VAR`, `DEFAULT_CHAT_MODEL_ID`, `LLM_MODEL_ALLOWLIST`.
Integrations and provider keys	`PROVIDER_KEYS_SECRET`, `HOOKS_TOKEN_SALT`.
Telemetry	`NEXT_PUBLIC_POSTHOG_TOKEN`, `NEXT_PUBLIC_POSTHOG_HOST`, `SENTRY_DSN`, `NEXT_PUBLIC_SENTRY_DSN`, `SENTRY_AUTH_TOKEN`.
Docs hosting	`MINTLIFY_DOCS_URL`, used at build time for Vercel rewrites from `/docs` and `docs.getoverlay.io` to Mintlify.

Private Deployment Defaults

For private deployments, disable unapproved processors in both server and client-visible env:

OVERLAY_FEATURE_INTEGRATIONS=false
OVERLAY_FEATURE_BROWSER_USE=false
OVERLAY_FEATURE_SANDBOXES=false
OVERLAY_FEATURE_WEB_SEARCH=false
OVERLAY_FEATURE_ANALYTICS=false
OVERLAY_FEATURE_ERROR_REPORTING=false
NEXT_PUBLIC_OVERLAY_FEATURE_ANALYTICS=false
NEXT_PUBLIC_OVERLAY_FEATURE_ERROR_REPORTING=false

OVERLAY_PROVIDER_INTEGRATIONS=none
OVERLAY_PROVIDER_BROWSER=none
OVERLAY_PROVIDER_SANDBOX=none
OVERLAY_PROVIDER_WEB_SEARCH=none
OVERLAY_PROVIDER_ANALYTICS=none
OVERLAY_PROVIDER_ERROR_REPORTING=none

Convex Placement

Convex needs only the secrets used by Convex functions. For the normal web path, configure:

INTERNAL_API_SECRET, matching the app runtime.

Session and crypto secrets belong only on the Next.js app runtime:

SESSION_SECRET
SESSION_TRANSFER_KEY
SESSION_COOKIE_ENCRYPTION_KEY
INTERNAL_SERVICE_AUTH_SECRET

After editing convex/, push both deployments:

npm run convex:push:all

Do not pass .env.local to production Convex deploy commands; use the package scripts so production and development deployments receive the right environment.

​Base Runtime

​Provider Variables

​Private Deployment Defaults

​Convex Placement

Base Runtime

Provider Variables

Private Deployment Defaults

Convex Placement