Environment Variables

Every variable below lives in .env.example (the template) and is loaded into SST's own secrets vault per stage — see Secrets for the loading commands. This page is the reference for where each value comes from, one platform at a time, for anyone setting this up for the first time.

You don't need every row — only fill in what a feature you're actually using requires. Everything not marked Always is gated by a flag in config.ts; leave it blank and disable the flag if you don't want that integration.

1. Branding — your identity

Set in the Branding section of your stage's env file — the single place your domain and sender email live; nothing in the code repeats them. Unlike everything below, these are not secrets: the deploy reads them straight from the file (and stops with the variable's name if one is missing or malformed), and a real environment variable of the same name takes precedence. Each stage reads its own file — .env.production for production, .env.stage for every other stage.

2. Cloudflare — deploy authentication

Required before any sst command works at all, on every machine that deploys. Full walkthrough with screenshots (permissions, token scope) is in Cloudflare Access.

3. Database — PostgreSQL

Any standard Postgres works — the app speaks the native wire protocol, never a provider SDK. Using Supabase as the example (it's what this project's own .env.stage points at):

Use the Direct connection, not the Session pooler

Supabase's database settings page shows two connection modes. Use Direct connection — Cloudflare's own Hyperdrive docs are explicit about this: "you should use the Direct connection connection string rather than the pooled connection strings, as Hyperdrive will perform pooling of connections to ensure optimal access from Workers." Hyperdrive already pools connections at Cloudflare's edge — routing it through Supabase's own pooler (Supavisor) on top would be pooling behind a pooler, for no benefit.

The two modes use different, non-interchangeable host and username formats — never mix one mode's host with the other mode's username:

Pairing a direct-mode host with a pooler-mode username (or vice versa) doesn't fail loudly with a clear message — it deploys, then Cloudflare rejects it with Hyperdrive → 400: "Invalid database credentials" (error code 2013), which reads like a wrong password even when the password is correct.

The one case where you might still need the pooler: every deploy runs database migrations automatically from your own machine (infra/utils/nuxt.ts, a local command), using these same values — not just from Cloudflare's edge. Supabase's direct connection is IPv6-only. If your network has no real IPv6 route to the internet, that local migration step will fail to connect (a connection timeout, not the credentials error above) even though Hyperdrive itself would have worked fine from Cloudflare's own IPv6-capable network. If you hit that specific failure, switching to the Session pooler pair (table above) is the pragmatic fix — you're trading a small amount of double-pooling overhead for reachability from your own machine.

Using RDS, Neon, or self-hosted Postgres instead: the same five values come from that provider's own connection-info page — the app doesn't care which one, as long as the postgis extension is enabled (Supabase has it available by default; run CREATE EXTENSION IF NOT EXISTS postgis; on others if needed).

4. Email — pick at least one provider

Enable/disable each in config.ts → flags. Only resend is on by default.

5. Social login

Both are optional, independently toggled (flags.githubAuth, flags.googleAuth). Each callback URL below must match exactly, including the /callback suffix — the OAuth provider will reject the login with a redirect-URI-mismatch error otherwise.

6. Payments

Stripe and Paddle can both be active at once — a Plan just picks one provider per row (see Payments & Billing).

There is no environment variable for which plan the landing page's Buy CTA sells — that's a database flag (Plan.isPublicOffer), toggled from /admin/plans and read live by apps/web over a Cloudflare service binding. See Payments & Billing for how it works.

PADDLE_API_KEY permissions — don't select "All"

When creating the API key, the app only ever calls two Paddle resources server-side (grep -rn "paddle\.\w*\.\w*(" apps/app/server to re-verify against a newer checkout of this repo):

• Customers — Read. paddle.customers.get(customerId) in the webhook handler (server/api/webhooks/paddle.post.ts), to read the customer's email.
• Customer portal sessions — Write. paddle.customerPortalSessions.create(...) (server/trpc/routers/billing.ts), to generate the billing-portal link a customer uses to manage their subscription.

Nothing else — no Adjustments, Businesses, Addresses, Discounts, Products, Prices, Transactions, or Reports permission is used anywhere in the codebase. A broader key is unnecessary blast radius if it ever leaks; widen the scope later only if new code actually calls another Paddle resource. (paddle.webhooks.unmarshal(...), the third Paddle SDK call in the same webhook handler, verifies the webhook signature locally — it's not a network call and needs no API permission.)

7. Platform Admin console (/admin)

Not from any external platform — generate these yourself, locally. See Platform Admin Console for what they protect.

8. Two-factor authentication (regular users)

Same generation command as the platform-admin pair above, same rules, but kept on separate secrets — see Platform Admin Console for why. Only required if a user actually turns on 2FA from Account Settings → Security; nothing else in the app depends on these.

9. Optional — AI & System One models (TypeSafe)

10. Optional — build tuning

What never goes in this file

NUXT_PUBLIC_* variables, worker URLs, client IDs exposed to the browser, and anything else derived at deploy time are computed automatically by infra/*.ts — never set those by hand here. The one exception: running seed/demo-accounts.ts manually needs AUTH_URL and AUTH_ADMIN_SECRET in your terminal's environment at the moment you run it (not in this file, not in the vault) — see Platform Admin Console.