Operator Deployment

Use this when you are self-hosting Breakdown, operating a deployment, or contributing to the app. These secrets are not required to connect an external agent to hosted Breakdown. Canonical direction is Roadmap and ADR 0004: Breakdown Local is the 1.0+ product and secrets are file-local only.

Who Needs This

Hosted service users and off-repo coding agents should use https://www.breakdown.sh/api/mcp, setup sessions, and scoped Bearer tokens. This page is for operators who manage the Breakdown app infrastructure.

Secrets Source Of Truth

Keep .env.local.example as the variable inventory. Real values should live in untracked local files (.env.local) and be injected as standard env vars. No Doppler and no Vercel env sync are required for ordinary development or for Breakdown Local — see Roadmap and Secrets Management (file-local).

Recommended Configs

For self-hosting the SaaS app, a straightforward setup is one host with separate environment values for local development, preview deployments, and production — managed in your hosting env store or chosen secrets manager, not via a required Doppler sync.

GroupVariables
ClerkNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY, sign-in and sign-up URLs
SupabaseNEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY
Stored integration credentialsINTEGRATION_TOKEN_ENCRYPTION_KEY
Google DriveGOOGLE_DRIVE_CLIENT_ID, GOOGLE_DRIVE_CLIENT_SECRET, NEXT_PUBLIC_GOOGLE_DRIVE_API_KEY, NEXT_PUBLIC_GOOGLE_DRIVE_APP_ID

Integration Token Encryption

INTEGRATION_TOKEN_ENCRYPTION_KEYmust decode to 32 bytes. Generate a value for each environment and store it only in that environment's env store.

openssl rand -base64 32

Local Development

cp .env.local.example .env.local
# edit .env.local
pnpm secrets:check
pnpm dev

No doppler setup required. See Local Development for the file-local flow.

Hosted Deployment

  1. Set preview/production env vars in your hosting env store (Vercel dashboard, Doppler, Vault, 1Password, or plain env).
  2. Redeploy after changing any build-time NEXT_PUBLIC_* value.
  3. Run a smoke test for the affected integration after each rotation.

Credential Rules

  • Do not commit real secrets.
  • Do not maintain duplicate manual values in the hosting dashboard.
  • User-managed AI provider API keys belong in app settings, not shared env vars.
  • Rotate upstream credentials after replacing them in the host env store.

Hosted-Legacy Appendix (Self-Host Only)

Operators who previously used Doppler may still sync a Doppler project (e.g. breakdown-sh / dev, stg, prd) to Vercel via Doppler's Vercel integration. That path is hosted-legacy / self-host only and is not required for Breakdown Local. The canonical retired artifacts were doppler.yaml and dev:secrets / build:secrets / start:secrets / ci:secrets (doppler run -- ...) and the dopplerhq/secrets-fetch-action OIDC step in supabase-migrations.yml — all removed or replaced in #205. See Secrets Management — Appendix A.