Backend environment variables

The backend reads configuration in two ways.

The validated schema. apps/core-api/src/config.ts defines a Zod schema and loadEnv() passes it to defineEnv from @perform/config. defineEnv loads .env with dotenv, validates process.env, prints every failing key to stderr and exits with code 78 when a required value is missing or invalid.
Direct reads in the ported packages. @repo/auth, @repo/payments, @repo/mail, @repo/storage, @repo/utils, @repo/api and @repo/database read process.env themselves. These variables are not validated at startup. A missing value shows up only when the feature runs.

The ESLint rule perform-internal/no-direct-process-env blocks direct reads in apps/ and in the @perform/* packages. It is switched off for the ported @repo/* packages.

The READMEs refer to a .env.example file. The backend repository does not contain one at the time of writing, although .gitignore allows it. This page is the reference. Never commit a real .env.

Validated by `config.ts`

Core

Variable	Required	Default	Purpose
`NODE_ENV`	no	`development`	One of `development`, `test`, `staging`, `production`.
`PORT`	no	`8000`	HTTP port. Local development and all deploy scripts use `3031`, so set it.
`DATABASE_URL`	yes		PostgreSQL connection string.
`REDIS_URL`	yes		Redis connection for BullMQ and the nonce store.
`CORS_ORIGIN`	no	`*`	Comma-separated list of allowed origins for the Express CORS middleware.
`PUBLIC_API_URL`	no	`http://localhost:8000`	Public base URL of this API. Used to build the SmartSend webhook callback URL.
`APP_WEB_URL`	no	production web URL	Origin of the coach web app, used to build links in partner API payloads.

Rate limiting

Variable	Required	Default	Purpose
`RATE_LIMIT_WINDOW_MS`	no	`60000`	Window length for both limiters.
`RATE_LIMIT_MAX`	no	`120`	Requests per window on `/v1` and `/mcp`, counted per client address.
`RATE_LIMIT_WEB_MAX`	no	`600`	Signed web lane requests per window, counted per user and studio.

Authentication

Variable	Required	Default	Purpose
`BETTER_AUTH_URL`	yes		Base URL of the better-auth instance. Must be a valid URL. Used by the HTTP session verifier.
`BETTER_AUTH_SECRET`	yes		At least 16 characters. The better-auth secret. Also signs the trainee session token.
`SESSION_VERIFY_INPROCESS`	no	`false`	`true` or `1` makes the bearer lane verify sessions with `auth.api.getSession` in process instead of an HTTP call to `BETTER_AUTH_URL`.
`SERVICE_AUTH_SECRET`	yes		At least 16 characters. Shared HMAC secret for the web lane and service calls. Must match the web app.
`TRAINEE_OTP_DEV_MODE`	no	`false`	When on, login codes are logged and returned as `devCode` instead of being sent over WhatsApp. Never enable in production.
`TRAINEE_REVIEW_PHONE`	no	set in `config.ts`	Phone number whose trainee login accepts a fixed code. Exists for app store review.
`TRAINEE_REVIEW_CODE`	no	set in `config.ts`	The fixed code for the review phone. An empty value disables it.

Trainee app update prompt

Variable	Required	Default	Purpose
`TRAINEE_APP_IOS_VERSION`	no	empty	Newest version live in the App Store. The app prompts for an update when its own version is older. Empty turns the prompt off.
`TRAINEE_APP_ANDROID_VERSION`	no	empty	Same for Google Play.
`TRAINEE_APP_IOS_STORE_URL`	no	App Store listing	Link the prompt opens on iOS.
`TRAINEE_APP_ANDROID_STORE_URL`	no	Play Store listing	Link the prompt opens on Android.

WhatsApp (SmartSend)

Variable	Required	Default	Purpose
`SMARTSEND_BASE_URL`	yes		SmartSend API base URL.
`SMARTSEND_API_KEY`	no	empty	Fallback key. Each studio normally stores its own key in `Studio.settings`.
`SMARTSEND_OTP_API_KEY`	no	empty	Key of the number that sends login codes.
`SMARTSEND_WEBHOOK_SECRET`	no	empty	Token checked on inbound webhooks. When empty, inbound webhooks are rejected.

AI

Variable	Required	Default	Purpose
`OPENAI_API_KEY`	no	empty	Key for meal analysis, form summaries and import formatting.
`OPENAI_NUTRITION_MODEL`	no	`gpt-4o`	Model for meal photo and text analysis.
`OPENAI_FORM_SUMMARY_MODEL`	no	`gpt-4o-mini`	Model for form summaries.
`OPENAI_NUTRITION_LOOKUP_MODEL`	no	`gpt-4o-mini`	Model for the nutrition lookup fallback.
`OPENAI_IMPORT_MODEL`	no	empty	Model for the AutoFit import passes. Empty falls back to `OPENAI_NUTRITION_MODEL`.
`ANTHROPIC_API_KEY`	no	empty	Key for the WhatsApp assistant.
`ANTHROPIC_WORKSPACE_ID`	no	empty	Needed when the Anthropic key is organisation wide instead of workspace scoped.
`AGENT_MODEL`	no	`claude-sonnet-5`	Model the assistant uses.
`AGENT_SMARTSEND_API_KEY`	no	empty	SmartSend key of the dedicated assistant number. Empty disables the assistant.
`AGENT_PILOT_PHONES`	no	empty	Comma-separated coach phones allowed during the pilot. Empty opens the assistant to every registered coach.
`AGENT_PHONE_COACHES`	no	empty	`phone=coachId` pairs, comma separated. Pins a number to one coach before the phone lookup.

Storage and uploads

Variable	Required	Default	Purpose
`R2_ENDPOINT`	no	empty	S3-compatible endpoint.
`R2_REGION`	no	`auto`	Region.
`R2_ACCESS_KEY_ID`	no	empty	Access key id.
`R2_SECRET_ACCESS_KEY`	no	empty	Secret key.
`R2_BUCKET_NAME`	no	empty	Bucket name.
`R2_PUBLIC_BASE_URL`	no	empty	Public base URL that serves stored objects.
`R2_PATH_PREFIX`	no	empty	Key prefix inside the bucket.
`UPLOAD_SERVER_URL`	no	set in `config.ts`	Legacy upload server endpoint.
`UPLOAD_SERVER_ACCESS_TOKEN`	no	empty	Token for the legacy upload server.

Imports and misc

Variable	Required	Default	Purpose
`AUTOFIT_MASTER_KEY`	no	empty	AutoFit Coach Data Export key. Server side only. Never entered by studios.
`AUTOFIT_IMPORT_MASTER_CODE`	no	empty	Ops-only code that passes the import wizard’s phone verification. Empty disables it.
`AUTOFIT_MINUTE_BUDGET`	no	`50`	Export requests per minute the import worker paces itself to.
`WAITLIST_WEBHOOK_URL`	no	set in `config.ts`	Webhook that receives landing page waitlist leads.

Read directly by packages

These are not in the schema. Set them when you use the feature.

`@repo/auth`

Variable	Purpose
`NEXT_PUBLIC_SAAS_URL`	Public URL of the web app. Used as the auth base URL and trusted origin. Also read by `@repo/api`, `@repo/notifications` and `@repo/utils`.
`AUTH_TRUSTED_ORIGINS`	Extra comma-separated origins trusted by auth and CORS. Useful for reaching a dev server over a LAN address.
`CORE_API_URL`	Base URL the auth lifecycle hooks call back into (`/v1/lifecycle/...` and coach provisioning). In practice this is the API’s own URL.
`CORE_API_SERVICE_ID`	Service id used when signing those calls. Use `web`, the only id registered in `serviceSecrets`.
`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`	Google sign-in.
`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`	GitHub sign-in.

@repo/auth also reads SERVICE_AUTH_SECRET, SMARTSEND_BASE_URL, SMARTSEND_API_KEY, SMARTSEND_OTP_API_KEY and TRAINEE_OTP_DEV_MODE directly.

`@repo/payments`

Variable	Purpose
`POLAR_ACCESS_TOKEN`	Polar API token.
`POLAR_WEBHOOK_SECRET`	Secret that verifies Polar webhooks on `/api/webhooks/payments`.
`POLAR_SERVER`	`sandbox` selects the Polar sandbox. Any other value, or none, selects production.
`PRICE_ID_START_MONTHLY`, `PRICE_ID_GROW_MONTHLY`, `PRICE_ID_PRO_MONTHLY`, `PRICE_ID_ELITE_MONTHLY`, `PRICE_ID_ENTERPRISE_MONTHLY`	Product ids of the monthly studio plans.
`PRICE_ID_SOLO_V2`, `PRICE_ID_START_V2`, `PRICE_ID_GROW_V2`, `PRICE_ID_PRO_V2`, `PRICE_ID_ELITE_V2`, `PRICE_ID_ENTERPRISE_V2`	Product ids of the second generation of plans.
`PRICE_ID_TEAM_SEAT`	Product id of the extra team seat.
`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`	Only for the Stripe provider, which is present in the package but is not the provider wired for production deploys.

`@repo/mail`

The provider exported from packages/mail/src/provider/index.ts is ZeptoMail. The other provider files remain in the package but are not exported.

Variable	Purpose
`ZEPTOMAIL_TOKEN`	ZeptoMail send token.
`ZEPTOMAIL_API_URL`	Override for the ZeptoMail API URL.
`MAIL_FROM`	Sender address.
`MAIL_HOST`, `MAIL_PORT`, `MAIL_USER`, `MAIL_PASS`	Nodemailer provider, unused by default.
`RESEND_API_KEY`, `POSTMARK_SERVER_TOKEN`, `PLUNK_API_KEY`, `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`	Other providers, unused by default.

`@repo/storage`

Reads the R2_* variables above. For each one it falls back to the older S3_ENDPOINT, S3_REGION, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY names. NEXT_PUBLIC_AVATARS_BUCKET_NAME names the avatars bucket.

Prisma CLI

Variable	Purpose
`DATABASE_URL`	Read by both `prisma.config.ts` files and by the runtime client.
`DIRECT_URL`	Optional. `packages/db/prisma.config.ts` uses it for migrations. When unset it derives one from `DATABASE_URL` by removing `-pooler.` from the host, so migrations bypass a connection pooler.

MCP stdio server (`apps/mcp-server`)

This binary runs on a coach’s machine, not on the server.

Variable	Purpose
`PERFORM_API_KEY`	Required. A studio API key created in the web app.
`PERFORM_API_URL`	Optional. Defaults to the production API.

One-off scripts

Scripts under apps/core-api/src/scripts and packages/database/scripts validate their own small schemas. Examples are RAPIDAPI_KEY, ASCENDAPI_HOST and ASCENDAPI_BASE_URL for the exercise catalog import, plus flags such as APPLY, LIMIT, ONLY, STUDIO_SLUG and CONCURRENCY that individual scripts document at the top of the file. They are not needed to run the API.

Variables that appear in old env files but are not read

GREEN_API_BASE_URL, GREEN_API_INSTANCE_ID and GREEN_API_TOKEN are listed in older docs and env files. No code in apps/ or packages/ reads them. You can leave them out.

Rules

Add a new variable to the schema in config.ts so it is validated at boot, and give it a safe default when the feature is optional.
Read it from ctx.env in modules. Do not read process.env in apps/core-api.
Never give a secret a real default in code.
NEXT_PUBLIC_SAAS_URL keeps its Next.js style name in the backend because the ported packages still read it under that name.

​Validated by config.ts

​Core

​Rate limiting

​Authentication

​Trainee app update prompt

​WhatsApp (SmartSend)

​AI

​Storage and uploads

​Imports and misc

​Read directly by packages

​@repo/auth

​@repo/payments

​@repo/mail

​@repo/storage

​Prisma CLI

​MCP stdio server (apps/mcp-server)

​One-off scripts

​Variables that appear in old env files but are not read

​Rules

Validated by `config.ts`

Core

Rate limiting

Authentication

Trainee app update prompt

WhatsApp (SmartSend)

AI

Storage and uploads

Imports and misc

Read directly by packages

`@repo/auth`

`@repo/payments`

`@repo/mail`

`@repo/storage`

Prisma CLI

MCP stdio server (`apps/mcp-server`)

One-off scripts

Variables that appear in old env files but are not read

Rules