> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agtos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Complete reference for all agtOS environment variables

agtOS reads configuration from environment variables, with optional file-based config as a fallback. Environment variables always take precedence over config file values.

## Configuration Loading Order

<Steps>
  <Step title="Load .env.local">
    Secrets and local overrides. Never committed to git.
  </Step>

  <Step title="Load .env">
    Shared defaults. Can be committed to git.
  </Step>

  <Step title="Load JSON config file">
    `~/.agtos/config.json` (desktop/user default) or `/etc/agtos/config.json` (system default), or the path in `AGTOS_CONFIG_PATH`. Only fills gaps not covered by env vars.
  </Step>
</Steps>

Environment variables set in `.env.local` or `.env` override the JSON config file. The JSON file is useful for Docker deployments and for storing model slot configuration.

```json ~/.agtos/config.json theme={null}
{
  "REDIS_URL": "redis://redis:6379",
  "LOG_LEVEL": "info",
  "slots": {
    "chat": { "provider": "claude", "model": "claude-sonnet-4-20250514" }
  }
}
```

## Server Ports

| Variable      | Default | Description                                                  |
| ------------- | ------- | ------------------------------------------------------------ |
| `VOICE_PORT`  | `3000`  | Voice pipeline WebSocket server (audio streaming, signaling) |
| `PORT`        | `3000`  | Alias for `VOICE_PORT`                                       |
| `MCP_PORT`    | `4100`  | MCP server (Streamable HTTP)                                 |
| `HEALTH_PORT` | `4102`  | Health endpoints, REST API, metrics, and dashboard           |

<Note>
  The Tauri desktop app and web dashboard connect to the same ports via localhost. The health port serves the REST API, Prometheus metrics, static dashboard files, and health checks.
</Note>

## Authentication

### Claude / Anthropic

