Self-host AVA Core

AVA Core README

How to install AVA Core

.env (prepared by preflight.sh; JWT_SECRET, ASTERISK_HOST, UVICORN_PORT etc.)

git clone --branch v7.6.4 https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git
cd AVA-AI-Voice-Agent-for-Asterisk
sudo ./preflight.sh --apply-fixes
docker compose -p asterisk-ai-voice-agent up -d --build admin_ui

How to configure AVA Core

• AAVA_ELEVENLABS_OUTPUT_RESAMPLER
• AAVA_GOOGLE_OUTPUT_RESAMPLER
• AAVA_GROK_OUTPUT_RESAMPLER
• AAVA_MEDIA_DIRShared media dir for outbound recordings (voicemail drop + consent prompt):

  Shared media dir for outbound recordings (voicemail drop + consent prompt):

• AAVA_OPENAI_OUTPUT_RESAMPLEROptional emergency/canary override for full-agent outbound downsampling. Prefer selecting `telephony_enhanced_8k` on an Agent. Provider and pipeline settings normally use `inherit`; these environment values take precedence after ai_engine is recreated: linear = compatibility behavior (default and immediate rollback) bandlimited = alias-safe 16/24 kHz -> 8 kHz telephony downsampling They are n

  Optional emergency/canary override for full-agent outbound downsampling. Prefer selecting `telephony_enhanced_8k` on an Agent. Provider and pipeline settings normally use `inherit`; these environment values take precedence after ai_engine is recreated: linear = compatibility behavior (default and immediate rollback) bandlimited = alias-safe 16/24 kHz -> 8 kHz telephony downsampling They are n

• AAVA_OUTBOUND_AMD_CONTEXTDialplan context used for the AMD hop (engine uses ARI continueInDialplan):

  Dialplan context used for the AMD hop (engine uses ARI continueInDialplan):

• AAVA_OUTBOUND_ATTEMPT_STALE_SECONDSSeconds before an outbound attempt that never reaches a live session is treated as stale. The same value is used for startup recovery and the runtime watchdog (minimum 10 seconds):

  Seconds before an outbound attempt that never reaches a live session is treated as stale. The same value is used for startup recovery and the runtime watchdog (minimum 10 seconds):

• AAVA_OUTBOUND_CHANNEL_TECHChannel technology for internal extension probing: auto (default, tries PJSIP then SIP) | pjsip | sip | local_only (skip probing)

  Channel technology for internal extension probing: auto (default, tries PJSIP then SIP) | pjsip | sip | local_only (skip probing)

• AAVA_OUTBOUND_DIAL_CONTEXTAsterisk dialplan context for Local/ channel origination: FreePBX: from-internal (default) | custom context

  Asterisk dialplan context for Local/ channel origination: FreePBX: from-internal (default) | custom context

• AAVA_OUTBOUND_DIAL_PREFIXDial prefix prepended to phone number before routing (carrier selection): FreePBX: empty (default) | custom carrier prefix

  Dial prefix prepended to phone number before routing (carrier selection): FreePBX: empty (default) | custom carrier prefix

