Configuration
Every setting Open CRM reads, where it goes, and what stops working without it. There are three places:
.env.localin the repository root: the frontend’sVITE_variables, read at build time (and bynpm run dev). They end up in the JavaScript every visitor downloads, so they hold nothing secret.- Edge function secrets: written to
supabase/functions/.env, then sent to the project withnpx supabase secrets set --env-file supabase/functions/.env(or set one at a time withnpx supabase secrets set NAME=value). Redeploy the functions after a change. - The scripts’ own inputs: environment variables
npm run dev:bootstrapreads for one run.
.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.