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
VR3 AI supports two deployment modes, set via DEPLOYMENT_MODE:
- OSS: The default mode and the one VR3 AI runs in. Designed for self-hosted deployments using Docker Compose — the fastest way to get VR3 AI running. Uses local JWT authentication and MinIO for storage.
- SaaS: An alternate mode intended for customised deployments outside of Docker, where authentication and API key management are delegated to an external Managed Platform Services (MPS) backend. Self-hosted VR3 AI deployments use the OSS mode above.
The relevant required variables for each mode are noted in the descriptions below.
Application
| Variable | Default | Description |
|---|
ENVIRONMENT | local | Runtime environment. Affects logging and behaviour. One of local, production, test |
DEPLOYMENT_MODE | oss | Deployment mode. Use oss for self-hosted |
AUTH_PROVIDER | local | Authentication provider. local (default) uses the built-in email/password flow. Set to stack to delegate to Stack Auth for social login — see Authentication for the full setup |
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 (OSS)
| Variable | Default | Description |
|---|
OSS_JWT_SECRET | N/A | Required for OSS deployments. Secret used to sign JWT tokens. Must be set to a strong random value in production |
OSS_JWT_EXPIRY_HOURS | 720 | JWT token lifetime in hours (default: 30 days) |
Never use the placeholder OSS_JWT_SECRET in a production deployment. Generate a strong random secret and store it securely.
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.
| Variable | Default | Description |
|---|
STACK_AUTH_PROJECT_ID | null | Required for stack. Stack project ID (public) |
STACK_PUBLISHABLE_CLIENT_KEY | null | Required for stack. Stack publishable client key (public) |
STACK_SECRET_SERVER_KEY | null | Required for stack. Stack secret server key — server-side only, also set on the ui service. Keep secret |
STACK_AUTH_API_URL | null | Required for stack. Stack REST API base URL (e.g. https://api.stack-auth.com) |
URLs
| Variable | Default | Description |
|---|
BACKEND_API_ENDPOINT | http://localhost:8000 | Internal URL of the backend API |
UI_APP_URL | http://localhost:3010 | URL of the frontend application |
MPS_API_URL | https://services.dograh.com | Managed Platform Services URL (only used in SaaS mode) |
DOGRAH_MPS_SECRET_KEY | null | Required for non-OSS deployments. Secret key for authenticating with MPS |
CORS_ALLOWED_ORIGINS | null | Required for non-OSS deployments. Comma-separated list of origins allowed to make credentialed cross-origin requests (e.g. https://app.example.com,https://admin.example.com). Ignored in OSS mode, which serves a permissive same-origin policy without credentials |
Storage
VR3 AI 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 | null | Publicly accessible MinIO URL (for download links) |
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 |
WebRTC
| Variable | Default | Description |
|---|
TURN_HOST | localhost | TURN server hostname for WebRTC NAT traversal |
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 OTEL ingest URL the backend pushes traces to (may be internal-only when self-hosting) |
LANGFUSE_PUBLIC_URL | LANGFUSE_HOST | Browser-reachable Langfuse web URL for “View Trace” links; set when LANGFUSE_HOST is internal-only |
LANGFUSE_PUBLIC_KEY | null | Langfuse public key |
LANGFUSE_SECRET_KEY | null | Langfuse secret key |
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
| Variable | Default | Description |
|---|
DEFAULT_ORG_CONCURRENCY_LIMIT | 2 | Maximum concurrent outbound calls per organization |
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. 
