Skip to the content.

Configuration

Every setting Open CRM reads, where it goes, and what stops working without it. There are three places:

.env.example lists the same names with short comments.

Frontend (.env.local)

Variable Required What it is Without it
VITE_SUPABASE_URL Yes The project URL, https://<ref>.supabase.co (Project Settings, API). Written by dev:bootstrap. The app cannot start. schedules:install also reads it.
VITE_SUPABASE_ANON_KEY Yes The anon (publishable) key. Written by dev:bootstrap. Never the service role key. The app cannot start.
VITE_SITE_URL For the AI connector The site’s public address, the same value as SITE_URL. Read only by the build. npm run build does not write dist/.well-known/oauth-authorization-server, so an AI assistant cannot find the connector’s sign-in. Everything else works.

Edge function secrets

Set by Supabase

Every deployed function gets these from the platform; you never set them.

Variable What it is
SUPABASE_URL The project URL.
SUPABASE_ANON_KEY The anon key.
SUPABASE_SERVICE_ROLE_KEY The service role key. Two-factor backup codes are hashed with a key derived from it, so rotating it invalidates every outstanding backup code.

A function that cannot read all three refuses to start.

Generated by npm run dev:bootstrap

The bootstrap writes each one into supabase/functions/.env once, only when it is missing, and never changes an existing value. Do not edit them, and do not copy them between projects.

Variable What it is Without it
DOCUMENT_ENCRYPTION_KEY AES-256 key (base64) that encrypts every stored document. encrypt-document and decrypt-document do not start: no upload, preview or download; the AI connector’s read_document_text cannot read an encrypted document. Changing it makes every stored document unreadable.
PII_ENCRYPTION_KEY AES-256 key (base64) for sensitive request answers and e-sign signers’ phone numbers. A client’s sensitive answer is refused and the owner’s Reveal fails (encryption_unavailable); text message codes for e-signature are refused; the AI connector’s read_request_answers returns sensitive answers unopened. Changing it makes those values unreadable.
CRON_SHARED_SECRET 64 hex characters. Scheduled calls send it in the x-cron-secret header; schedules:install copies it into Vault. Every scheduled call is refused (an unset or shorter-than-32-character secret refuses all callers), so reminders, digests, envelope expiry and clean-up never run. Run schedules:install again after changing it.
ESIGN_INTERNAL_TOKEN 64 hex characters, sent by esign-signer-sign to esign-finalize-envelope. The last signature is recorded but finalize is skipped: no executed PDF, no completion emails.
ESIGN_SMS_CODE_KEY 32 bytes as 64 hex characters, the HMAC key for e-sign text message codes. High-verification signing (a text message code) fails.

Set by you

Variable Required What it is Without it
SITE_URL Yes, on any install that sends links The address the app is served from, e.g. https://crm.example.com (http://localhost:5173 while developing). It is the browser origin the functions accept and the base of every link in an email. Portal invitations, e-sign sends, resends and finalize, request sends and reminders, and group email are refused (site_url_missing). The AI connector cannot issue sign-ins. csp-report drops every report. Browser calls are accepted from localhost only, while ENVIRONMENT is not production.
ENVIRONMENT Yes, in production (production) Production mode. Not production: the functions also accept http://localhost:5173, and any message with no provider configured is written to the dev outbox instead of sent. In production a missing provider is an error.
ALLOWED_ORIGINS No Extra browser origins, comma-separated. In production, local origins are dropped from it. Only SITE_URL (and localhost outside production) may call the functions from a browser.
RESEND_API_KEY For real email A Resend API key. Turns on real email: invitations, requests, e-sign, group email, the owner’s notices and two-factor recovery alerts. Outside production, email goes to the dev outbox (System, Outbox). In production, every send fails.
EMAIL_FROM With RESEND_API_KEY The sender, e.g. Example Co <crm@example.com>, on a domain verified in Resend. Email sends fail while RESEND_API_KEY is set.
EMAIL_REPLY_TO No Where replies go. Replies go to EMAIL_FROM.
TWILIO_ACCOUNT_SID For real text messages Twilio account SID. All three Twilio values turn on real texts (e-sign codes). Outside production, codes go to the dev outbox. In production, High verification is not offered (turn SMS off in Settings, E-sign).
TWILIO_AUTH_TOKEN With the SID Twilio auth token. As above.
TWILIO_FROM With the SID The sending number in E.164 (+1...) or a Messaging Service SID. In the United States a long-code number needs a registered A2P 10DLC campaign. As above.
MCP_EXTRA_REDIRECT_URIS No Exact OAuth callback addresses of AI assistants beyond Claude and ChatGPT, comma-separated, each https with no query or fragment (e.g. https://assistant.example.com/oauth/callback). Read by mcp-oauth; an entry that is not a plain https address is ignored and logged. Only Claude, ChatGPT and local (loopback) assistants can connect.
RESEND_WEBHOOK_SECRET No The signing secret of a Resend webhook pointed at https://<ref>.supabase.co/functions/v1/esign-resend-webhook. The webhook answers 503 and e-sign emails show no delivered or opened time.

Script inputs

Variable Read by What it is
SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY npm run dev:bootstrap The project’s URL and keys, if you would rather not type them at the prompt. The service role key is used for that run only and never written to disk.

dev:bootstrap also takes --email, --password, --org-name, --yes (fail instead of asking) and --adopt-existing (take over an Auth account that already holds the owner’s email, setting its password). schedules:install reads VITE_SUPABASE_URL from .env.local and CRON_SHARED_SECRET from supabase/functions/.env.

Supabase project settings

These live in supabase/config.toml and reach your project with npx supabase config push: public sign-up off, passwords of at least eight characters with a lower-case letter, an upper-case letter, a digit and a symbol, authenticator-app two-factor on, a password change that needs a recent sign-in or an emailed code, and the site URL. Before pushing to a live project, replace site_url and the localhost entries in additional_redirect_urls with your site (<your site>/reset-password and <your site>/settings/security, or <your site>/**).

Custom SMTP for Supabase Auth is set in the dashboard (Authentication, Emails). Without it, Auth’s built-in sender allows only a few emails an hour across the whole project.