Environment Variables

Core environment variables are centralized in api/constants.py. Variables marked Required in the description must be explicitly set — the application will either fail to boot or behave insecurely without them.

Application

Variable	Default	Description
`ENVIRONMENT`	`local`	Runtime environment. Affects logging and behaviour. One of `local`, `production`, `test`
`DEPLOYMENT_MODE`	`oss`	Cosmetic label reported by `/v1/health`. Has no behavioural effect
`ALLOW_PRIVATE_SERVICE_URLS`	`true`	SSRF guard for user-supplied service URLs (webhooks, custom base URLs, MCP servers). Leave `true` for single-tenant self-hosting so local/private addresses work; set `false` on hosted multi-tenant deployments to block requests to private networks

Database

Variable	Default	Description
`DATABASE_URL`	N/A	Required. PostgreSQL connection string. e.g. `postgresql+asyncpg://user:pass@host:5432/dbname`
`REDIS_URL`	N/A	Required. Redis connection string. e.g. `redis://localhost:6379`

Authentication (Clerk)

User sign-in (Google + email) is handled by Clerk. The publishable key is public and is served to the browser at runtime via /v1/health; the secret key stays server-side. Until Clerk keys are set, browser sign-in returns 503, but API-key access still works. See Authentication for the full walkthrough.

Variable	Default	Description
`CLERK_SECRET_KEY`	`null`	Required for browser sign-in. Clerk secret key — server-side only. Also set on the `ui` service (Clerk middleware/SSR). Keep secret
`CLERK_PUBLISHABLE_KEY`	`null`	Clerk publishable key (public). Served to the browser at runtime via `/v1/health`, so prebuilt images need no rebuild. Also set on the `ui` service
`CLERK_JWT_KEY`	`null`	Optional JWKS public key (PEM). Enables networkless session-token verification — recommended in production
`CLERK_AUTHORIZED_PARTIES`	`null`	Comma-separated origins accepted as the session token’s authorized party
`SUPERUSER_EMAILS`	`null`	Comma-separated email addresses auto-promoted to superuser on sign-in

URLs

Variable	Default	Description
`PUBLIC_BASE_URL`	`null`	Canonical public origin for the deployment (scheme + host, e.g. `https://203-0-113-10.sslip.io`). For a standard single-host install this is the only endpoint value you set — `BACKEND_API_ENDPOINT` and `MINIO_PUBLIC_ENDPOINT` derive from it
`PUBLIC_HOST`	`null`	Public host without scheme (e.g. `203-0-113-10.sslip.io`); `TURN_HOST` derives from it
`BACKEND_API_ENDPOINT`	`PUBLIC_BASE_URL`, else `http://localhost:8000`	Public URL the backend builds webhook / callback / embed links from. Set explicitly only to override the value derived from `PUBLIC_BASE_URL`
`UI_APP_URL`	`http://localhost:3010`	URL of the frontend application
`CORS_ALLOWED_ORIGINS`	`null`	Comma-separated list of origins allowed to make credentialed cross-origin requests (e.g. `https://app.example.com,https://admin.example.com`). When unset, the backend serves a permissive wildcard policy without credentials; when set, only the listed origins are allowed and credentials are permitted

Platform model providers

These OpenAI-compatible endpoints define what the EESI-managed model configuration (and empty configurations) resolve to. Defaults point at the self-hosted local stack — Ollama for the LLM, Speaches for STT/TTS; a hosted deployment repoints them at its own provider accounts. BYOK configurations never use these. The old MPS_LLM_BASE_URL-style MPS_* names are still accepted as deprecated fallbacks.

