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`	Convex app-data provider	Shared app-to-Convex secret. It is not required by a Postgres-only deployment.
`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`, `BETTER_AUTH_JWT_ISSUER`, `BETTER_AUTH_JWT_AUDIENCE`, `BETTER_AUTH_JWKS_URL`, and one connection registry using `BETTER_AUTH_CONNECTION_ID`, `BETTER_AUTH_CONNECTION_PRESET`, `BETTER_AUTH_CONNECTION_LABEL`, `BETTER_AUTH_CONNECTION_DOMAINS`, and the applicable connection client/issuer variables. See Authentication. Legacy `BETTER_AUTH_DEFAULT_SSO_` and `BETTER_AUTH_OIDC_` variables exist for migration compatibility but must not be mixed with the connection registry.
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`.
Transactional email	`OVERLAY_EMAIL_PROVIDER` (`resend`, `ses`, `smtp`, or `none`), `OVERLAY_EMAIL_FROM`, and optional `OVERLAY_EMAIL_REPLY_TO`. Resend uses `RESEND_API_KEY` (or `OVERLAY_EMAIL_RESEND_API_KEY`). SES uses `OVERLAY_EMAIL_SES_ACCESS_KEY_ID`, `OVERLAY_EMAIL_SES_SECRET_ACCESS_KEY`, `OVERLAY_EMAIL_SES_SESSION_TOKEN`, `OVERLAY_EMAIL_SES_REGION`, and `OVERLAY_EMAIL_SES_CONFIGURATION_SET`. SMTP uses `OVERLAY_EMAIL_SMTP_HOST`, `OVERLAY_EMAIL_SMTP_PORT`, `OVERLAY_EMAIL_SMTP_SECURE`, `OVERLAY_EMAIL_SMTP_USERNAME`, and `OVERLAY_EMAIL_SMTP_PASSWORD`.
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`, and optionally `S3_ENDPOINT_URL`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_FORCE_PATH_STYLE`. AWS task and instance roles work with both key variables omitted; otherwise configure both together.
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
OVERLAY_FEATURE_TRANSACTIONAL_EMAIL=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
OVERLAY_EMAIL_PROVIDER=none

Backend-specific placement

When the app-data provider is Convex, configure:

INTERNAL_API_SECRET, matching the app runtime.
If transactional email is enabled, the same OVERLAY_EMAIL_* provider, sender, and provider-credential values used by the app runtime. Convex owns the durable delivery action for this backend.

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. When the app-data provider is Postgres, omit NEXT_PUBLIC_CONVEX_URL, DEV_NEXT_PUBLIC_CONVEX_URL, CONVEX_DEPLOYMENT, and INTERNAL_API_SECRET. Use OVERLAY_DATABASE_URL for application data and BETTER_AUTH_DATABASE_URL for Better Auth. They must use separate databases, roles, and migration lifecycles. Postgres deployments deliver the same outbox through the supervised npm run app-db:worker process. Keep OVERLAY_EMAIL_PROVIDER=none to disable all Overlay transactional email. WorkOS or the selected IdP remains responsible for verification and password-reset messages in every mode. Convex-backed deployments run transactional delivery from convex/crons.ts, so the selected provider variables must also exist in the matching Convex deployment; setting them only on Vercel does not configure the Convex email worker.

Start

Desktop

Configure

Develop

Deploy & Operate

API Reference

Legal

Changelog

Help

Environment Variables

Base Runtime

Provider Variables

Private Deployment Defaults

Backend-specific placement

​Base Runtime

​Provider Variables

​Private Deployment Defaults

​Backend-specific placement

Base Runtime

Provider Variables

Private Deployment Defaults

Backend-specific placement