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

Load .env.local

Secrets and local overrides. Never committed to git.

Load .env

Shared defaults. Can be committed to git.

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.

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.

~/.agtos/config.json

{
  "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

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.

Authentication

Claude / Anthropic

Variable	Default	Description
`ANTHROPIC_API_KEY`	—	API key (`sk-ant-api03-` prefix). Pay-per-token billing from 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.
`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)

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). Run agtos setup to configure slots interactively.

See Authentication and Providers 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

In production, always set AGTOS_API_KEY to protect the REST API. Without it, all endpoints are unauthenticated.

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)

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.

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

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

Memory Maintenance

These variables control the periodic memory lint sweep and its background-work gating (ADR-021, ADR-027). See Memory System 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 system (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)

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.

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`)

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.

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.

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.

Generate values for Docker:

# 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

Full example with all common variables

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

Docker Environment

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

# 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

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.

Documentation Index

​Configuration Loading Order

​Server Ports

​Authentication

​Claude / Anthropic

​OpenAI

​Claude Transport

​API Security

​Claude Options

​Ollama Options

​STT / TTS

​sherpa-onnx (In-Process Speech Engine)

​STT Configuration

​TTS Configuration

​VAD Configuration

​Model Storage

​Voice Pipeline

​Cognitive Task Providers

​Memory Maintenance

​Provider Catalog

​Redis

​Networking

​Logging

​Feature Flags

​Runtime Configuration (Hot-Reload)

​Credentials / Encryption

​Config File

​CLI

​Complete .env.local Example

​Docker Environment

Configuration Loading Order

Server Ports

Authentication

Claude / Anthropic

OpenAI

Claude Transport

API Security

Claude Options

Ollama Options

STT / TTS

sherpa-onnx (In-Process Speech Engine)

STT Configuration

TTS Configuration

VAD Configuration

Model Storage

Voice Pipeline

Cognitive Task Providers

Memory Maintenance

Provider Catalog

Redis

Networking

Logging

Feature Flags

Runtime Configuration (Hot-Reload)

Credentials / Encryption

Config File

CLI

Complete `.env.local` Example

Docker Environment