VoxCore reads configuration from a .env file at the project root. Defaults are for local development. Production fleet hosts override the worker and storage values explicitly.
Core settings
| Variable | Default | Description |
|---|
VOXBRIDGE_CONFIG_URL | http://localhost:8080/api/v1/config | VoxBridge config API base URL |
VOXBRIDGE_URL | http://localhost:8080 | VoxBridge base URL for non-config internal endpoints |
VOXCORE_SECRET | voxcore-internal-secret | Shared secret for VoxBridge ↔ VoxCore auth |
ENVIRONMENT | development | Set to production on live hosts to enable startup safety checks |
MAX_CONCURRENT_CALLS | 5 | Local dev default. Production fleet workers should use 1 so one worker equals one call slot. |
VOXCORE_WORKERS | 4 | Worker count reported in health endpoints. Production must match the actual systemd/container worker count. |
VOXCORE_SOCKET | "" | Unix socket path for a single worker, set by the systemd template |
AUDIO_SAMPLE_RATE | 8000 | Default audio sample rate (Hz) |
LOG_LEVEL | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
Do not use the local MAX_CONCURRENT_CALLS=5 default in production. Current production architecture is one call per worker, enforced by both MAX_CONCURRENT_CALLS=1 and nginx max_conns=1.
Object storage
| Variable | Default | Description |
|---|
MINIO_ENDPOINT | localhost:9000 | S3-compatible endpoint |
MINIO_ACCESS_KEY | minioadmin | Access key |
MINIO_SECRET_KEY | minioadmin | Secret key |
MINIO_BUCKET | recordings | Bucket for call recordings |
MINIO_SECURE | false | Use HTTPS for storage endpoint |
LiveKit (SIP transports)
| Variable | Default | Description |
|---|
LIVEKIT_URL | (empty) | LiveKit server URL (e.g., wss://livekit.example.com) |
LIVEKIT_API_KEY | (empty) | LiveKit API key |
LIVEKIT_API_SECRET | (empty) | LiveKit API secret |
LiveKit variables are only required if using LiveKit SIP inbound or outbound transports. The WebSocket and Exotel transports do not need them.
OpenTelemetry
| Variable | Default | Description |
|---|
OTEL_ENABLED | false | Enable OpenTelemetry tracing |
OTEL_ENDPOINT | http://localhost:4317 | OTLP exporter endpoint |
OTEL_SERVICE_NAME | voxcore | Service name in traces |
API keys
STT, LLM, and TTS API keys can be set in environment variables but are typically provided through bot config from VoxBridge:
| Variable | Service |
|---|
DEEPGRAM_API_KEY | Deepgram STT |
SONIOX_API_KEY | Soniox STT |
OPENAI_API_KEY | OpenAI LLM |
GOOGLE_API_KEY | Google Gemini LLM |
ELEVENLABS_API_KEY | ElevenLabs TTS |
SARVAM_API_KEY | Sarvam TTS |
LLM caching
| Variable | Default | Description |
|---|
GEMINI_CONTEXT_CACHE_TTL_SECONDS | 3600 | TTL (seconds) for Gemini/Vertex CachedContent used by live and post-call explicit caching. Floored at 300s; workers proactively recreate caches after ~90% of TTL. |
TTS cache
| Variable | Default | Description |
|---|
TTS_CACHE_REDIS_URL | "" | Redis URL used by the ElevenLabs TTS cache. Required only when a bot enables tts.cache_config.enabled. |
Durable outboxes
VoxCore persists result delivery and Agent Desk enqueue attempts before trying to send them to VoxBridge.
| Variable | Default | Description |
|---|
RESULT_OUTBOX_DIR | /tmp/voxcore-result-outbox | Directory for pending call-result webhook payloads |
RESULT_OUTBOX_POLL_SECONDS | 30.0 | Background retry poll interval |
RESULT_OUTBOX_RETRY_SECONDS | 30.0 | Initial retry delay |
RESULT_OUTBOX_MAX_RETRY_SECONDS | 300.0 | Max retry delay |
AGENT_DESK_OUTBOX_DIR | /tmp/voxcore-agent-desk-outbox | Directory for pending Agent Desk handoff payloads |
AGENT_DESK_OUTBOX_POLL_SECONDS | 10.0 | Background retry poll interval |
AGENT_DESK_OUTBOX_RETRY_SECONDS | 5.0 | Initial retry delay |
AGENT_DESK_OUTBOX_MAX_RETRY_SECONDS | 60.0 | Max retry delay |
AGENT_DESK_WAIT_ESTIMATE_SECONDS | 120 | Wait estimate sent with Agent Desk handoffs |
AGENT_DESK_WAIT_ANNOUNCEMENT_ENABLED | true | Whether the bot announces the wait before handoff |
When ENVIRONMENT=production, VoxCore refuses to start with default secrets or /tmp outbox directories. Use persistent disk paths for outboxes on live hosts.
Production example
VOXBRIDGE_CONFIG_URL=https://api.vohci.com/api/v1/config
VOXCORE_SECRET=your-secret-here
ENVIRONMENT=production
MAX_CONCURRENT_CALLS=1
VOXCORE_WORKERS=16
AUDIO_SAMPLE_RATE=8000
LOG_LEVEL=info
RESULT_OUTBOX_DIR=/var/lib/voxcore/result-outbox
AGENT_DESK_OUTBOX_DIR=/var/lib/voxcore/agent-desk-outbox
MINIO_ENDPOINT=sgp1.digitaloceanspaces.com
MINIO_BUCKET=vohci-matrix
MINIO_SECURE=true
LIVEKIT_URL=wss://livekit.vohci.com
OTEL_ENABLED=false