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.

Deployment Modes

Talkr supports two deployment modes, set via DEPLOYMENT_MODE:

• OSS: The default mode. Designed for self-hosted deployments using Docker Compose — the fastest way to get Talkr running. Uses local JWT authentication and MinIO for storage.
• SaaS: Intended for customised deployments outside of Docker, allowing greater flexibility in how the platform is hosted and integrated. Talkr is bring-your-own-key (BYOK) only — there is no managed/hosted AI model tier.

The relevant required variables for each mode are noted in the descriptions below.

Application

Database

Authentication (OSS)

Authentication (Stack Auth)

Set these when AUTH_PROVIDER=stack to delegate sign-in to Stack Auth for social login. The project id and publishable client key are public and are served to the browser at runtime via /api/v1/health; the secret server key stays server-side. See Authentication for the full walkthrough.

URLs

AI Workflow Generation

Powers the "Use Agent Builder" wizard on /workflow/create — a Talkr-owned LLM key, entirely separate from any organization's BYOK model configuration, so the feature works before an organization has configured anything.

Generations are capped at 10 per organization per day (fixed, not currently configurable) since this key is shared and Talkr-paid rather than per-organization.

Trial-credit managed tier

Powers the free trial credits every new organization gets on signup (see Billing) — Talkr-owned STT/TTS keys, entirely separate from any organization's BYOK model configuration, used only as a fallback for a service the organization hasn't configured itself, metered against that organization's credit balance. The LLM side of this reuses TALKR_PLATFORM_LLM_API_KEY/_PROVIDER/_MODEL above.

Every new organization gets a one-time credit grant (TRIAL_CREDITS_INITIAL_GRANT in api/constants.py); once it's spent, calls needing a trial-managed service are rejected until the organization buys more credits or configures its own keys for that service.

Storage

Talkr 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)

AWS S3 (alternative)

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=...

WebRTC

Tracing (Langfuse)

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.

Telephony

Carriers dial the media WebSocket back at /api/v1/telephony/ws/{workflow_id}/{organization_id}/{workflow_run_id}. Those ids travel in a caller-visible URL, so on their own they are a guessable capability. Setting a secret makes Talkr sign that URL with an HMAC and verify the signature when the socket opens.

The signature travels as a trailing path segment — /api/v1/telephony/ws/{workflow_id}/{organization_id}/{workflow_run_id}/{token} — because carriers do not reliably forward query strings. Twilio documents that its <Stream> url "does not support query string parameters" and drops them outright. Asterisk ARI is the exception: it connects to /api/v1/telephony/ws/ari and passes token as a query parameter alongside its other routing values, which works because Asterisk builds that URL itself.

Roll it out in two steps so no call is dropped:

1. Set TELEPHONY_WS_TOKEN_SECRET on every process that places or receives calls — the api service and, if you run Asterisk, the ari-manager. They must share the same value: one mints the token, the other verifies it. Calls keep connecting either way; anything unverifiable is logged as UNVERIFIED media socket.
2. Once those warnings stop, set TELEPHONY_WS_TOKEN_ENFORCE=true to start rejecting them.

Setting TELEPHONY_WS_TOKEN_ENFORCE without a secret does nothing at all — the check is skipped entirely rather than rejecting every connection.

Rate Limiting

Telephony webhook callbacks (/api/v1/telephony/*) and health-check endpoints are never subject to this limit, so real calls and infra liveness checks are unaffected regardless of these values.

Monitoring

Logging

Campaigns

Controls concurrency for Campaigns, Talkr's bulk outbound calling feature.

Capacity & Scaling

See Scaling for the full picture of how these interact.

Billing (Razorpay)

Only relevant if you've enabled paid credit top-ups via Razorpay. Unset: billing/top-up endpoints are unavailable, credits work purely as a usage meter with no purchase flow.

Webhooks

Tuning for outbound webhook delivery retries.

Email

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.