| Variable             | Default                     | Description                                                                                                          |
| -------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `ANTHROPIC_API_KEY`  | --                          | API key (`sk-ant-api03-` prefix). Pay-per-token billing from [console.anthropic.com](https://console.anthropic.com). |
| `CLAUDE_API_KEY`     | --                          | Legacy alias for `ANTHROPIC_API_KEY`                                                                                 |
| `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` | Custom API endpoint (for proxies or CLI transport)                                                                   |

### OpenAI

| Variable             | Default                     | Description                                                                                                   |
| -------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `OPENAI_API_KEY`     | --                          | OpenAI API key (`sk-` prefix). Pay-per-token billing from [platform.openai.com](https://platform.openai.com). |
| `OPENAI_BASE_URL`    | `https://api.openai.com/v1` | Custom OpenAI API endpoint (for proxies or compatible APIs)                                                   |
| `OPENAI_MODEL`       | `gpt-4o`                    | Default OpenAI model for chat completions                                                                     |
| `OPENAI_MAX_TOKENS`  | `4096`                      | Maximum output tokens for OpenAI responses                                                                    |
| `OPENAI_TEMPERATURE` | `0.7`                       | Sampling temperature for OpenAI (0.0--2.0)                                                                    |

### Claude Transport

| Variable                 | Default | Description                                                                    |
| ------------------------ | ------- | ------------------------------------------------------------------------------ |
| `AGTOS_CLAUDE_TRANSPORT` | `sdk`   | Claude transport mode: `sdk` (direct API) or `cli` (spawn `claude` CLI binary) |

<Note>
  Cloud provider selection (Claude vs OpenAI) is no longer configured via environment variable. It is now set per slot in `~/.agtos/config.json` via the Model Slot Registry ([ADR-020](/architecture/decisions#adr-020)). Run `agtos setup` to configure slots interactively.
</Note>

See [Authentication](/configuration/authentication) and [Providers](/configuration/providers#router-configuration) for detailed setup instructions.

### API Security

| Variable          | Default       | Description                                                                                          |
| ----------------- | ------------- | ---------------------------------------------------------------------------------------------------- |
| `AGTOS_API_KEY`   | -- (disabled) | When set, all `/api/*` routes require `Authorization: Bearer <key>`. When unset, endpoints are open. |
| `API_RATE_LIMIT`  | `100`         | Max API requests per minute per client IP                                                            |
| `CHAT_RATE_LIMIT` | `20`          | Max chat/task requests per minute per client IP                                                      |

<Warning>
  In production, always set `AGTOS_API_KEY` to protect the REST API. Without it, all endpoints are unauthenticated.
</Warning>

## Claude Options

| Variable              | Default                     | Description                                                        |
| --------------------- | --------------------------- | ------------------------------------------------------------------ |
| `CLAUDE_MODEL`        | `claude-sonnet-4-20250514`  | Model for cloud inference via the model router                     |
| `CLAUDE_THINKING`     | -- (SDK default)            | Adaptive thinking mode: `adaptive`, `enabled`, `disabled`          |
| `CLAUDE_EFFORT`       | -- (SDK default)            | Effort level: `low`, `medium`, `high`, `max` (max = Opus 4.6 only) |
| `CLAUDE_SERVICE_TIER` | -- (SDK default)            | Service tier: `auto` (priority if available), `standard_only`      |
| `CLAUDE_AGENT_MODEL`  | `claude-haiku-4-5-20251001` | Model for Agent SDK credential validation                          |
| `CLAUDE_CLI_PATH`     | -- (auto-detect)            | Explicit path to `claude` CLI binary                               |

## Ollama Options

| Variable               | Default                  | Description                                    |
| ---------------------- | ------------------------ | ---------------------------------------------- |
| `OLLAMA_HOST`          | `http://localhost:11434` | Ollama API server URL                          |
| `OLLAMA_DEFAULT_MODEL` | `qwen3:4b`               | Model for local query execution (Tier 2)       |
| `OLLAMA_INTENT_MODEL`  | `qwen3:1.7b`             | Small model for intent classification (Tier 1) |
| `OLLAMA_URL`           | `http://localhost:11434` | Alias used by credential validation            |

## STT / TTS

| Variable             | Default                            | Description                                      |
| -------------------- | ---------------------------------- | ------------------------------------------------ |
| `SPEACHES_URL`       | `http://localhost:8000`            | speaches server base URL (shared by STT and TTS) |
| `STT_PROVIDER`       | `sherpa-onnx`                      | STT provider name                                |
| `SPEACHES_STT_MODEL` | `Systran/faster-whisper-small`     | Faster Whisper model for transcription           |
| `TTS_PROVIDER`       | `sherpa-onnx`                      | TTS provider name                                |
| `SPEACHES_TTS_MODEL` | `speaches-ai/Kokoro-82M-v1.0-ONNX` | Kokoro model for speech synthesis                |
| `SPEACHES_TTS_VOICE` | `af_heart`                         | Default TTS voice ID                             |

## sherpa-onnx (In-Process Speech Engine)

<Note>
  sherpa-onnx is the default provider. These variables tune its behavior. Set `STT_PROVIDER=speaches` or `TTS_PROVIDER=speaches` to use the external server instead.
</Note>

### STT Configuration

| Variable                     | Default                      | Description                                                        |
| ---------------------------- | ---------------------------- | ------------------------------------------------------------------ |
| `STT_PROVIDER`               | `sherpa-onnx`                | Default in-process engine. Set to `speaches` for external server   |
| `SHERPA_STT_MODEL`           | `moonshine-tiny-en-int8`     | STT model ID                                                       |
| `SHERPA_STT_STREAMING_MODEL` | `zipformer-streaming-en-20m` | Streaming STT model ID                                             |
| `SHERPA_STT_NUM_THREADS`     | `4`                          | ONNX Runtime inference threads                                     |
| `SHERPA_STT_PROVIDER`        | `cpu`                        | Execution provider (`cpu`, `cuda`, `coreml`)                       |
| `SHERPA_STT_LANGUAGE`        | `en`                         | Default language                                                   |
| `SHERPA_STT_TIMEOUT_MS`      | `30000`                      | Inference timeout in milliseconds                                  |
| `SHERPA_STT_TIMESTAMPS`      | `true`                       | Enable word-level timestamps in transcription                      |
| `SHERPA_STT_ENDPOINT`        | `true`                       | Enable endpoint detection (auto-detect end of speech in streaming) |

### TTS Configuration

| Variable                     | Default                | Description                                                      |
| ---------------------------- | ---------------------- | ---------------------------------------------------------------- |
| `TTS_PROVIDER`               | `sherpa-onnx`          | Default in-process engine. Set to `speaches` for external server |
| `SHERPA_TTS_MODEL`           | `kokoro-int8-multi-v1` | TTS model ID                                                     |
| `SHERPA_TTS_VOICE`           | `af_heart`             | Default voice                                                    |
| `SHERPA_TTS_SPEED`           | `1.0`                  | Speech speed (0.5-2.0)                                           |
| `SHERPA_TTS_NUM_THREADS`     | `2`                    | ONNX Runtime threads per TTS instance                            |
| `SHERPA_TTS_POOL_SIZE`       | `3`                    | Concurrent TTS instances                                         |
| `SHERPA_TTS_POOL_TIMEOUT_MS` | `30000`                | Timeout for acquiring a TTS instance from the pool               |
| `SHERPA_TTS_TIMEOUT_MS`      | `30000`                | Per-request TTS inference timeout                                |
| `SHERPA_TTS_MAX_SENTENCES`   | `99`                   | Maximum sentences per synthesis batch                            |

### VAD Configuration

| Variable                    | Default      | Description                            |
| --------------------------- | ------------ | -------------------------------------- |
| `SHERPA_VAD_MODEL`          | `silero-vad` | VAD model ID                           |
| `SHERPA_VAD_THRESHOLD`      | `0.3`        | Speech detection threshold (0.0-1.0)   |
| `SHERPA_VAD_MIN_SPEECH`     | `0.25`       | Minimum speech duration (seconds)      |
| `SHERPA_VAD_MIN_SILENCE`    | `0.5`        | Silence gap to end segment (seconds)   |
| `SHERPA_VAD_MAX_SPEECH`     | `20`         | Maximum segment before split (seconds) |
| `SHERPA_VAD_WINDOW_SIZE`    | `512`        | Audio frame size for VAD processing    |
| `SHERPA_VAD_NUM_THREADS`    | `1`          | CPU threads for VAD inference          |
| `SHERPA_VAD_BUFFER_SECONDS` | `60`         | Audio history buffer size (seconds)    |

### Model Storage

| Variable                | Default           | Description                                                                                                                                                                            |
| ----------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGTOS_MODEL_DIR`       | `~/.agtos/models` | Local directory for ONNX model files                                                                                                                                                   |
| `AGTOS_ORT_RUNTIME_DIR` | -- (dev: unused)  | Absolute path to bundled ONNX Runtime binaries. Set automatically by the Tauri sidecar in desktop builds. In development, leave unset — onnxruntime-node resolves from `node_modules`. |

## Voice Pipeline

| Variable           | Default        | Description                                                                |
| ------------------ | -------------- | -------------------------------------------------------------------------- |
| `COMMAND_PROVIDER` | `model-router` | LLM provider for the voice pipeline: `model-router`, `claude`, or `ollama` |

## Cognitive Task Providers

These variables configure independent provider selection for specialized AI tasks ([ADR-018](/architecture/decisions#adr-018)). Each task can use a different provider (`ollama`, `claude`, or `openrouter`), allowing you to optimize cost, quality, and privacy per task.

| Variable                       | Default                  | Description                                                                 |
| ------------------------------ | ------------------------ | --------------------------------------------------------------------------- |
| `AGTOS_EMBEDDING_PROVIDER`     | `ollama`                 | Embedding provider (`ollama` for local, `openrouter` for cloud)             |
| `AGTOS_EMBEDDING_MODEL`        | `nomic-embed-text`       | Embedding model                                                             |
| `AGTOS_CLASSIFIER_PROVIDER`    | `ollama`                 | Intent classification provider                                              |
| `AGTOS_CLASSIFIER_MODEL`       | -- (uses Ollama default) | Intent classification model                                                 |
| `AGTOS_CONSOLIDATION_PROVIDER` | --                       | Memory consolidation (Dreamer) provider                                     |
| `AGTOS_CONSOLIDATION_MODEL`    | --                       | Memory consolidation model                                                  |
| `AGTOS_REASONING_PROVIDER`     | --                       | User reasoning (Dialectic) provider                                         |
| `AGTOS_REASONING_MODEL`        | --                       | User reasoning model                                                        |
| `AGTOS_SUMMARIZATION_PROVIDER` | --                       | Conversation summarization provider                                         |
| `AGTOS_SUMMARIZATION_MODEL`    | --                       | Conversation summarization model                                            |
| `OPENROUTER_API_KEY`           | --                       | OpenRouter API key (required when using `openrouter` provider for any task) |
| `OPENROUTER_HTTP_REFERER`      | --                       | Attribution header for the OpenRouter leaderboard. Optional.                |
| `OPENROUTER_X_TITLE`           | `agtOS`                  | App name header sent to OpenRouter for attribution.                         |

<Info>
  These settings are also configurable at runtime via `PUT /api/settings`. Changes to provider settings require a provider restart to take effect.
</Info>

## Memory Maintenance

These variables control the periodic memory lint sweep and its background-work gating ([ADR-021](/architecture/decisions#adr-021), [ADR-027](/architecture/decisions#adr-027)). See [Memory System](/features/memory#maintenance-mode-memory-lint) for the user-facing description.

| Variable                            | Default     | Description                                                                                                                                                                                             |
| ----------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGTOS_MAINTENANCE_ENABLED`         | `true`      | Kill switch for memory maintenance. Set to `false` to disable both auto-registered and manually-created schedules, plus any direct event publishes on `memory.maintenance`.                             |
| `AGTOS_MAINTENANCE_SCHEDULE`        | `0 3 * * *` | Cron expression for the auto-registered `memory-maintenance` task.                                                                                                                                      |
| `AGTOS_MAINTENANCE_TIMEZONE`        | `UTC`       | IANA timezone (e.g., `America/New_York`) used to evaluate the maintenance cron expression. Validated via `Intl.DateTimeFormat` at startup.                                                              |
| `AGTOS_BACKGROUND_WORK_POLICY`      | `auto`      | ResourceGuard policy: `auto` (default — runs all checks), `always` (skip all checks; dedicated GPU hosts), `idle-only` (stricter 0.3×CPU load threshold; POSIX only).                                   |
| `AGTOS_NLI_ENABLED`                 | `true`      | Kill switch for the NLI cross-encoder (Stage 2) in the 3-stage contradiction pipeline. When `false`, Stage 2 is skipped and Stage 3 (LLM judge) receives the full candidate list from Stage 1 directly. |
| `AGTOS_NLI_MODEL_SIZE`              | `base`      | DeBERTa-v3 model variant for the Stage 2 cross-encoder: `xsmall`, `small`, `base`, or `disabled`. Requires server restart.                                                                              |
| `AGTOS_NLI_CONTRADICTION_THRESHOLD` | `0.7`       | Softmax confidence floor for the NLI contradiction verdict (0.0–1.0). Higher values = fewer false positives. Takes effect immediately.                                                                  |
| `AGTOS_PAIR_CACHE_TTL_SECONDS`      | `604800`    | Redis TTL for NLI pair classification cache (default 7 days). Takes effect immediately.                                                                                                                 |
| `AGTOS_MCP_SERVERS`                 | --          | JSON string describing external MCP servers to connect at startup. Malformed JSON logs a warning and proceeds with no servers.                                                                          |

## Provider Catalog

These variables control model discovery and caching for the [ProviderCatalog](/configuration/providers#provider-catalog) system ([ADR-026](/architecture/decisions#adr-026)).

| Variable                                   | Default | Description                                                                                                                                                   |
| ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGTOS_PROVIDER_CATALOG_CACHE_TTL_SECONDS` | `3600`  | Catalog model-list cache expiry in seconds (default 1 hour). Lower values give fresher model lists but increase upstream API calls. Takes effect immediately. |
| `AGTOS_PROVIDER_CATALOG_AUTO_REFRESH`      | `true`  | Enable background refresh of cached provider catalogs. Set to `false` to only fetch catalogs on demand. Requires provider restart.                            |

## Redis

| Variable         | Default                  | Description                                                                                   |
| ---------------- | ------------------------ | --------------------------------------------------------------------------------------------- |
| `REDIS_URL`      | `redis://localhost:6379` | Redis connection URL. Used for sessions, memory, scheduler, events, devices, and preferences. |
| `REDIS_HOST`     | --                       | Alternative to `REDIS_URL` (host component)                                                   |
| `REDIS_PORT`     | --                       | Alternative to `REDIS_URL` (port component)                                                   |
| `REDIS_PASSWORD` | --                       | Redis auth password (if using authenticated Redis)                                            |

<Info>
  Redis is optional but recommended. Without it, the scheduler, episodic/semantic memory, device registry, and user preferences are disabled. Session management falls back to in-memory storage.
</Info>

## Networking

| Variable      | Default                 | Description                                                           |
| ------------- | ----------------------- | --------------------------------------------------------------------- |
| `CORS_ORIGIN` | `http://localhost:5173` | Allowed CORS origins (comma-separated). Tauri origins are auto-added. |

Tauri 2 desktop app origins (`tauri://localhost`, `https://tauri.localhost`) are always included regardless of `CORS_ORIGIN`.

## Logging

| Variable    | Default                                    | Description                                                   |
| ----------- | ------------------------------------------ | ------------------------------------------------------------- |
| `LOG_LEVEL` | `info` (production), `debug` (development) | Log level: `trace`, `debug`, `info`, `warn`, `error`, `fatal` |
| `NODE_ENV`  | --                                         | Set to `production` for JSON structured logging               |

## Feature Flags

| Variable             | Default | Description                                               |
| -------------------- | ------- | --------------------------------------------------------- |
| `AGTOS_MDNS_ENABLED` | `false` | Enable mDNS UDP multicast for ESP32 zero-config discovery |

## Runtime Configuration (Hot-Reload)

These variables are managed by the Settings API (`PUT /api/settings`) and the legacy config API (`PUT /api/config`). They can be changed at runtime without restarting the server.

| Variable                       | Default                      | Reload Type      | Description                                         |
| ------------------------------ | ---------------------------- | ---------------- | --------------------------------------------------- |
| `AGTOS_TTS_VOICE`              | `af_heart`                   | immediate        | TTS voice name                                      |
| `AGTOS_TTS_SPEED`              | `1.0`                        | immediate        | TTS speech speed (0.5--2.0)                         |
| `AGTOS_STT_LANGUAGE`           | `en`                         | provider-restart | STT language code                                   |
| `AGTOS_STT_MODEL`              | `moonshine-tiny-en-int8`     | provider-restart | STT model ID                                        |
| `AGTOS_STT_STREAMING_MODEL`    | `zipformer-streaming-en-20m` | provider-restart | Streaming STT model ID                              |
| `AGTOS_LLM_PROVIDER`           | --                           | provider-restart | Primary LLM provider (`claude`, `ollama`, `auto`)   |
| `AGTOS_LLM_MODEL`              | --                           | provider-restart | LLM model name                                      |
| `AGTOS_API_RATE_LIMIT`         | --                           | immediate        | API rate limit per minute (1--1000)                 |
| `AGTOS_CHAT_RATE_LIMIT`        | --                           | immediate        | Chat rate limit per minute (1--100)                 |
| `AGTOS_MEMORY_SEARCH_MODE`     | `hybrid`                     | immediate        | Memory search strategy (`hybrid`, `vector`, `bm25`) |
| `AGTOS_MEMORY_QUERY_EXPANSION` | `false`                      | immediate        | Enable Ollama-powered query expansion               |
| `AGTOS_VAD_THRESHOLD`          | `0.3`                        | immediate        | VAD speech detection threshold (0.0--1.0)           |
| `AGTOS_VAD_SENSITIVITY`        | --                           | immediate        | VAD sensitivity preset (`low`, `medium`, `high`)    |
| `AGTOS_AUDIO_INPUT_DEVICE`     | --                           | provider-restart | Audio input device ID                               |
| `AGTOS_MEMORY_RETENTION_DAYS`  | `30`                         | immediate        | Memory retention in days (1--365)                   |
| `AGTOS_NOTIFICATIONS_ENABLED`  | --                           | immediate        | Enable desktop notifications                        |
| `AGTOS_PTT_HOTKEY`             | --                           | immediate        | Push-to-talk hotkey (e.g., `Alt+Space`)             |

<Note>
  The `API_RATE_LIMIT` and `CHAT_RATE_LIMIT` variables (without the `AGTOS_` prefix) are used at server startup. The `AGTOS_` prefixed versions are used by the runtime config system for hot-reload. Both control the same behavior — set the non-prefixed versions in `.env.local` for startup defaults, and use the Settings API to adjust at runtime.
</Note>

## Credentials / Encryption

| Variable                  | Default                     | Description                                                                                                                                                                                                 |
| ------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGTOS_CREDENTIAL_SECRET` | -- (auto-generated)         | Overrides the machine secret for AES-256-GCM encryption. By default, a 32-byte secret is auto-generated at `~/.agtos/.secret`. Set this env var for Docker/CI where filesystem persistence isn't available. |
| `AGTOS_CREDENTIAL_SALT`   | -- (auto-generated)         | Hex-encoded salt for scrypt key derivation. By default, a 32-byte salt is auto-generated at `~/.agtos/.salt`. Set this env var for Docker/CI deployments.                                                   |
| `AGTOS_CREDENTIAL_PATH`   | `~/.agtos/credentials.json` | Path to the AES-256-GCM encrypted credential file.                                                                                                                                                          |

<Note>
  Credentials are stored encrypted at `~/.agtos/credentials.json` with 0o600 permissions. Key derivation uses scrypt (N=16384, r=8, p=1) with AAD binding per provider. The machine secret (`~/.agtos/.secret`) and salt (`~/.agtos/.salt`) are auto-generated on first use. For Docker deployments, set `AGTOS_CREDENTIAL_SECRET` and `AGTOS_CREDENTIAL_SALT` as environment variables so credentials persist across container restarts.
</Note>

Generate values for Docker:

```bash theme={null}
# Generate a credential secret (32 random bytes, hex-encoded)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Generate a salt (32 random bytes, hex-encoded)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

## Config File

| Variable            | Default                | Description                                                                                                                                                 |
| ------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGTOS_CONFIG_PATH` | `~/.agtos/config.json` | Path to JSON config file. Defaults to `~/.agtos/config.json` (desktop) or `/etc/agtos/config.json` (system). File values fill gaps not covered by env vars. |

## CLI

| Variable        | Default                 | Description                               |
| --------------- | ----------------------- | ----------------------------------------- |
| `AGTOS_API_URL` | `http://localhost:4102` | API base URL for the `npx agtos` CLI tool |

## Complete `.env.local` Example

<Accordion title="Full example with all common variables">
  ```bash theme={null}
  # === Claude Authentication ===
  ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

  # === OpenAI Authentication (optional) ===
  # OPENAI_API_KEY=sk-your-key-here

  # === Claude Transport ===
  # AGTOS_CLAUDE_TRANSPORT=sdk           # 'sdk' (default) or 'cli'
  # Note: Cloud provider selection is now per-slot in ~/.agtos/config.json

  # === Claude Options ===
  CLAUDE_MODEL=claude-sonnet-4-20250514
  CLAUDE_THINKING=adaptive
  CLAUDE_EFFORT=medium
  CLAUDE_SERVICE_TIER=auto

  # === Ollama ===
  OLLAMA_HOST=http://localhost:11434
  OLLAMA_DEFAULT_MODEL=qwen3:4b
  OLLAMA_INTENT_MODEL=qwen3:1.7b

  # === sherpa-onnx (in-process, default) ===
  STT_PROVIDER=sherpa-onnx
  TTS_PROVIDER=sherpa-onnx
  SHERPA_STT_MODEL=moonshine-tiny-en-int8
  SHERPA_TTS_MODEL=kokoro-int8-multi-v1
  SHERPA_TTS_VOICE=af_heart
  AGTOS_MODEL_DIR=~/.agtos/models

  # === speaches STT/TTS (external server fallback) ===
  # STT_PROVIDER=speaches
  # TTS_PROVIDER=speaches
  # SPEACHES_URL=http://localhost:8000
  # SPEACHES_STT_MODEL=Systran/faster-whisper-small
  # SPEACHES_TTS_MODEL=speaches-ai/Kokoro-82M-v1.0-ONNX
  # SPEACHES_TTS_VOICE=af_heart

  # === Voice Pipeline ===
  COMMAND_PROVIDER=model-router

  # === Redis ===
  REDIS_URL=redis://localhost:6379

  # === Ports ===
  VOICE_PORT=3000
  MCP_PORT=4100
  HEALTH_PORT=4102

  # === Security ===
  AGTOS_API_KEY=your-secret-api-key
  API_RATE_LIMIT=100
  CHAT_RATE_LIMIT=20
  AGTOS_CREDENTIAL_SALT=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

  # === Networking ===
  CORS_ORIGIN=http://localhost:5173

  # === Logging ===
  LOG_LEVEL=info
  NODE_ENV=production

  # === Features ===
  AGTOS_MDNS_ENABLED=false

  # === Cognitive Task Providers (optional) ===
  # AGTOS_EMBEDDING_PROVIDER=ollama
  # AGTOS_EMBEDDING_MODEL=nomic-embed-text
  # AGTOS_CLASSIFIER_PROVIDER=ollama
  # AGTOS_CONSOLIDATION_PROVIDER=ollama
  # AGTOS_REASONING_PROVIDER=ollama
  # AGTOS_SUMMARIZATION_PROVIDER=ollama
  # OPENROUTER_API_KEY=sk-or-your-key  # Only needed for openrouter provider
  ```
</Accordion>

## Docker Environment

When running with Docker, set variables via `docker-compose.yml` or `docker run -e`:

```yaml theme={null}
# docker-compose.yml (excerpt)
services:
  agtos:
    environment:
      - REDIS_URL=redis://redis:6379
      - VOICE_PORT=3000
      - MCP_PORT=4100
      - HEALTH_PORT=4102
      - OLLAMA_HOST=http://host.docker.internal:11434
      - SPEACHES_URL=http://host.docker.internal:8000
      - NODE_ENV=production
    env_file:
      - .env.local  # secrets
```

<Tip>
  Use `host.docker.internal` to reach services running on the Docker host (like Ollama or speaches). On Linux, you may need `--network=host` or extra Docker config instead.
</Tip>