Variable	Default	Description
`PLATFORM_LLM_BASE_URL`	`http://localhost:11434/v1`	OpenAI-compatible LLM endpoint (Ollama by default)
`PLATFORM_LLM_MODEL`	`qwen3.5:0.8b`	LLM model name. If empty, the first model reported by the endpoint is used
`PLATFORM_LLM_API_KEY`	empty	API key for the LLM endpoint, if it requires one
`PLATFORM_STT_BASE_URL`	`http://localhost:8010/v1`	OpenAI-compatible speech-to-text endpoint (Speaches by default)
`PLATFORM_STT_MODEL`	`Systran/faster-distil-whisper-small.en`	STT model name
`PLATFORM_STT_LANGUAGE`	`en`	Default STT language
`PLATFORM_STT_API_KEY`	empty	API key for the STT endpoint, if it requires one
`PLATFORM_TTS_BASE_URL`	`http://localhost:8010/v1`	OpenAI-compatible text-to-speech endpoint (Speaches by default)
`PLATFORM_TTS_MODEL`	`speaches-ai/Kokoro-82M-v1.0-ONNX`	TTS model name
`PLATFORM_TTS_VOICE`	`af_heart`	Default TTS voice
`PLATFORM_TTS_API_KEY`	empty	API key for the TTS endpoint, if it requires one

Billing (Polar)

EESI bills usage with prepaid credits (1 credit = 1 cent) purchased through Polar checkout and tracked on a local ledger. Billing is optional and turns on only when all three of POLAR_ACCESS_TOKEN, POLAR_WEBHOOK_SECRET, and POLAR_PRODUCT_IDS are set. Until then the billing UI is hidden, billing routes return 404, and no credit gating is applied (visible as billing_enabled: false in GET /v1/health).

Variable	Default	Description
`POLAR_ACCESS_TOKEN`	`null`	Polar organization access token. Required for billing
`POLAR_WEBHOOK_SECRET`	`null`	Secret used to verify `POST /v1/webhooks/polar` signatures. Required for billing
`POLAR_PRODUCT_IDS`	`null`	Comma-separated Polar product IDs offered as credit packs at checkout. At least one required for billing
`POLAR_SERVER`	`production`	Polar environment. Set `sandbox` for testing
`DEFAULT_PRICE_PER_SECOND_USD`	`0`	Price charged per second of call time, in USD. `0` disables usage charging

Storage

EESI uses MinIO by default, which is bundled with the self-hosted deployment and requires no external setup. Set ENABLE_AWS_S3=true to switch to AWS S3 — typically used for cloud or managed deployments where S3 is already part of the infrastructure.

MinIO (OSS default)

Variable	Default	Description
`MINIO_ENDPOINT`	`localhost:9000`	MinIO server host and port
`MINIO_PUBLIC_ENDPOINT`	`PUBLIC_BASE_URL`, else `http://localhost:9000`	Publicly accessible MinIO URL for download links. Derives from `PUBLIC_BASE_URL`; set explicitly only for a separate object-storage origin
`MINIO_ACCESS_KEY`	N/A	Required for OSS deployments. MinIO access key. Must be set to a secure value in production
`MINIO_SECRET_KEY`	N/A	Required for OSS deployments. MinIO secret key. Must be set to a secure value in production
`MINIO_BUCKET`	`voice-audio`	Bucket name for audio files
`MINIO_SECURE`	`false`	Use HTTPS for MinIO connections

AWS S3 (alternative)

Variable	Default	Description
`ENABLE_AWS_S3`	`false`	Set to `true` to use AWS S3 instead of MinIO
`S3_BUCKET`	`null`	S3 bucket name
`S3_REGION`	`us-east-1`	AWS region
`S3_ENDPOINT_URL`	`null`	Custom S3 endpoint for S3-compatible servers (e.g. `https://s3.example.com`). Leave unset for AWS.
`S3_SIGNATURE_VERSION`	`null`	Signing version. Unset uses botocore’s default; set `s3v4` for servers that require SigV4.
`S3_ADDRESSING_STYLE`	`null`	`auto` (default), `path`, or `virtual`. Many S3-compatible servers and TLS setups require `path`.

Credentials come from the standard AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY environment variables.

S3-compatible servers (MinIO, rustfs, Ceph, …)

The S3 backend can target any S3-compatible server, not just AWS. Prefer it over the MinIO backend when you need presigned URLs against a private bucket: the MinIO backend returns plain unsigned object URLs and relies on the bucket being anonymously public-readable, whereas the S3 backend issues real presigned URLs so the bucket can stay private. To use it, set ENABLE_AWS_S3=true and point it at your server with the S3_* overrides above. For example, against rustfs:

