Skip to content

Configuration & env

Environment variables

  • NEXT_PUBLIC_CONVEX_URL (required): Convex deployment URL for UI and server calls.
  • INGEST_API_KEY (deprecated in OSS template): use per-project API keys (see convex/apiKeys.ts).
  • RUNFORGE_API_KEY (client/SDK): same value as INGEST_API_KEY for local development and default setups.
  • RF_RATE_LIMIT_PER_MINUTE (optional, default 1000): per-project ingestion limit.
  • RUNFORGE_SYNC_URL (optional): internal sync webhook (e.g., /api/internal/pg-sync).
  • RUNFORGE_SYNC_SIGN (optional but required if URL set): HMAC secret for sync.
  • RUNFORGE_MASTER_KEY (optional, recommended): 32-byte key (base64 or 64-hex) for AES-GCM helpers.
  • RUNFORGE_DEV_MODE (dev only): enables auth fallbacks in lib/auth.ts.
  • RF_ALLOW_PROJECTID_FALLBACK (dev only, "1"): allow SDK projectId fallback via global.
  • CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY (auth provider keys for UI).
  • DATABASE_URL (Postgres, for Prisma).
  • RUNFORGE_ENDPOINT (client/SDK; optional): base URL for ingest (defaults to http://localhost:3000/api/ingest in examples).

.env example

NEXT_PUBLIC_CONVEX_URL=...
INGEST_API_KEY=...
RF_RATE_LIMIT_PER_MINUTE=1000
RUNFORGE_SYNC_URL=http://localhost:3000/api/internal/pg-sync
RUNFORGE_SYNC_SIGN=dev-signature
RUNFORGE_MASTER_KEY=base64:...
DATABASE_URL=postgres://user:pass@localhost:5432/runforge
CLERK_PUBLISHABLE_KEY=...
CLERK_SECRET_KEY=...

Checklist: keep /docs/11-configuration-env.md aligned when adding envs in lib/config.ts, lib/auth.ts, or API routes.