• AAVA_OUTBOUND_EXTENSION_IDENTITY═══════════════════════════════════════════════════════════════════════════ OPTIONAL (v5.0.0): Outbound Campaign Dialer (Alpha) ═══════════════════════════════════════════════════════════════════════════ Outbound calling is managed from Admin UI → Call Scheduling. It assumes your trunk(s) and outbound routes are already configured in Asterisk/FreePBX. Extension identity used for FreePBX routing (s

  ═══════════════════════════════════════════════════════════════════════════ OPTIONAL (v5.0.0): Outbound Campaign Dialer (Alpha) ═══════════════════════════════════════════════════════════════════════════ Outbound calling is managed from Admin UI → Call Scheduling. It assumes your trunk(s) and outbound routes are already configured in Asterisk/FreePBX. Extension identity used for FreePBX routing (s

• AAVA_OUTBOUND_LEAD_IMPORT_MAX_BYTESMaximum uploaded CSV/XLSX lead file size in bytes (default 10 MiB):

  Maximum uploaded CSV/XLSX lead file size in bytes (default 10 MiB):

• AAVA_OUTBOUND_LEAD_IMPORT_MAX_ROWSMaximum data rows accepted from the first XLSX worksheet (default 10000, hard cap 100000):

  Maximum data rows accepted from the first XLSX worksheet (default 10000, hard cap 100000):

• AAVA_OUTBOUND_PBX_TYPEPBX type controls FreePBX-specific channel vars (AMPUSER/FROMEXTEN). freepbx (default) | generic Legacy "vicidial" remains readable for migration only. New VICIdial connections use Admin UI → Call Scheduling → VICIdial Remote Agents.

  PBX type controls FreePBX-specific channel vars (AMPUSER/FROMEXTEN). freepbx (default) | generic Legacy "vicidial" remains readable for migration only. New VICIdial connections use Admin UI → Call Scheduling → VICIdial Remote Agents.

• AAVA_SERVER_TIMEZONEOptional server timezone override for the Admin UI clock (IANA TZ string):

  Optional server timezone override for the Admin UI clock (IANA TZ string):

• AAVA_VM_UPLOAD_MAX_BYTESUpload size limit for voicemail/consent recordings (bytes). WAV is auto-converted to 8kHz μ-law:

  Upload size limit for voicemail/consent recordings (bytes). WAV is auto-converted to 8kHz μ-law:

• ADMIN_UI_CORS_ORIGINS═══════════════════════════════════════════════════════════════════════════ Admin UI Runtime (Optional) ═══════════════════════════════════════════════════════════════════════════ Comma-separated list of allowed origins for the Admin UI API CORS policy. Defaults to http://localhost:3003 and http://127.0.0.1:3003. Set to "*" only for advanced debugging; credentials will be disabled if "*".

  ═══════════════════════════════════════════════════════════════════════════ Admin UI Runtime (Optional) ═══════════════════════════════════════════════════════════════════════════ Comma-separated list of allowed origins for the Admin UI API CORS policy. Defaults to http://localhost:3003 and http://127.0.0.1:3003. Set to "*" only for advanced debugging; credentials will be disabled if "*".

• AI_ROLE=You are a concise and helpful voice assistant.
• ASTERISK_ARI_PASSWORD
• ASTERISK_ARI_PORT=8088ARI Port (default: 8088, some setups use custom ports like 20071)

  ARI Port (default: 8088, some setups use custom ports like 20071)

• ASTERISK_ARI_SCHEMEARI Scheme (default: http, use https for secure/WSS connections) - http: Uses ws:// for WebSocket (local/trusted networks) - https: Uses wss:// for WebSocket (remote/internet connections)

  ARI Scheme (default: http, use https for secure/WSS connections) - http: Uses ws:// for WebSocket (local/trusted networks) - https: Uses wss:// for WebSocket (remote/internet connections)

• ASTERISK_ARI_SSL_VERIFYSSL Certificate Verification (default: true) Set to false to skip SSL certificate verification for self-signed certs or when certificate doesn't match hostname/IP

  SSL Certificate Verification (default: true) Set to false to skip SSL certificate verification for self-signed certs or when certificate doesn't match hostname/IP

• ASTERISK_ARI_USERNAME=asteriskARI Credentials (SECRETS - keep in .env, never commit to git) Create in FreePBX: Settings → Asterisk REST Interface Users

  ARI Credentials (SECRETS - keep in .env, never commit to git) Create in FreePBX: Settings → Asterisk REST Interface Users

• ASTERISK_GID
• ASTERISK_HOST=127.0.0.1ASTERISK_HOST: How ai-engine connects to Asterisk ARI - Use IP address (127.0.0.1) for local Asterisk - Use hostname (asterisk.example.com) for remote Asterisk NOTE: When using hostname, you MUST set allowed_remote_hosts in ai-agent.yaml or via the Setup Wizard for RTP security

  ASTERISK_HOST: How ai-engine connects to Asterisk ARI - Use IP address (127.0.0.1) for local Asterisk - Use hostname (asterisk.example.com) for remote Asterisk NOTE: When using hostname, you MUST set allowed_remote_hosts in ai-agent.yaml or via the Setup Wizard for RTP security

• ASTERISK_MEDIA_WS_PASSWORDRequired only when audio_transport=websocket. This must match the password in Asterisk websocket_client.conf; configure the listener itself in YAML/UI.

  Required only when audio_transport=websocket. This must match the password in Asterisk websocket_client.conf; configure the listener itself in YAML/UI.

• ASTERISK_RECORDING_PATH=/var/spool/asterisk/monitorHost path to Asterisk call recordings (FreePBX default: /var/spool/asterisk/monitor) Mounted read-only into admin_ui container for playback in Call Details. Leave default unless your recordings are stored elsewhere.

  Host path to Asterisk call recordings (FreePBX default: /var/spool/asterisk/monitor) Mounted read-only into admin_ui container for playback in Call Details. Leave default unless your recordings are stored elsewhere.

• ASTERISK_UIDAsterisk User/Group IDs (for container permission alignment) Detect with: id -u asterisk && id -g asterisk Defaults to 995 (FreePBX standard) - adjust for your system

  Asterisk User/Group IDs (for container permission alignment) Detect with: id -u asterisk && id -g asterisk Defaults to 995 (FreePBX standard) - adjust for your system

• AUDIOSOCKET_ADVERTISE_HOST═══════════════════════════════════════════════════════════════════════════ OPTIONAL: NAT / Hybrid Network Configuration (Milestone 23) ═══════════════════════════════════════════════════════════════════════════ Use these when AI engine is behind NAT and Asterisk is remote. Set to the IP address that Asterisk can reach (VPN IP, public IP, LAN IP). For AudioSocket transport:

  ═══════════════════════════════════════════════════════════════════════════ OPTIONAL: NAT / Hybrid Network Configuration (Milestone 23) ═══════════════════════════════════════════════════════════════════════════ Use these when AI engine is behind NAT and Asterisk is remote. Set to the IP address that Asterisk can reach (VPN IP, public IP, LAN IP). For AudioSocket transport:

• AZURE_SPEECH_KEYMicrosoft Azure Speech Service (STT & TTS) Get your key at: https://portal.azure.com → Cognitive Services → Speech The region is NOT an env var — set it via the `region` field on each Azure provider in config/ai-agent.yaml (examples: eastus, westus2, westeurope).

  Microsoft Azure Speech Service (STT & TTS) Get your key at: https://portal.azure.com → Cognitive Services → Speech The region is NOT an env var — set it via the `region` field on each Azure provider in config/ai-agent.yaml (examples: eastus, westus2, westeurope).

• CALL_HISTORY_DB_PATH=/app/data/call_history.dbDatabase file path. Use an ABSOLUTE path that lands on the mounted ./data volume (container WORKDIR is /app). A relative path resolves against the current working directory, so a process started elsewhere (e.g. a `docker exec python -` from /) would read/write a different file off the persisted volume.

  Database file path. Use an ABSOLUTE path that lands on the mounted ./data volume (container WORKDIR is /app). A relative path resolves against the current working directory, so a process started elsewhere (e.g. a `docker exec python -` from /) would read/write a different file off the persisted volume.

• CALL_HISTORY_ENABLED=trueEnable/disable call history recording

  Enable/disable call history recording

• CALL_HISTORY_RETENTION_DAYS=0Retention period in days (0 = unlimited, keep forever)

  Retention period in days (0 = unlimited, keep forever)

• CALL_HISTORY_TOOL_REDACTION_MODE=strictPrivacy policy for persisted in-call tool diagnostics (requires ai_engine restart): strict (default) - redact credentials, caller PII/free text, and routing targets show_routing - keep destinations/extensions/queues/mailboxes; redact secrets and PII off - persist tool parameters and messages verbatim (trusted/private boxes only) This affects future tool executions only. Existin

  Privacy policy for persisted in-call tool diagnostics (requires ai_engine restart): strict (default) - redact credentials, caller PII/free text, and routing targets show_routing - keep destinations/extensions/queues/mailboxes; redact secrets and PII off - persist tool parameters and messages verbatim (trusted/private boxes only) This affects future tool executions only. Existin

• CAMB_API_KEY
• COMPOSE_PROJECT_NAME=asterisk-ai-voice-agent
• DEEPGRAM_API_KEY
• DIAG_ATTACK_MS
• DIAG_EGRESS_FORCE_MULAW
• DIAG_EGRESS_SWAP_MODE
• DIAG_ENABLE_TAPS=false
• DIAG_TAP_OUTPUT_DIR
• DIAG_TAP_POST_SECS
• DIAG_TAP_PRE_SECS
• DOCKER_GIDDocker socket group ID (for Admin UI container management) Admin UI runs as non-root (UID 1000) and needs docker group access. Default is 999 (common on most Linux systems). Check with: stat -c '%g' /var/run/docker.sock

  Docker socket group ID (for Admin UI container management) Admin UI runs as non-root (UID 1000) and needs docker group access. Default is 999 (common on most Linux systems). Check with: stat -c '%g' /var/run/docker.sock

• DOCKER_SOCK═══════════════════════════════════════════════════════════════════════════ OPTIONAL: Rootless Docker / Admin UI Docker Socket ═══════════════════════════════════════════════════════════════════════════ If your host uses rootless Docker, Admin UI must mount the rootless socket. Example:

  ═══════════════════════════════════════════════════════════════════════════ OPTIONAL: Rootless Docker / Admin UI Docker Socket ═══════════════════════════════════════════════════════════════════════════ If your host uses rootless Docker, Admin UI must mount the rootless socket. Example:

• ELEVENLABS_API_KEY
• EXTERNAL_MEDIA_ADVERTISE_HOSTFor ExternalMedia RTP transport:

  For ExternalMedia RTP transport:

• FISH_AUDIO_API_KEYFish Audio TTS (https://fish.audio) - streams PCM at the call sample rate

  Fish Audio TTS (https://fish.audio) - streams PCM at the call sample rate

• FISH_AUDIO_REFERENCE_IDRequired only for the legacy env-only path; Admin UI provider configuration stores the voice reference in YAML.

  Required only for the legacy env-only path; Admin UI provider configuration stores the voice reference in YAML.

• GOOGLE_API_KEY
• GOOGLE_APPLICATION_CREDENTIALSOption 2: Service Account (recommended for production) Create service account at: https://console.cloud.google.com/iam-admin/serviceaccounts Download JSON key and set the full path below

  Option 2: Service Account (recommended for production) Create service account at: https://console.cloud.google.com/iam-admin/serviceaccounts Download JSON key and set the full path below

• GOOGLE_CALENDAR_ID═══════════════════════════════════════════════════════════════════════════ OPTIONAL: GOOGLE CALENDAR tool ═══════════════════════════════════════════════════════════════════════════ GOOGLE_CALENDAR_CREDENTIALS=$GOOGLE_APPLICATION_CREDENTIALS # to use the same credentials

  ═══════════════════════════════════════════════════════════════════════════ OPTIONAL: GOOGLE CALENDAR tool ═══════════════════════════════════════════════════════════════════════════ GOOGLE_CALENDAR_CREDENTIALS=$GOOGLE_APPLICATION_CREDENTIALS # to use the same credentials

• GOOGLE_CLOUD_LOCATION
• GOOGLE_CLOUD_PROJECT─────────────────────────────────────────────────────────────────────────── OPTIONAL: Google Vertex AI Live API (AAVA-191) ─────────────────────────────────────────────────────────────────────────── Use Vertex AI instead of the Developer API for the google_live provider. Benefits: GA models with fixed function calling (no 1008 bug), enterprise SLA. Step 1: Enable Vertex AI API in your GCP project

  ─────────────────────────────────────────────────────────────────────────── OPTIONAL: Google Vertex AI Live API (AAVA-191) ─────────────────────────────────────────────────────────────────────────── Use Vertex AI instead of the Developer API for the google_live provider. Benefits: GA models with fixed function calling (no 1008 bug), enterprise SLA. Step 1: Enable Vertex AI API in your GCP project

• GPU_AVAILABLEGPU_AVAILABLE: Auto-detected by preflight.sh (do not set manually) - true: NVIDIA GPU detected on host - false: No GPU detected or nvidia-smi not found This is used by Admin UI wizard for tier detection without needing GPU passthrough

  GPU_AVAILABLE: Auto-detected by preflight.sh (do not set manually) - true: NVIDIA GPU detected on host - false: No GPU detected or nvidia-smi not found This is used by Admin UI wizard for tier detection without needing GPU passthrough

• GREETING=Hello, how can I help you today?
• HEALTH_API_TOKENSECURITY: Required for remote access to sensitive endpoints (/reload, /mcp/test/*) Generate with: openssl rand -hex 32

  SECURITY: Required for remote access to sensitive endpoints (/reload, /mcp/test/*) Generate with: openssl rand -hex 32

• HEALTH_BIND_PORTHEALTH_BIND_HOST=127.0.0.1 # Use 0.0.0.0 for remote monitoring

  HEALTH_BIND_HOST=127.0.0.1 # Use 0.0.0.0 for remote monitoring

• HEALTH_CHECK_AI_ENGINE_URLTier 3 / Best-effort hosts (Docker Desktop, Podman, unsupported distros): If the Admin UI shows AI Engine / Local AI Server as "unreachable" while containers are running, set explicit health probe URLs that are reachable from the admin-ui container:

  Tier 3 / Best-effort hosts (Docker Desktop, Podman, unsupported distros): If the Admin UI shows AI Engine / Local AI Server as "unreachable" while containers are running, set explicit health probe URLs that are reachable from the admin-ui container:

• HEALTH_CHECK_LOCAL_AI_URL
• HOST_PROJECT_ROOTHost project root path (auto-set by preflight.sh, required for Admin UI container management)

  Host project root path (auto-set by preflight.sh, required for Admin UI container management)

• JWT_SECRET═══════════════════════════════════════════════════════════════════════════ REQUIRED (Production): Admin UI Auth (SECRETS) ═══════════════════════════════════════════════════════════════════════════ JWT secret used by the Admin UI backend to sign auth tokens. IMPORTANT: This will be auto-generated by preflight.sh or install.sh. If running manually, generate with: openssl rand -hex 32 WARNING: If l

  ═══════════════════════════════════════════════════════════════════════════ REQUIRED (Production): Admin UI Auth (SECRETS) ═══════════════════════════════════════════════════════════════════════════ JWT secret used by the Admin UI backend to sign auth tokens. IMPORTANT: This will be auto-generated by preflight.sh or install.sh. If running manually, generate with: openssl rand -hex 32 WARNING: If l

• KOKORO_MODEL_PATHKokoro TTS Settings (only used when LOCAL_TTS_BACKEND=kokoro) ───────────────────────────────────────────────────────────── Model files are downloaded by the setup wizard to /app/models/tts/kokoro/ Voices: af_heart, af_bella, am_adam, am_michael (see VOICES.md)

  Kokoro TTS Settings (only used when LOCAL_TTS_BACKEND=kokoro) ───────────────────────────────────────────────────────────── Model files are downloaded by the setup wizard to /app/models/tts/kokoro/ Voices: af_heart, af_bella, am_adam, am_michael (see VOICES.md)

• KOKORO_VOICE
• KROKO_API_KEY
• KROKO_EMBEDDEDOption 3: Embedded mode (Kroko server runs inside local-ai-server container) Requires building with: docker build --build-arg INCLUDE_KROKO_EMBEDDED=true

  Option 3: Embedded mode (Kroko server runs inside local-ai-server container) Requires building with: docker build --build-arg INCLUDE_KROKO_EMBEDDED=true

• KROKO_LANGUAGE=en-USLanguage code for Kroko (see https://docs.kroko.ai/languages/)

  Language code for Kroko (see https://docs.kroko.ai/languages/)

• KROKO_MODEL_PATH
• KROKO_PORT
• KROKO_URLKroko ASR Settings (only used when LOCAL_STT_BACKEND=kroko) ───────────────────────────────────────────────────────────── Option 1: Hosted API (easiest - no model download required) Get API key at: https://app.kroko.ai/

  Kroko ASR Settings (only used when LOCAL_STT_BACKEND=kroko) ───────────────────────────────────────────────────────────── Option 1: Hosted API (easiest - no model download required) Get API key at: https://app.kroko.ai/

• LIVE_STATUS_ADMIN_URLOPTIONAL: Admin UI live-status push from ai_engine/local_ai_server. Uses LIVE_STATUS_PUSH_TOKEN when set, otherwise falls back to HEALTH_API_TOKEN. In the default host-network compose setup, the Admin UI API is reachable on 127.0.0.1:3003.

  OPTIONAL: Admin UI live-status push from ai_engine/local_ai_server. Uses LIVE_STATUS_PUSH_TOKEN when set, otherwise falls back to HEALTH_API_TOKEN. In the default host-network compose setup, the Admin UI API is reachable on 127.0.0.1:3003.

• LIVE_STATUS_PUSH_INTERVAL_SECONDS
• LIVE_STATUS_PUSH_TIMEOUT_SECONDS
• LIVE_STATUS_PUSH_TOKEN
• LLAMA_CUDA_ARCHITECTURESOptional build optimization for llama.cpp CUDA source builds. Leave blank for a portable image, or set a semicolon-separated CMake architecture list. The Tesla V100/V100S compute capability is 70. Rebuild local_ai_server after a change; an incorrect value can make the image unusable on the target GPU.

  Optional build optimization for llama.cpp CUDA source builds. Leave blank for a portable image, or set a semicolon-separated CMake architecture list. The Tesla V100/V100S compute capability is 70. Rebuild local_ai_server after a change; an incorrect value can make the image unusable on the target GPU.

• LOCAL_DEBUG=0Verbose audio flow debugging (separate from log level) Set to 1 to enable detailed audio processing logs: - "FEEDING VOSK" messages with byte counts - RMS/energy calculations for each audio chunk - Audio buffer states and routing decisions WARNING: Creates very high log volume - only enable for troubleshooting!

  Verbose audio flow debugging (separate from log level) Set to 1 to enable detailed audio processing logs: - "FEEDING VOSK" messages with byte counts - RMS/energy calculations for each audio chunk - Audio buffer states and routing decisions WARNING: Creates very high log volume - only enable for troubleshooting!

• LOCAL_ENABLE_FILLER_AUDIOFiller audio: play a brief phrase before LLM starts (local full mode only)

  Filler audio: play a brief phrase before LLM starts (local full mode only)

• LOCAL_LLM_CHAT_FORMAT
• LOCAL_LLM_GPU_LAYERSGPU layer offloading (uncomment and set to enable): 0 = CPU only (default when commented out, no GPU required) -1 = Auto-detect (use GPU if CUDA available) — RECOMMENDED for GPU users N = Offload N layers to GPU (e.g., 35) Tip: Run preflight.sh first to detect GPU, then set -1 for auto.

  GPU layer offloading (uncomment and set to enable): 0 = CPU only (default when commented out, no GPU required) -1 = Auto-detect (use GPU if CUDA available) — RECOMMENDED for GPU users N = Offload N layers to GPU (e.g., 35) Tip: Run preflight.sh first to detect GPU, then set -1 for auto.

• LOCAL_LLM_MODEL_PATHCPU recommended: Qwen 2.5-1.5B (~15-30 tok/s). Phi-3 is too slow on CPU (~0.8 tok/s).

  CPU recommended: Qwen 2.5-1.5B (~15-30 tok/s). Phi-3 is too slow on CPU (~0.8 tok/s).

• LOCAL_LLM_STREAMING_TTS_OVERLAPLLM streaming: synthesize TTS per-sentence instead of waiting for full response

  LLM streaming: synthesize TTS per-sentence instead of waiting for full response

• LOCAL_LOG_LEVEL=INFOLog level for the local-ai-server process Values: DEBUG | INFO | WARNING | ERROR | CRITICAL - DEBUG: All logs including WebSocket messages, audio routing, model loading - INFO: Normal operation logs (recommended for production) - WARNING: Only warnings and errors - ERROR: Only errors

  Log level for the local-ai-server process Values: DEBUG | INFO | WARNING | ERROR | CRITICAL - DEBUG: All logs including WebSocket messages, audio routing, model loading - INFO: Normal operation logs (recommended for production) - WARNING: Only warnings and errors - ERROR: Only errors

• LOCAL_STT_BACKEND=voskLocal AI Server - STT Backend Selection ───────────────────────────────────────────────────────────── Choose STT backend implementation. Default is vosk.

  Local AI Server - STT Backend Selection ───────────────────────────────────────────────────────────── Choose STT backend implementation. Default is vosk.

• LOCAL_STT_MODEL_PATH
• LOCAL_TOOL_CALL_POLICY=autoLocal provider tool-call strategy: - auto: follow local-ai-server LLM capability probe (recommended) - strict: full structured tool prompting - compatible: compact prompting + parser recovery - off: disable local tool prompt injection

  Local provider tool-call strategy: - auto: follow local-ai-server LLM capability probe (recommended) - strict: full structured tool prompting - compatible: compact prompting + parser recovery - off: disable local tool prompt injection

• LOCAL_TOOL_GATEWAY_ENABLED=trueStructured tool gateway for full-local provider mode only (recommended). Modular local STT-only / TTS-only adapters are unaffected.

  Structured tool gateway for full-local provider mode only (recommended). Modular local STT-only / TTS-only adapters are unaffected.

• LOCAL_TTS_BACKEND=piper
• LOCAL_TTS_MODEL_PATH
• LOCAL_TTS_PHRASE_CACHE_ENABLEDTTS phrase cache: cache short repeated phrases to skip re-synthesis

  TTS phrase cache: cache short repeated phrases to skip re-synthesis

• LOCAL_WS_AUTH_TOKENOptional auth token for local-ai-server WebSocket. If set here, also set providers.local*.auth_token to ${LOCAL_WS_AUTH_TOKEN} in ai-agent.yaml.

  Optional auth token for local-ai-server WebSocket. If set here, also set providers.local*.auth_token to ${LOCAL_WS_AUTH_TOKEN} in ai-agent.yaml.

• LOCAL_WS_CHUNK_MS=320
• LOCAL_WS_CONNECT_TIMEOUT=2.0
• LOCAL_WS_HOSTNotes: - When either value is set, it is authoritative: the Admin UI probes only that URL. - Default deployment uses host networking (docker-compose.yml uses network_mode: host), so 127.0.0.1 is the correct way for ai-engine to reach local-ai-server. - If you run containers on a user-defined bridge network (no host networking), use ws://local_ai_server:8765 instead. If you want Local AI Server to

  Notes: - When either value is set, it is authoritative: the Admin UI probes only that URL. - Default deployment uses host networking (docker-compose.yml uses network_mode: host), so 127.0.0.1 is the correct way for ai-engine to reach local-ai-server. - If you run containers on a user-defined bridge network (no host networking), use ws://local_ai_server:8765 instead. If you want Local AI Server to

• LOCAL_WS_PORT=8765
• LOCAL_WS_RESPONSE_TIMEOUT=5.0
• LOCAL_WS_URL=ws://127.0.0.1:8765Default (recommended): host networking → connect via 127.0.0.1. If running without host networking (bridge), set to ws://local_ai_server:8765.

  Default (recommended): host networking → connect via 127.0.0.1. If running without host networking (bridge), set to ws://local_ai_server:8765.

• LOG_COLOR=1
• LOG_FILE_PATH
• LOG_FORMAT=console
• LOG_LEVEL=info
• LOG_SHOW_TRACEBACKS=auto
• LOG_TO_FILEOptional: File logging (Docker logs usually sufficient)

  Optional: File logging (Docker logs usually sufficient)

• MINIMAX_API_KEYMiniMax LLM (OpenAI-compatible API) Get your API key at: https://platform.minimax.io/ Docs: https://platform.minimax.io/docs/api-reference/text-openai-api Models: MiniMax-M3 (default), MiniMax-M2.7, MiniMax-M2.7-highspeed

  MiniMax LLM (OpenAI-compatible API) Get your API key at: https://platform.minimax.io/ Docs: https://platform.minimax.io/docs/api-reference/text-openai-api Models: MiniMax-M3 (default), MiniMax-M2.7, MiniMax-M2.7-highspeed

• OPENAI_API_KEYAPI keys are set by the Setup Wizard or manually Leave empty until you configure them - providers will show "Not Ready" until set

  API keys are set by the Setup Wizard or manually Leave empty until you configure them - providers will show "Not Ready" until set

• RESEND_API_KEY
• SHERPA_MODEL_PATHSherpa-onnx STT Settings (only used when LOCAL_STT_BACKEND=sherpa) ───────────────────────────────────────────────────────────── Local streaming ASR using sherpa-onnx (no server needed)

  Sherpa-onnx STT Settings (only used when LOCAL_STT_BACKEND=sherpa) ───────────────────────────────────────────────────────────── Local streaming ASR using sherpa-onnx (no server needed)

• SHERPA_MODEL_TYPE
• SILERO_MODEL_PATHSilero TTS Settings (only used when LOCAL_TTS_BACKEND=silero) ───────────────────────────────────────────────────────────── Multi-language TTS with 8kHz native telephony output (no resampling) Requires: INCLUDE_SILERO=true below AND rebuild (docker compose build --build-arg INCLUDE_SILERO=true) INCLUDE_SILERO=false # Set to true and rebuild to enable Silero TTS SILERO_SPEAKER=xenia

  Silero TTS Settings (only used when LOCAL_TTS_BACKEND=silero) ───────────────────────────────────────────────────────────── Multi-language TTS with 8kHz native telephony output (no resampling) Requires: INCLUDE_SILERO=true below AND rebuild (docker compose build --build-arg INCLUDE_SILERO=true) INCLUDE_SILERO=false # Set to true and rebuild to enable Silero TTS SILERO_SPEAKER=xenia

• SMTP_HOSTSMTP (optional): Use a local SMTP server for transcript/summary emails. If SMTP_HOST is set, email tools can use provider=auto or provider=smtp.

  SMTP (optional): Use a local SMTP server for transcript/summary emails. If SMTP_HOST is set, email tools can use provider=auto or provider=smtp.

• SMTP_PASSWORD
• SMTP_TIMEOUT_SECONDSSMTP_TLS_MODE=starttls # starttls | smtps | none SMTP_TLS_VERIFY=true # true | false

  SMTP_TLS_MODE=starttls # starttls | smtps | none SMTP_TLS_VERIFY=true # true | false

• SMTP_USERNAMESMTP_PORT=587 # 587=STARTTLS, 465=SMTPS (implicit TLS)

  SMTP_PORT=587 # 587=STARTTLS, 465=SMTPS (implicit TLS)

• STREAMING_LOG_LEVEL=info
• TELNYX_API_KEYTelnyx AI Inference (OpenAI-compatible API for LLM) Get your API key at: https://portal.telnyx.com/ Docs: https://developers.telnyx.com/docs/inference/overview Use with pipeline config: set llm base_url to https://api.telnyx.com/v2/ai

  Telnyx AI Inference (OpenAI-compatible API for LLM) Get your API key at: https://portal.telnyx.com/ Docs: https://developers.telnyx.com/docs/inference/overview Use with pipeline config: set llm base_url to https://api.telnyx.com/v2/ai

• UVICORN_HOSTAdmin UI bind controls (advanced). Default is remote-accessible for first-run usability. For production hardening, consider binding to localhost and placing a reverse proxy/VPN in front.

  Admin UI bind controls (advanced). Default is remote-accessible for first-run usability. For production hardening, consider binding to localhost and placing a reverse proxy/VPN in front.

• UVICORN_PORT
• VICIDIAL_API_PASS
• VICIDIAL_API_USERVICIdial Remote Agent API credentials. The mapping stores these variable names, never values. Set both before using Call Scheduling → VICIdial Remote Agents, then recreate ai_engine and admin_ui so both services receive the new environment.

  VICIdial Remote Agent API credentials. The mapping stores these variable names, never values. Set both before using Call Scheduling → VICIdial Remote Agents, then recreate ai_engine and admin_ui so both services receive the new environment.

• VICIDIAL_DB_PATHOptional shared SQLite path for VICIdial connections, mappings, and readiness evidence.

  Optional shared SQLite path for VICIdial connections, mappings, and readiness evidence.

• XAI_API_KEYxAI Grok Voice Agent (full-agent realtime provider, NEW in v6.5.2) Get an API key at: https://x.ai/api (console) Docs: https://docs.x.ai/developers/model-capabilities/audio/voice-agent Single-instance shortcut only — for ANY multi-instance deployment, use the per-instance api_key_file path /app/project/secrets/providers/<provider_key>/api-key instead. (XAI_API_KEY is only consulted when no per-in

  xAI Grok Voice Agent (full-agent realtime provider, NEW in v6.5.2) Get an API key at: https://x.ai/api (console) Docs: https://docs.x.ai/developers/model-capabilities/audio/voice-agent Single-instance shortcut only — for ANY multi-instance deployment, use the per-instance api_key_file path /app/project/secrets/providers/<provider_key>/api-key instead. (XAI_API_KEY is only consulted when no per-in