Skip to main content

​
Environment

This page is the canonical runtime configuration reference for the repo.

​
Local setup

Copy the example files before starting the workspace:

​
Required Supabase variables

  • NEXT_PUBLIC_SUPABASE_URL for any runtime that creates a Supabase client
  • NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY for browser and request-scoped clients
  • SUPABASE_SECRET_KEY for server-only admin access

​
Required Meta variables for real sends and webhook verification

  • WHATSAPP_META_ACCESS_TOKEN for worker-side outbound dispatch against the Meta Graph API
  • WEBHOOK_SIGNATURE_SECRET for validating x-hub-signature-256 on inbound webhooks
  • META_WEBHOOK_VERIFY_TOKEN if you want deterministic challenge verification for the Meta webhook handshake
These env variables remain valid platform-level bootstrap fallbacks. Once a workspace stores its own provider credentials through the operator app, the Vault-backed workspace values take precedence.

​
Accepted legacy aliases

The repo still accepts these while integrations are being migrated:
  • NEXT_PUBLIC_SUPABASE_ANON_KEY
  • SUPABASE_SERVICE_ROLE_KEY
New work should use the publishable and secret key names.

​
Data mode switch

  • WHATSAPP_PLATFORM_DATA_MODE=mock keeps the operator app, API routes, and docs running against the typed in-memory store
  • WHATSAPP_PLATFORM_DATA_MODE=supabase enables the Supabase-backed data path where implemented
If the variable is omitted, the repo stays in mock mode by default.

​
Optional variables

  • SUPABASE_DB_URL for direct Postgres tooling, migrations, and server-side jobs that need the connection string. It is also required if you want workspace-managed provider secrets to be stored in Supabase Vault from the product UI.
  • WHATSAPP_META_API_VERSION to override the default Graph API version. The repo defaults to v25.0.
  • WORKSPACE_BOOTSTRAP_ADMIN_EMAILS as a comma-separated list of emails allowed to bootstrap privileged workspace access without an invite.
  • WORKSPACE_ALLOW_FIRST_CLAIM to permit a single first-user owner claim when no workspace members exist yet. Default behavior is disabled unless you explicitly set this to true.
  • DEFAULT_WORKSPACE_SLUG for bootstrapping the default workspace context
  • DEFAULT_CHANNEL_WABA_ID, DEFAULT_CHANNEL_PHONE_NUMBER_ID, DEFAULT_CHANNEL_PHONE_E164, and DEFAULT_CHANNEL_DISPLAY_NAME for default channel metadata

​
Deployment split

  • Vercel-hosted apps/web, apps/app, and apps/api should receive the public Supabase variables they need for their runtime path
  • server runtimes such as apps/api, apps/worker, and apps/control-plane also need SUPABASE_SECRET_KEY
  • apps/worker on Railway needs WHATSAPP_META_ACCESS_TOKEN for real provider dispatch
  • apps/api on Vercel needs WEBHOOK_SIGNATURE_SECRET for signed webhook ingestion in the current alpha posture
  • only server runtimes should receive SUPABASE_DB_URL
  • the operator app server needs SUPABASE_DB_URL if you want /setup and Settings -> Provider to store or rotate workspace-managed secrets
  • the operator app server also needs WORKSPACE_BOOTSTRAP_ADMIN_EMAILS if you want the first privileged operator path to be explicit instead of invite-only
  • if a first authenticated operator reaches /pending-access with zero workspace members, recover by setting WORKSPACE_BOOTSTRAP_ADMIN_EMAILS, temporarily enabling WORKSPACE_ALLOW_FIRST_CLAIM=true, or manually provisioning the workspace_members row; deleting the auth user is not required
  • apps/control-plane remains in the repo but is not part of the current hosted alpha contract unless the ingress decision changes