Configuration and env loading

Two ways env is read

There are two patterns in the repo and you need to know which one a file uses.

Where	How it reads env	Validation
`apps/core-api` and `@perform/*` packages	`ctx.env`, built by `loadEnv()` from `config.ts`	Zod schema, process exits on failure
`@repo/*` packages (`auth`, `api`, `payments`, `mail`, `storage`, `database`, `notifications`, `utils`)	`process.env.X` directly	Mostly none. A missing value fails at first use.

The ESLint rule perform-internal/no-direct-process-env blocks process.env everywhere except packages/config and the ported @repo/* directories, which are exempted in eslint.config.mjs. apps/mcp-server disables the rule in its one file because it runs on a coach’s machine with two variables.

defineEnv

@perform/config exports one function:

export function defineEnv<TSchema extends ZodType>(schema: TSchema): ReturnType<TSchema['parse']>

It loads .env once with dotenv, runs schema.safeParse(process.env), and on failure writes one line per issue to stderr and calls process.exit(78). apps/core-api/src/config.ts wraps it:

export type Env = z.infer<typeof schema>;
export const loadEnv = (): Env => defineEnv(schema);

load-env.ts calls loadEnv() as a side effect so the first import in server.ts validates the environment before any other module is evaluated. Booleans are strings in env. The schema converts them with value === 'true' || value === '1'.

Core API schema

Every variable below is in apps/core-api/src/config.ts. “Required” means the schema has no default.

Server and infrastructure

Variable	Required	Default	Purpose
`NODE_ENV`	no	`development`	One of `development`, `test`, `staging`, `production`.
`PORT`	no	`8000`	HTTP port. Also used by the MCP route to call the API on loopback.
`DATABASE_URL`	yes		PostgreSQL connection string.
`REDIS_URL`	yes		Redis for BullMQ, nonces, OTP and caches.
`CORS_ORIGIN`	no	`*`	Comma separated list of origins for the Express `cors` middleware.
`PUBLIC_API_URL`	no	`http://localhost:8000`	Public base URL of this API. Used to build the SmartSend inbound webhook URL.
`APP_WEB_URL`	no	the production web app origin	Coach web app origin, used to build links in partner payloads, form links and team invitation emails.

Rate limits

Variable	Default	Purpose
`RATE_LIMIT_WINDOW_MS`	`60000`	Window for both limiters.
`RATE_LIMIT_MAX`	`120`	Requests per window per IP on `/v1` (not `/v1/web`) and `/mcp`.
`RATE_LIMIT_WEB_MAX`	`600`	Requests per window per studio and user on `/v1/web`.

Auth

Variable	Required	Default	Purpose
`BETTER_AUTH_URL`	yes		Base URL of the better-auth handler. Used by the HTTP session verifier on the bearer lane.
`BETTER_AUTH_SECRET`	yes (min 16 chars)		better-auth secret. Also the HMAC key for trainee session tokens.
`SESSION_VERIFY_INPROCESS`	no	`false`	When true the bearer lane verifies sessions by calling `auth.api.getSession` in process instead of over HTTP.
`SERVICE_AUTH_SECRET`	yes (min 16 chars)		HMAC secret for the `web` service id.

Variable	Default	Purpose
`SMARTSEND_BASE_URL`	required	SmartSend API base URL.
`SMARTSEND_API_KEY`	empty	Global fallback key.
`SMARTSEND_OTP_API_KEY`	empty	Key of the org that sends OTP templates. Falls back to `SMARTSEND_API_KEY`.
`SMARTSEND_WEBHOOK_SECRET`	empty	Token compared against `?token=` on inbound webhooks. Empty rejects every webhook.
`TRAINEE_OTP_DEV_MODE`	`false`	Skips the WhatsApp send and returns the code in the response.
`TRAINEE_REVIEW_PHONE`, `TRAINEE_REVIEW_CODE`	set in `config.ts`	A fixed phone and code pair accepted by `verify-otp` for app store review. Setting either to empty turns the bypass off.
`TRAINEE_APP_IOS_VERSION`, `TRAINEE_APP_ANDROID_VERSION`	empty	Newest store version per platform. Empty turns the update prompt off.
`TRAINEE_APP_IOS_STORE_URL`, `TRAINEE_APP_ANDROID_STORE_URL`	store links	Where the update prompt sends the trainee.
`WAITLIST_WEBHOOK_URL`	set in `config.ts`	Receives every landing page waitlist lead. Empty disables forwarding.

config.ts ships real default values for TRAINEE_REVIEW_PHONE, TRAINEE_REVIEW_CODE and WAITLIST_WEBHOOK_URL. A deployment that does not override them inherits a working login bypass for that phone number. Override or blank them per environment.

AI

Variable	Default	Used by
`OPENAI_API_KEY`	empty	All OpenAI helpers. Empty disables them.
`OPENAI_NUTRITION_MODEL`	`gpt-4o`	Meal analysis, recipe generation, program generation.
`OPENAI_NUTRITION_LOOKUP_MODEL`	`gpt-4o-mini`	Web search lookup for foods not in the library.
`OPENAI_FORM_SUMMARY_MODEL`	`gpt-4o-mini`	Form response summaries and nutrition insight.
`OPENAI_IMPORT_MODEL`	empty	AutoFit import passes. Empty uses `OPENAI_NUTRITION_MODEL`.
`ANTHROPIC_API_KEY`	empty	Assistant, WhatsApp agent, plan import, forms AI, check-in insights.
`ANTHROPIC_WORKSPACE_ID`	empty	Sent as the `anthropic-workspace-id` header when set.
`AGENT_MODEL`	`claude-sonnet-5`	Model for every Anthropic feature.
`AGENT_SMARTSEND_API_KEY`	empty	SmartSend org key of the WhatsApp agent number. Empty disables the agent.
`AGENT_PILOT_PHONES`	empty	Comma separated coach phones allowed to use the agent. Empty allows every registered coach.
`AGENT_PHONE_COACHES`	empty	`phone=coachId` pairs that pin a number to one coach row.

See AI features.

Storage

Variable	Default	Purpose
`R2_ENDPOINT`, `R2_REGION`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`	empty (`R2_REGION` is `auto`)	S3 compatible bucket. With any of them missing `storage.configured` is false and uploads answer `INTERNAL`.
`R2_PUBLIC_BASE_URL`	empty	Public URL prefix written into stored file URLs.
`R2_PATH_PREFIX`	empty	Optional key prefix inside the bucket.
`UPLOAD_SERVER_URL`, `UPLOAD_SERVER_ACCESS_TOKEN`	set in `config.ts`, empty	Declared in the schema. No code under `apps/core-api/src` reads them.

AutoFit import

Variable	Default	Purpose
`AUTOFIT_MASTER_KEY`	empty	Export key for the AutoFit Coach Data Export API. Server side only.
`AUTOFIT_IMPORT_MASTER_CODE`	empty	Operations code that passes the import wizard’s phone verification. Empty disables it.
`AUTOFIT_MINUTE_BUDGET`	`50`	Export requests per minute the client paces itself to.

Variables read by @repo packages

These are not in the Zod schema. They are read with process.env inside the package that needs them.

Package	Variables
`@repo/auth`	`NEXT_PUBLIC_SAAS_URL` (base URL and trusted origin), `AUTH_TRUSTED_ORIGINS`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `SMARTSEND_BASE_URL`, `SMARTSEND_OTP_API_KEY`, `SMARTSEND_API_KEY`, `TRAINEE_OTP_DEV_MODE`, `CORE_API_URL`, `CORE_API_SERVICE_ID`, `SERVICE_AUTH_SECRET`
`@repo/api`	`NEXT_PUBLIC_SAAS_URL`. `lib/backend-config.ts` also defines `BACKEND_URL`, `BACKEND_SERVICE_SECRET` and `BACKEND_LIFECYCLE_SECRET` and throws at import if they are missing, but only `lib/backend-client.ts` imports it.
`@repo/payments`	`POLAR_ACCESS_TOKEN`, `POLAR_WEBHOOK_SECRET`, `POLAR_SERVER` (`sandbox` or production), `PRICE_ID_START_V2` and the other `PRICE_ID__V2` overrides, `PRICE_ID_START_MONTHLY` and the other legacy `PRICE_ID__MONTHLY` ids, `PRICE_ID_TEAM_SEAT`. The Stripe provider file reads `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` but is not exported.
`@repo/mail`	`MAIL_FROM`, `ZEPTOMAIL_TOKEN`, `ZEPTOMAIL_API_URL` (optional)
`@repo/storage`	`R2_ENDPOINT` or `S3_ENDPOINT`, `R2_REGION` or `S3_REGION`, `R2_ACCESS_KEY_ID` or `S3_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` or `S3_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME` or `NEXT_PUBLIC_AVATARS_BUCKET_NAME`, `R2_PUBLIC_BASE_URL`, `R2_PATH_PREFIX`
`@repo/database`	`DATABASE_URL`, `NODE_ENV`
`@repo/utils`	`NEXT_PUBLIC_VERCEL_URL`, `VERCEL`, `PORT`, `AUTH_TRUSTED_ORIGINS`
`apps/mcp-server`	`PERFORM_API_KEY` (required), `PERFORM_API_URL` (optional)

Adding a variable

Add it to the schema

Add the key to the z.object in apps/core-api/src/config.ts. Give optional values a default so local development still boots.

Read it from the context

Use ctx.env.MY_VALUE in the router factory and pass it into the service as config. Do not pass the whole env into a service.

Document it

Add it to this page. The older backend notes refer to a tracked .env.example, but the working tree has no such file, only local .env files at the repo root, apps/core-api, packages/db and packages/database. This page is the current list of variable names.

​Two ways env is read

​defineEnv

​Core API schema

​Server and infrastructure

​Rate limits

​Auth

​SmartSend and trainee login

​AI

​Storage

​AutoFit import

​Variables read by @repo packages

​Adding a variable

Two ways env is read

defineEnv

Core API schema

Server and infrastructure

Rate limits

Auth

SmartSend and trainee login

AI

Storage

AutoFit import

Variables read by @repo packages

Adding a variable