ENABLE_AWS_S3=true
S3_BUCKET=voice-audio
S3_REGION=us-east-1
S3_ENDPOINT_URL=https://s3.example.com
S3_SIGNATURE_VERSION=s3v4   # rustfs rejects SigV2 with SignatureDoesNotMatch
S3_ADDRESSING_STYLE=path    # rustfs and most non-AWS TLS certs require path-style
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

Presigned URLs point at S3_ENDPOINT_URL, so that host must be reachable from the browser. Because browsers fetch transcripts cross-origin, the bucket also needs a CORS rule allowing your app’s origin for GET/HEAD — configure this on the storage server (e.g. via PutBucketCors), not in EESI.

WebRTC

Variable	Default	Description
`TURN_HOST`	`PUBLIC_HOST`, else `localhost`	TURN server hostname for WebRTC NAT traversal. Derives from `PUBLIC_HOST`; set explicitly only when TURN runs on a separate host
`TURN_PORT`	`3478`	TURN server port
`TURN_TLS_PORT`	`5349`	TURN server TLS port
`TURN_SECRET`	`null`	Required for WebRTC. Shared secret for TURN credential generation
`TURN_CREDENTIAL_TTL`	`86400`	TURN credential validity in seconds (default: 24h)
`FORCE_TURN_RELAY`	`false`	Diagnostic flag. When `true`, restricts ICE to relay-only candidates on both server (SDP filter) and browser (`iceTransportPolicy: 'relay'`). Use to verify TURN connectivity end-to-end — calls fail cleanly if TURN is misconfigured instead of silently falling back to a direct path.

Tracing (Langfuse)

Variable	Default	Description
`LANGFUSE_HOST`	`null`	Langfuse server URL
`LANGFUSE_PUBLIC_KEY`	`null`	Langfuse public key
`LANGFUSE_SECRET_KEY`	`null`	Langfuse secret key

Tracing activates automatically as soon as credentials are available — either via these environment variables (applied to all organizations) or per-organization in the UI under Platform Settings. If neither is set, spans are dropped silently. See the Tracing guide for setup instructions.

Monitoring

Variable	Default	Description
`SENTRY_DSN`	`null`	Sentry DSN for error tracking
`ENABLE_TELEMETRY`	`false`	Enable anonymous telemetry collection

Logging

Variable	Default	Description
`LOG_LEVEL`	`DEBUG`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`LOG_FILE_PATH`	`null`	Write logs to this file path (in addition to stdout)
`LOG_ROTATION_SIZE`	`100 MB`	Rotate log file when it reaches this size
`LOG_RETENTION`	`7 days`	How long to keep rotated log files
`LOG_COMPRESSION`	`gz`	Compression format for rotated logs
`SERIALIZE_LOG_OUTPUT`	`false`	Output logs as JSON (useful for log aggregation)

Campaigns

Controls concurrency for Campaigns, EESI’s bulk outbound calling feature.

Variable	Default	Description
`DEFAULT_ORG_CONCURRENCY_LIMIT`	`10`	Maximum concurrent active calls per organization (values below 1 are clamped to 1)

Further Customisation

The variables documented here cover the standard configuration surface. For advanced customisation — such as integrating additional services or tuning internal behaviour — consult the relevant module alongside api/constants.py to understand how each variable is consumed.

Contribution

Guides

SDKs

Deployment

Environment Variables

Application

Database

Authentication (Clerk)

URLs

Platform model providers

Billing (Polar)

Storage

MinIO (OSS default)

AWS S3 (alternative)

S3-compatible servers (MinIO, rustfs, Ceph, …)

WebRTC

Tracing (Langfuse)

Monitoring

Logging

Campaigns

Further Customisation

​Application

​Database

​Authentication (Clerk)

​URLs

​Platform model providers

​Billing (Polar)

​Storage

​MinIO (OSS default)

​AWS S3 (alternative)

​S3-compatible servers (MinIO, rustfs, Ceph, …)

​WebRTC

​Tracing (Langfuse)

​Monitoring

​Logging

​Campaigns

​Further Customisation

Application

Database

Authentication (Clerk)

URLs

Platform model providers

Billing (Polar)

Storage

MinIO (OSS default)

AWS S3 (alternative)

S3-compatible servers (MinIO, rustfs, Ceph, …)

WebRTC

Tracing (Langfuse)

Monitoring

Logging

Campaigns

Further Customisation