Skip to main content

​
Environment variables

VoiceGateway reads environment variables for configuration overrides, daemon binding, secret material, and provider API keys. Variables can also be referenced in voicegw.yaml using ${VAR_NAME} syntax.

​
VoiceGateway variables

VariablePurposeExample
VOICEGW_CONFIGOverride the config file path. Skips the default search order./opt/voicegw/config.yaml
VOICEGW_DB_PATHOverride the SQLite database path. Also enables cost tracking when set.~/.config/voicegateway/voicegw.db
VOICEGW_HOSTBind host for python -m voicegateway.server.main (the Docker entrypoint). The CLI uses serve.host from the config; this var is for module invocations.127.0.0.1
VOICEGW_PORTBind port for python -m voicegateway.server.main. Same scope as VOICEGW_HOST.8080
VOICEGW_SECRETFernet key for encrypting managed-provider API keys before they land in SQLite. Generate with python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())".(44-char base64 string)
VOICEGW_SECRET_FALLBACKComma-separated previous Fernet keys for rotation. Lets voicegw rotate-secret re-encrypt rows that were stored under an older key.(44-char base64 string)
VOICEGW_MCP_TOKENBearer token for authenticating MCP server requests when running over HTTP/SSE.mcp-secret-token

​
Provider API keys

Each cloud provider reads its API key from a standard environment variable. These are referenced in voicegw.yaml via ${VAR_NAME} substitution.
VariableProviderRequired for
DEEPGRAM_API_KEYDeepgramSTT, TTS
OPENAI_API_KEYOpenAISTT, LLM, TTS
ANTHROPIC_API_KEYAnthropicLLM
GROQ_API_KEYGroqSTT, LLM
CARTESIA_API_KEYCartesiaTTS
ELEVENLABS_API_KEYElevenLabsTTS
ASSEMBLYAI_API_KEYAssemblyAISTT

​
How substitution works

In voicegw.yaml, any string value can reference an environment variable using ${VAR_NAME}: 
providers:
  deepgram:
    api_key: ${DEEPGRAM_API_KEY}
  openai:
    api_key: ${OPENAI_API_KEY}
    base_url: ${OPENAI_BASE_URL}
VoiceGateway substitutes these at config load time. If the environment variable is not set, it resolves to an empty string. Substitution works recursively through all dicts and lists in the config.

​
Setting environment variables

​
Shell export

export DEEPGRAM_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"
export VOICEGW_DB_PATH="~/.config/voicegateway/voicegw.db"

​
.env file

VoiceGateway does not load .env files automatically. Use a tool like direnv or dotenv if you prefer file-based env var management: 
# With direnv
echo 'export DEEPGRAM_API_KEY="your-key"' >> .envrc
direnv allow

​
Docker

docker compose up -d \
  -e DEEPGRAM_API_KEY=your-key \
  -e OPENAI_API_KEY=your-key \
  -e VOICEGW_SECRET=your-secret
Or in docker-compose.yml: 
services:
  voicegw:
    environment:
      - DEEPGRAM_API_KEY=${DEEPGRAM_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - VOICEGW_SECRET=${VOICEGW_SECRET}

​
Config search order

When VOICEGW_CONFIG is not set, VoiceGateway searches for config in this order:
  1. ./voicegw.yaml
  2. ~/.config/voicegateway/voicegw.yaml
  3. /etc/voicegateway/voicegw.yaml
voicegw onboard writes to the second path by default. See voicegw.yaml reference, Providers, Installation.