Environment Variables

Complete reference for configuring Unmute through environment variables

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