Environment variables

This page lists variable names and purpose only - never values. Do not commit real keys; per-feature runbooks (SETUP.md, DEPLOY.md, docs/billing-setup.md, docs/email-setup.md, docs/domain-system-plan.md) own the full setup steps.

For the repo-wide placement matrix, provider acquisition steps, safe smoke results, and cleanup findings, see the internal operator runbook docs/env-and-secrets.md. The tracked templates are split by destination: .env.local.example, .env.convex.example, .env.vercel.example, .env.prod.example, .env.status.example, .env.github.example, .env.desktop.example, and .env.test.example.

Where vars live

Two homes:

• Vercel / .env.local - frontend and build vars (anything NEXT_PUBLIC_*, plus the Clerk client/server keys read by the Next.js app and middleware).
• The Convex deployment - server-only secrets used inside Convex actions (AI, Stripe, Resend, the Vercel domains API). Set them with:

npx convex env set NAME value            # dev
npx convex env set NAME value --prod     # production

CLERK_JWT_ISSUER_DOMAIN is the one var that must be set in both places - the Next.js app and the Convex deployment - because Convex validates the convex JWT template independently. See Auth & permissions.

The dev-fallback principle

Most integrations run in dev / mock mode until their credentials are set, so the whole app (and CI) works locally without secrets:

• No OPENROUTER_API_KEY → AI is disabled; the deterministic generator and the rest of the product still work fully.
• No RESEND_API_KEY → transactional email is silently skipped (invites fall back to copy-link).
• No Stripe keys → billing and payments are gated off (dev simulate paths).
• No VERCEL_API_TOKEN / VERCEL_PROJECT_ID → the domain connect/buy flow returns deterministic "connected" results (dev fallback), testable without credentials.
• No NEXT_PUBLIC_SITES_DOMAIN → platform subdomains are dormant; sites stay reachable at the /site/<slug> path.

Core (Convex client)

Clerk (auth - required)

AI - OpenRouter (optional; on the Convex deployment)

OPENROUTER_API_KEY powers all AI (generation/polish, the chat assistant, vision, dictation). The model overrides are all optional - defaults live in convex/generation/models.ts.

See the AI system.

Leave Agent/Fast unset for plan-aware routing. Use them only to pin one chat speed globally across all plans.

Email - Resend (optional; on the Convex deployment)

No key = email is silently skipped (docs/email-setup.md).

Billing & payments - Stripe (optional; on the Convex deployment)

Price ids and the operator runbook live in docs/billing-setup.md.

Domains & hosting - Name.com + Vercel (optional)

See Deployment and docs/domain-system-plan.md. No domain secrets are ever stored in Convex tables.

Misc & native shells (optional)

Status, automation, and test-only variables

These do not belong in the browser bundle or in the Convex deployment unless the code path explicitly consumes them:

The platform-injected values NODE_ENV, NEXT_RUNTIME, VERCEL, VERCEL_ENV, CI, PATH, and PORT are not hand-configured in the example files.