> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/kyutai-labs/unmute/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField path="KYUTAI_STT_URL" type="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`

  ```yaml theme={null}
  backend:
    environment:
      - KYUTAI_STT_URL=ws://stt:8080
  ```
</ParamField>

<ParamField path="KYUTAI_TTS_URL" type="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`

  ```yaml theme={null}
  backend:
    environment:
      - KYUTAI_TTS_URL=ws://tts:8080
  ```
</ParamField>

<ParamField path="KYUTAI_LLM_URL" type="string" default="http://localhost:8091">
  HTTP URL for the LLM service (OpenAI-compatible API).

  **Docker Compose default**: `http://llm:8000`

  ```yaml theme={null}
  backend:
    environment:
      - KYUTAI_LLM_URL=http://llm:8000
  ```
</ParamField>

<ParamField path="KYUTAI_LLM_MODEL" type="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**:

  ```yaml theme={null}
  backend:
    environment:
      - KYUTAI_LLM_URL=http://host.docker.internal:11434
      - KYUTAI_LLM_MODEL=gemma3
      - KYUTAI_LLM_API_KEY=ollama
  ```

  **Example with OpenAI**:

  ```yaml theme={null}
  backend:
    environment:
      - KYUTAI_LLM_URL=https://api.openai.com/v1
      - KYUTAI_LLM_MODEL=gpt-4o
      - KYUTAI_LLM_API_KEY=sk-...
  ```
</ParamField>

<ParamField path="KYUTAI_LLM_API_KEY" type="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**:

  ```yaml theme={null}
  backend:
    environment:
      - KYUTAI_LLM_API_KEY=sk-your-api-key
  ```
</ParamField>

<ParamField path="KYUTAI_VOICE_CLONING_URL" type="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.
</ParamField>

<ParamField path="KYUTAI_REDIS_URL" type="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**:

  ```yaml theme={null}
  backend:
    environment:
      - KYUTAI_REDIS_URL=redis://redis:6379
  ```
</ParamField>

## External API Keys

<ParamField path="HUGGING_FACE_HUB_TOKEN" type="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:

  ```bash theme={null}
  export HUGGING_FACE_HUB_TOKEN=hf_your_token_here
  docker compose up
  ```

  See the [Hugging Face Setup guide](/configuration/huggingface-setup) for details.
</ParamField>

<ParamField path="NEWSAPI_API_KEY" type="string" default="null">
  API key for [NewsAPI.org](https://newsapi.org).

  Used by the "Dev (news)" character voice to fetch recent news articles from The Verge. Optional feature.

  **Example**:

  ```yaml theme={null}
  backend:
    environment:
      - NEWSAPI_API_KEY=your_newsapi_key
  ```
</ParamField>

<ParamField path="TURN_KEY_ID" type="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.
</ParamField>

<ParamField path="TURN_KEY_API_TOKEN" type="string" default="null">
  Cloudflare Calls API token for TURN server configuration.

  Works with `TURN_KEY_ID`. See [Cloudflare Calls documentation](https://developers.cloudflare.com/calls/) for setup.
</ParamField>

## File Storage

<ParamField path="KYUTAI_VOICE_DONATION_DIR" type="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`
</ParamField>

<ParamField path="KYUTAI_RECORDINGS_DIR" type="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**:

  ```yaml theme={null}
  backend:
    environment:
      - KYUTAI_RECORDINGS_DIR=/app/recordings
    volumes:
      - ./recordings:/app/recordings
  ```
</ParamField>

## Development Variables

<ParamField path="FREESOUND_API_KEY" type="string" default="null">
  API key for [Freesound.org](https://freesound.org).

  Only needed if you're downloading new voice samples from Freesound for character voices. Not required for running Unmute.
</ParamField>

<ParamField path="OPENAI_API_KEY" type="string" default="null">
  OpenAI API key.

  Only used in example scripts (`example_websocket_client.py`). Not required for running Unmute.
</ParamField>

## Configuration Examples

### Default Docker Compose Setup

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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

```yaml theme={null}
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:

```bash theme={null}
# 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:

<Steps>
  <Step title="Check Required Variables">
    ```bash theme={null}
    echo $HUGGING_FACE_HUB_TOKEN
    ```

    Should output your token starting with `hf_`.
  </Step>

  <Step title="Test Service Health">
    After starting Unmute, check the health endpoint:

    ```bash theme={null}
    curl http://localhost/api/v1/health
    ```

    Expected response:

    ```json theme={null}
    {
      "tts_up": true,
      "stt_up": true,
      "llm_up": true,
      "voice_cloning_up": false,
      "ok": true
    }
    ```
  </Step>

  <Step title="Check Docker Environment">
    View environment variables in a running container:

    ```bash theme={null}
    docker compose exec backend env | grep KYUTAI
    ```
  </Step>
</Steps>

## Security Best Practices

<Warning>
  Never commit API keys or tokens to version control. Always use environment variables.
</Warning>

* 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.