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
/etc/agtos/config.json 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 server configurations where you want a single config file.
// /etc/agtos/config.json (example) { "REDIS_URL" : "redis://redis:6379" , "VOICE_PORT" : "3000" , "LOG_LEVEL" : "info" }
Server Ports Variable Default Description VOICE_PORT3000Voice pipeline WebSocket server (audio streaming, signaling) PORT3000Alias for VOICE_PORT MCP_PORT4100MCP server (Streamable HTTP) HEALTH_PORT4102Health 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— Standard API key (sk-ant-api03- prefix). Pay-per-token billing. ANTHROPIC_AUTH_TOKEN— Max/Pro subscription OAuth token (sk-ant-oat01- prefix). Uses claude CLI subprocess. CLAUDE_CODE_OAUTH_TOKEN— Alias for ANTHROPIC_AUTH_TOKEN CLAUDE_API_KEY— Legacy alias for ANTHROPIC_API_KEY. Auto-detected by token prefix. ANTHROPIC_BASE_URLhttps://api.anthropic.comCustom API endpoint (for proxies or CLI transport)
Token priority order:
ANTHROPIC_AUTH_TOKEN / CLAUDE_CODE_OAUTH_TOKEN — CLI transportANTHROPIC_API_KEY / CLAUDE_API_KEY — SDK transport
See Authentication 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_LIMIT100Max API requests per minute per client IP CHAT_RATE_LIMIT20Max 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_MODELclaude-sonnet-4-20250514Model 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_MODELclaude-haiku-4-5-20251001Model for Agent SDK credential validation CLAUDE_CLI_PATH— (auto-detect) Explicit path to claude CLI binary
Ollama Options Variable Default Description OLLAMA_HOSThttp://localhost:11434Ollama API server URL OLLAMA_DEFAULT_MODELqwen3:4bModel for local query execution (Tier 2) OLLAMA_INTENT_MODELqwen3:1.7bSmall model for intent classification (Tier 1) OLLAMA_URLhttp://localhost:11434Alias used by credential validation
STT / TTS (speaches) Variable Default Description SPEACHES_URLhttp://localhost:8000speaches server base URL (shared by STT and TTS) STT_PROVIDERspeachesSTT provider name SPEACHES_STT_MODELSystran/faster-whisper-smallFaster Whisper model for transcription TTS_PROVIDERspeachesTTS provider name SPEACHES_TTS_MODELspeaches-ai/Kokoro-82M-v1.0-ONNXKokoro model for speech synthesis SPEACHES_TTS_VOICEaf_heartDefault TTS voice ID
Voice Pipeline Variable Default Description COMMAND_PROVIDERmodel-routerLLM provider for the voice pipeline: model-router, claude, or ollama
Redis Variable Default Description REDIS_URLredis://localhost:6379Redis 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_ORIGINhttp://localhost:5173Allowed 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_LEVELinfo (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_ENABLEDfalseEnable mDNS UDP multicast for ESP32 zero-config discovery
Credentials / Encryption Variable Default Description AGTOS_CREDENTIAL_SECRETagtos-dev-secret-...AES-256-GCM encryption key for BYOK credential storage. Change in production. AGTOS_CREDENTIAL_SALT— (random per restart) Hex-encoded 16-byte salt for key derivation. Required in production for persistence across restarts.
Generate a salt:
node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
Config File Variable Default Description AGTOS_CONFIG_PATH/etc/agtos/config.jsonPath to JSON config file. File values fill gaps not covered by env vars.
CLI Variable Default Description AGTOS_API_URLhttp://localhost:4102API base URL for the npx agtos CLI tool
Complete .env.local Example
Full example with all common variables
# === Claude Authentication (pick one) === ANTHROPIC_API_KEY = sk-ant-api03-your-key-here # ANTHROPIC_AUTH_TOKEN=sk-ant-oat01-your-oauth-token # === 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 # === speaches STT/TTS === 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
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.