Environment Variables
Last updated April 25, 2026
Configure Matruno runtime, database, Redis, Temporal, auth, integrations, frontend, and observability environment variables from the repo examples.
Source files#
The root reference file is .env.example. Docker Compose also loads backend/.env for the backend and worker services, so keep root .env and backend/.env aligned for local Compose runs.
For local setup:
bash
cp .env.example .env
cp .env.example backend/.env
If you run the frontend outside Docker, create frontend/.env.local with frontend public values.
Required core variables#
| Variable | Used by | Purpose |
|---|---|---|
DATABASE_URL | Backend, worker | Async PostgreSQL connection string |
SECRET_KEY | Backend, worker | Session/application secret and encrypted secret material |
TOKEN_HASH_SECRET | Backend, worker | Independent token hashing/HMAC secret |
REDIS_URL | Backend, worker | Redis cache, locks, and coordination |
TEMPORAL_HOST | Backend, worker | Temporal frontend address |
TEMPORAL_NAMESPACE | Backend, worker | Temporal namespace |
FRONTEND_URL | Backend | Browser origin and callback-safe links |
CORS_ORIGINS | Backend | Explicit browser origins when credentials are enabled |
NEXT_PUBLIC_API_URL | Frontend | Public API base URL, usually http://localhost:5678/api/v1 |
Local default ports#
| Variable | Default |
|---|---|
API_PORT / BACKEND_PORT | 5678 |
FRONTEND_PORT | 3456 |
ADMIN_PANEL_PORT | 5679 |
TEMPORAL_UI_PORT | 8233 |
POSTGRES_PORT | 5433 |
Docs PORT / MATRUNO_DOCS_PORT | 3457 |
Optional provider and integration variables#
| Variable family | Purpose |
|---|---|
OPENAI_API_KEY, OPENAI_API_KEYS | OpenAI-backed agent, extraction, drafting, and chat paths |
ANTHROPIC_API_KEY, ANTHROPIC_API_KEYS | Optional Anthropic provider paths |
GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REDIRECT_URI, GMAIL_SCOPES | Gmail OAuth and email flows |
AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID, AZURE_REDIRECT_URI, GRAPH_SCOPES | Microsoft Graph email paths |
NANGO_SECRET_KEY, NEXT_PUBLIC_NANGO_PUBLIC_KEY | Nango-backed provider status and OAuth flows |
SMTP_*, IMAP_* | SMTP sending and IMAP inbox monitoring |
VOICE_AGENT_WS_URL, VOICE_AGENT_HEALTH_URL | Optional voice-agent observability links |
Observability variables#
| Variable | Purpose |
|---|---|
OTEL_ENABLED | Enables backend and worker OpenTelemetry bootstrap |
OTEL_EXPORTER_OTLP_ENDPOINT | OTLP gRPC endpoint, local Compose uses the collector |
OTEL_EXPORTER_OTLP_INSECURE | Local insecure OTLP transport flag |
OTEL_SERVICE_VERSION | Resource version label |
OTEL_DEPLOYMENT_ENVIRONMENT | Resource environment label |
OTEL_METRIC_EXPORT_INTERVAL_MILLIS | Metric export interval |
GRAFANA_CLOUD_OTLP_ENDPOINT | Optional Grafana Cloud OTLP target |
GRAFANA_CLOUD_OTLP_AUTH_HEADER | Optional Grafana Cloud auth header |
NEXT_PUBLIC_BROWSER_OBSERVABILITY_ENABLED | Enables frontend/admin browser RUM |
NEXT_PUBLIC_BROWSER_OTLP_BASE_URL | Browser same-origin OTLP proxy base |
OTEL_BROWSER_PROXY_TARGET | Frontend/admin proxy target for browser OTLP |
Production secrets
Never use the example secrets in production. Set high-entropy secrets, lock down CORS, enable secure cookies, and configure only the integration credentials your deployment actually needs.
Was this helpful?