Skip to main content
Unmute uses environment variables to configure service URLs, API keys, and other settings. This reference documents all available environment variables.

​
Core Service URLs

These variables configure connections between Unmute services.
​
KYUTAI_STT_URL
string
default:"ws://localhost:8090"
WebSocket URL for the speech-to-text service.Supports both ws:// and http:// protocols (automatically converted to WebSocket).Docker Compose default: ws://stt:8080
backend:
  environment:
    - KYUTAI_STT_URL=ws://stt:8080
​
KYUTAI_TTS_URL
string
default:"ws://localhost:8089"
WebSocket URL for the text-to-speech service.Supports both ws:// and http:// protocols (automatically converted to WebSocket).Docker Compose default: ws://tts:8080
backend:
  environment:
    - KYUTAI_TTS_URL=ws://tts:8080
​
KYUTAI_LLM_URL
string
default:"http://localhost:8091"
HTTP URL for the LLM service (OpenAI-compatible API).Docker Compose default: http://llm:8000
backend:
  environment:
    - KYUTAI_LLM_URL=http://llm:8000
​
KYUTAI_LLM_MODEL
string
default:"null"
Override the LLM model name.If not set, the backend uses the default model from the LLM server. Required when using external LLM providers.Example with Ollama:
backend:
  environment:
    - KYUTAI_LLM_URL=http://host.docker.internal:11434
    - KYUTAI_LLM_MODEL=gemma3
    - KYUTAI_LLM_API_KEY=ollama
Example with OpenAI:
backend:
  environment:
    - KYUTAI_LLM_URL=https://api.openai.com/v1
    - KYUTAI_LLM_MODEL=gpt-4o
    - KYUTAI_LLM_API_KEY=sk-...
​
KYUTAI_LLM_API_KEY
string
default:"null"
API key for authenticating with the LLM service.Not required for the default vLLM setup, but necessary for external providers like OpenAI, Anthropic, or Mistral.Example:
backend:
  environment:
    - KYUTAI_LLM_API_KEY=sk-your-api-key
​
KYUTAI_VOICE_CLONING_URL
string
default:"http://localhost:8092"
HTTP URL for the optional voice cloning service.Voice cloning allows users to upload custom voice samples. This service is optional.
​
KYUTAI_REDIS_URL
string
default:"null"
Redis connection URL for distributed caching.If not set, an in-memory dictionary cache is used instead. Redis is recommended for production deployments with multiple backend instances.Example:
backend:
  environment:
    - KYUTAI_REDIS_URL=redis://redis:6379

​
External API Keys

​
HUGGING_FACE_HUB_TOKEN
string
required
Hugging Face access token for downloading gated models.Required for:
  • LLM models (Mistral, Llama, Gemma)
  • Speech-to-text models
  • Text-to-speech models
Format: Starts with hf_Set in your shell before running Docker Compose:
export HUGGING_FACE_HUB_TOKEN=hf_your_token_here
docker compose up
See the Hugging Face Setup guide for details.
​
NEWSAPI_API_KEY
string
default:"null"
API key for NewsAPI.org.Used by the “Dev (news)” character voice to fetch recent news articles from The Verge. Optional feature.Example:
backend:
  environment:
    - NEWSAPI_API_KEY=your_newsapi_key
​
TURN_KEY_ID
string
default:"null"
Cloudflare Calls API key ID for TURN server configuration.Used with TURN_KEY_API_TOKEN to generate ICE servers for WebRTC connections. Optional for most deployments.
​
TURN_KEY_API_TOKEN
string
default:"null"
Cloudflare Calls API token for TURN server configuration.Works with TURN_KEY_ID. See Cloudflare Calls documentation for setup.

​
File Storage

​
KYUTAI_VOICE_DONATION_DIR
path
default:"voices/donation"
Directory for storing voice donation submissions.Relative to the repository root. Used by the voice donation feature.Default: {repo_root}/voices/donation
​
KYUTAI_RECORDINGS_DIR
path
default:"null"
Directory for saving conversation recordings.If not set, recordings are disabled. When enabled, each conversation is saved with audio and event data for debugging.Example:
backend:
  environment:
    - KYUTAI_RECORDINGS_DIR=/app/recordings
  volumes:
    - ./recordings:/app/recordings

