Configuration & Environment Variables
All configuration lives in .env.local (copy it from .env.local.example). This page groups the variables by what they're for and which ones must stay server-only.
Supabase
| Variable | Server-only? | Notes |
|---|
NEXT_PUBLIC_SUPABASE_URL | No | Public by design |
NEXT_PUBLIC_SUPABASE_ANON_KEY | No | RLS-governed, safe to ship to the browser |
SUPABASE_SERVICE_ROLE_KEY | Yes | Bypasses RLS entirely — never expose this to the client. The widget's public API routes use it because anonymous visitors have no Supabase session for RLS to check |
AI Providers
| Variable | Notes |
|---|
OPENAI_API_KEY | Required — the widget chat endpoint is fixed to gpt-4o-mini for v1 |
ANTHROPIC_API_KEY | Optional, used by the dashboard chat feature inherited from the base template |
Stripe (owner billing)
| Variable | Notes |
|---|
STRIPE_SECRET_KEY | Server-only |
STRIPE_WEBHOOK_SECRET | Server-only, verifies incoming webhook signatures |
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY | Client-side checkout |
NEXT_PUBLIC_STRIPE_PORTAL_URL | Customer portal link |
STRIPE_PRO_PRICE_ID / STRIPE_TOPUP_PRICE_ID / STRIPE_ENTERPRISE_PRICE_ID | Price IDs from your Stripe dashboard |
Widget usage is billed against the bot owner's credit balance — a visitor never sees Stripe.
App
| Variable | Notes |
|---|
NEXT_PUBLIC_APP_URL | Used to build the widget's iframe src and OAuth redirect URIs — must be the real deployed URL in production, not localhost |
CRON_SECRET | Protects scheduled credit-reset endpoints |
Email (widget lead notifications)
| Variable | Notes |
|---|
RESEND_API_KEY | Optional — without it, lead capture still writes to the leads table, but the owner doesn't get an email |
EMAIL_FROM | The From address Resend sends lead/credit-exhausted notifications from |
CRM booking integrations (Phase 9 scaffold)
| Variable | Notes |
|---|
JOBBER_CLIENT_ID / JOBBER_CLIENT_SECRET | Only needed if you're wiring up the Jobber OAuth connect flow |
HOUSECALL_PRO_CLIENT_ID / HOUSECALL_PRO_CLIENT_SECRET | Same, for Housecall Pro |
These only enable the OAuth connect flow — see CRM Integrations for what's real versus stubbed before you rely on them.
Validating your setup
After filling in .env.local, run the built-in checklist rather than guessing:
pnpm dev
Then visit /dashboard/setup — it checks env vars and confirms the database schema was applied correctly.