​
Development Variables

​
FREESOUND_API_KEY
string
default:"null"
API key for Freesound.org.Only needed if you’re downloading new voice samples from Freesound for character voices. Not required for running Unmute.
​
OPENAI_API_KEY
string
default:"null"
OpenAI API key.Only used in example scripts (example_websocket_client.py). Not required for running Unmute.

​
Configuration Examples

​
Default Docker Compose Setup

services:
  backend:
    environment:
      - KYUTAI_STT_URL=ws://stt:8080
      - KYUTAI_TTS_URL=ws://tts:8080
      - KYUTAI_LLM_URL=http://llm:8000

  llm:
    environment:
      - HUGGING_FACE_HUB_TOKEN=$HUGGING_FACE_HUB_TOKEN

  stt:
    environment:
      - HUGGING_FACE_HUB_TOKEN=$HUGGING_FACE_HUB_TOKEN

  tts:
    environment:
      - HUGGING_FACE_HUB_TOKEN=$HUGGING_FACE_HUB_TOKEN

​
Using External OpenAI API

Replace the local vLLM service with OpenAI: 
services:
  backend:
    environment:
      - KYUTAI_STT_URL=ws://stt:8080
      - KYUTAI_TTS_URL=ws://tts:8080
      - KYUTAI_LLM_URL=https://api.openai.com/v1
      - KYUTAI_LLM_MODEL=gpt-4o
      - KYUTAI_LLM_API_KEY=sk-your-openai-key

  # Remove the llm service entirely

​
Using Ollama Locally

Connect to Ollama running on your host machine: 
services:
  backend:
    environment:
      - KYUTAI_STT_URL=ws://stt:8080
      - KYUTAI_TTS_URL=ws://tts:8080
      - KYUTAI_LLM_URL=http://host.docker.internal:11434
      - KYUTAI_LLM_MODEL=gemma3
      - KYUTAI_LLM_API_KEY=ollama
    extra_hosts:
      - "host.docker.internal:host-gateway"

​
Production Setup with Redis

services:
  backend:
    environment:
      - KYUTAI_STT_URL=ws://stt:8080
      - KYUTAI_TTS_URL=ws://tts:8080
      - KYUTAI_LLM_URL=http://llm:8000
      - KYUTAI_REDIS_URL=redis://redis:6379
      - KYUTAI_RECORDINGS_DIR=/app/recordings
      - NEWSAPI_API_KEY=your_newsapi_key
    volumes:
      - ./recordings:/app/recordings

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

​
Dockerless Environment

For dockerless deployment, set these in your shell: 
# Required
export HUGGING_FACE_HUB_TOKEN=hf_your_token

# Service URLs (using localhost)
export KYUTAI_STT_URL=ws://localhost:8090
export KYUTAI_TTS_URL=ws://localhost:8089
export KYUTAI_LLM_URL=http://localhost:8091

# Optional features
export NEWSAPI_API_KEY=your_newsapi_key
export KYUTAI_RECORDINGS_DIR=/path/to/recordings

# Start services
./dockerless/start_stt.sh
./dockerless/start_tts.sh
./dockerless/start_llm.sh
./dockerless/start_backend.sh
./dockerless/start_frontend.sh

​
Validation

To verify your environment variables are set correctly:
1

Check Required Variables

echo $HUGGING_FACE_HUB_TOKEN
Should output your token starting with hf_.
2

Test Service Health

After starting Unmute, check the health endpoint:
curl http://localhost/api/v1/health
Expected response:
{
  "tts_up": true,
  "stt_up": true,
  "llm_up": true,
  "voice_cloning_up": false,
  "ok": true
}
3

Check Docker Environment

View environment variables in a running container:
docker compose exec backend env | grep KYUTAI

​
Security Best Practices

Never commit API keys or tokens to version control. Always use environment variables.
  • Store sensitive variables in .env files (add to .gitignore)
  • Use separate tokens for development and production
  • Rotate API keys periodically
  • Use read-only Hugging Face tokens for production
  • Consider using secret management tools (AWS Secrets Manager, HashiCorp Vault) for production deployments

Build docs developers (and LLMs) love

Get started for freeTalk to us