{"slug": "show-hn-self-hosted-voice-ai-agent-for-asterisk-freepbx", "title": "Show HN: Self-hosted voice AI agent for Asterisk/FreePBX", "summary": "A developer released a self-hosted open-source AI voice agent for Asterisk/FreePBX, featuring a modular pipeline architecture that supports multiple STT, LLM, and TTS providers with six production-ready baselines. The project includes an admin UI that can be set up in two minutes and provides tools for configuring AI-powered actions and dialplan integration.", "body_md": "The most powerful, flexible open-source AI voice agent for Asterisk/FreePBX. Featuring a **modular pipeline architecture** that lets you mix and match STT, LLM, and TTS providers, plus **6 production-ready golden baselines** validated for enterprise deployment.\n\n[🚀 Quick Start](#-quick-start)[🎉 What's New](#-whats-new)[🌟 Why Asterisk AI Voice Agent?](#-why-asterisk-ai-voice-agent)[✨ Features](#-features)[🎥 Demo](#-demo)[🛠️ AI-Powered Actions](#-ai-powered-actions)[🩺 Agent CLI Tools](#-agent-cli-tools)[⚙️ Configuration](#-configuration)[🏗️ Project Architecture](#-project-architecture)[📊 Requirements](#-requirements)[🗺️ Documentation](#-documentation)[🤝 Contributing](#-contributing)[💬 Community](#-community)[📝 License](#-license)\n\nGet the **Admin UI running in 2 minutes**.\n\nFor a complete **first successful call** walkthrough (dialplan + transport selection + verification), see:\n\n```\n# Clone repository\ngit clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git\ncd AVA-AI-Voice-Agent-for-Asterisk\n\n# Run preflight with auto-fix (creates .env, generates JWT_SECRET)\nsudo ./preflight.sh --apply-fixes\n```\n\nImportant:Preflight creates your`.env`\n\nfile and generates a secure`JWT_SECRET`\n\n. Always run this first!\n\n```\n# Start the Admin UI container\ndocker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui\n```\n\nOpen in your browser:\n\n**Local:**`http://localhost:3003`\n\n**Remote server:**`http://<server-ip>:3003`\n\n**Default Login:** On first start, a one-time admin password is printed to the container logs. Retrieve it with:\n\n```\ndocker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password\n```\n\nYou must change it at first login. Restrict port 3003 via firewall, VPN, or reverse proxy for production use.\n\nFollow the **Setup Wizard** to configure your providers and make a test call.\n\n⚠️ Security:The Admin UI is accessible on the network. Restrict port 3003 via firewall, VPN, or reverse proxy for production use.\n\nGPU users:If you have an NVIDIA GPU for local AI inference, seefor the GPU compose overlay ([docs/LOCAL_ONLY_SETUP.md]`docker-compose.gpu.yml`\n\n) before building.\n\n```\n# Start ai_engine (required for health checks)\ndocker compose -p asterisk-ai-voice-agent up -d --build ai_engine\n\n# Check ai_engine health\ncurl http://localhost:15000/health\n# Expected: {\"status\":\"healthy\"} (\"degraded\" is also possible if a subsystem is unhealthy)\n\n# View logs for any errors\ndocker compose -p asterisk-ai-voice-agent logs ai_engine | tail -20\n```\n\nThe wizard will generate the necessary dialplan configuration for your Asterisk server.\n\nTransport selection is configuration-dependent (not strictly “pipelines vs full agents”). Use the validated matrix in:\n\nFor users who prefer the command line or need headless setup.\n\n```\n./install.sh\nagent setup\n```\n\nNote: Legacy commands\n\n`agent init`\n\n,`agent quickstart`\n\n,`agent doctor`\n\n,`agent troubleshoot`\n\n, and`agent demo`\n\nremain as hidden compatibility aliases. New workflows should use the visible commands documented in[.]`docs/CLI_TOOLS_GUIDE.md`\n\n```\n# Configure environment\ncp .env.example .env\n# Edit .env with your API keys\n\n# Start services\ndocker compose -p asterisk-ai-voice-agent up -d\n```\n\nAdd this to your FreePBX (`extensions_custom.conf`\n\n):\n\n``` js\n[from-ai-agent]\nexten => s,1,NoOp(Asterisk AI Voice Agent)\n ; AI_AGENT selects an operator-managed agent by slug.\n same => n,Set(AI_AGENT=sales-agent)\n ; Optional: override that agent's configured provider/pipeline for this call.\n ; same => n,Set(AI_PROVIDER=google_live)\n same => n,Stasis(asterisk-ai-voice-agent)\n same => n,Hangup()\n```\n\nNotes:\n\n- Use\n`AI_AGENT`\n\nto select an operator-managed agent. Its configured target is authoritative unless`AI_PROVIDER`\n\nis intentionally set as a per-call override. - Generate a current snippet with\n`agent dialplan --agent <slug>`\n\n. - See\n`docs/FreePBX-Integration-Guide.md`\n\nfor channel variable precedence and examples.\n\n**Health check:**\n\n```\nagent check\n```\n\n**View logs:**\n\n```\ndocker compose -p asterisk-ai-voice-agent logs -f ai_engine\n```\n\n**v7.3.2 — stabilization release 🛡️**\n\nv7.3.2 is a stabilization-only patch release built from the supervised AudioSocket and ExternalMedia validation cycle.\n\n**No new providers**— scope is limited to reliability, deployment safety, documentation, and contributor-facing CI.** Grok ExternalMedia repaired**— clean barge-in, cancelled-output quarantine, named-instance runtime inheritance, complete replacement turns, and exact inactivity announcements through xAI`force_message`\n\n.**AudioSocket and modular pipelines hardened**— terminal playback, pipeline producer ownership, talk-detect echo, and inactivity-grace regressions are covered by focused tests and supervised calls.**Updater and provider-failure recovery hardened**— safer ownership, rollback/stash handling, readiness validation, and an opt-in dialplan redirect.** PR quality gates expanded**— Admin backend/frontend checks and CLI cross-compilation now run before merge.\n\nRelease evidence and remaining gates are tracked in the\n[v7.3.2 validation matrix](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/baselines/golden/v7.3.2-validation-matrix.md).\n\n**v7.3.1 — Silence watchdog & safe call endings ☎️**\n\n**AVA now protects silent calls and finishes every terminal message before disconnecting.**\n\n**30-second inbound inactivity protection by default**— AVA asks “Are you still there?”, waits 15 seconds for a reply, then speaks a configurable final warning and ends the call. Outbound agents remain opt-in.**The agent keeps its configured voice**— check-ins and final warnings are synthesized by the active Google Live, OpenAI Realtime, Grok, Deepgram, ElevenLabs, local full-agent, or pipeline voice.**Transport-safe hangup**— watchdog and`hangup_call`\n\nfarewells drain AudioSocket or ExternalMedia/RTP streaming buffers and ARI file playback before ARI disconnects the caller. Fixed sleeps no longer clip long final sentences.**Deepgram and ElevenLabs lifecycle fixes**— Deepgram control frames no longer split greetings, and ElevenLabs response-completion plus hosted-silence handling keeps AVA's watchdog authoritative.**Global and per-agent controls**— configure defaults under** Advanced Settings → Voice Activity Detection → Caller Inactivity**, then optionally override them per agent. Call History labels watchdog endings as** No input timeout**.\n\nSee [Caller inactivity configuration](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Configuration-Reference.md#caller-inactivity-no_input), [ElevenLabs setup](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Provider-ElevenLabs-Setup.md#ava-caller-inactivity-compatibility-v731), and the full [v7.3.1 changelog](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CHANGELOG.md#731---2026-07-09).\n\n**v7.3.0 — Per-agent voices 🎙️**\n\n**Voice now belongs to agents.** Configure one provider, create multiple agents that share it — each with its own voice.\n\n**Provider-aware voice picker** in the Agent form: a dropdown of OpenAI's 10 GA voices, suggestions + custom clone IDs for Grok, Google Live's 30 prebuilt voices, Deepgram's Aura models — the control adapts to the agent's selected AI Engine.**Safe by default**— the provider-level voice becomes the*default voice*; agents without one behave exactly as before. Unrecognized values (OpenAI/Google/Deepgram catalogs are validated) log a warning and fall back — a bad voice value never fails a call.**Observable**— every call logs the resolved voice and its source, and Call History shows \"Voice: marin (from agent)\" per call.- Agent voice changes apply instantly — no engine restart.\n\nThanks @foytech for seeding this feature (#497). Full guide: [docs/VOICE_SELECTION.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/VOICE_SELECTION.md).\n\n**v7.2.0 — Live-status dashboard 📡**\n\nReal-time system status for the Admin UI — pushed, not polled.\n\n**Live-status hub**— a single`/api/live-status`\n\nsnapshot endpoint plus an SSE stream (`/api/live-status/stream`\n\n) aggregates AI Engine health, Local AI connectivity, active sessions, audio directories, platform checks, and Asterisk ARI into one normalized status feed.**Push-first**—`ai_engine`\n\nand`local_ai_server`\n\npush their own readiness to the Admin UI (`POST /api/live-status/publish`\n\n, authenticated with`LIVE_STATUS_PUSH_TOKEN`\n\n), so the dashboard converges in sub-second time after a restart instead of waiting on staggered polls. Legacy`/api/system/*`\n\nprobes remain as fallback/enrichment.**Configurable**—`LIVE_STATUS_POLL_INTERVAL_SECONDS`\n\n(default 30 s, min 2 s) and`LIVE_STATUS_INITIAL_PROBE_TIMEOUT_SECONDS`\n\n(default 2 s), read live from`.env`\n\n.\n\nFull notes in [CHANGELOG.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CHANGELOG.md).\n\n**v7.1.1 — Dashboard reliability & Admin UI polish 🛠️**\n\nA focused quality release across the Admin UI — no call-path changes.\n\n**Dashboard reliability**— the Asterisk status pill no longer flaps on a transient ARI blip: it reads the engine's authoritative, reconnect-supervised ARI state and applies hysteresis. The system endpoints the Dashboard polls every 5s no longer block the admin event loop, the heaviest is TTL-cached, polling backs off on errors, failed polls surface in the error banner, and a single bad poll no longer flashes cards to \"Loading…\".**No more \"Loading configuration…\" flash**— ~11 config pages now seed from a shared stale-while-revalidate cache of the config document, so revisiting a settings page is instant.**Accessibility (WCAG AA)**— form labels programmatically associated with inputs, a focus-trapping modal, a navigation landmark + \"skip to content\" link, accessible names on icon-only buttons, non-colour status cues on the topology, a visible dark-mode toggle on-state, and light-mode contrast fixes. Debug`console.log`\n\ns (including one that leaked the auth token to the browser console) were removed.**Prompt editor**— configured tool names are colour-coded by their in-call status (enabled / global / not-enabled) as you type.** Fix (#436)**— a canonical`google_live: { type: full }`\n\nprovider can be edited and saved again.\n\nFull notes in [CHANGELOG.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CHANGELOG.md).\n\n**v7.0.0 — the Agents release 🎯**\n\nThe biggest release yet: **manage your AI agents from the Admin UI, not a config file.**\n\n**🤖 Agents tab**— create, edit, and manage agents in the UI. Start from a template (receptionist, after-hours, appointment booker, and more), set the prompt and provider, and copy a ready-to-paste dialplan snippet. (Voice is configured on the provider, not per agent.)**📊 Multi-agent dashboard**— live KPIs (active agents, active calls, calls routed, transfers), per-agent stats, and routing breakdowns at a glance.**☎️ New**— route a call to an agent by name. Your existing`AI_AGENT`\n\ndialplan variable`AI_CONTEXT`\n\ndialplans keep working unchanged.**🔄 Automatic migration**— your existing contexts move into a local agents database on first start. Nothing to do, and rollback is one command.**🔒 Security hardening**— no more`admin`\n\n/`admin`\n\n: a one-time admin password is generated and must be changed at first login. Config exports no longer bundle your`.env`\n\nby default.\n\n[Upgrade Notes](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CHANGELOG.md) before upgrading from 6.x.\n\n**v6.5.4 (2026-05-25) — OpenAI Realtime GA cleanup across every code path**\n\nFollow-up to the v6.5.3 hotfix. v6.5.3 only flipped `config/ai-agent.yaml`\n\n; v6.5.4 brings the rest of the codebase in line:\n\n**Pydantic defaults** in`src/config.py`\n\nnow default to`api_version: ga`\n\n+`model: gpt-realtime`\n\n(so fresh wizard installs are correct).**Admin UI \"Add Provider\" template** for OpenAI Realtime no longer seeds the sunset preview model.**Model dropdown** removes the 5 sunset preview options and adds 3 new GA models —`gpt-realtime-1.5`\n\n(best audio-in/audio-out quality),`gpt-realtime-2`\n\n(reasoning voice model, GPT-5-class), and`gpt-realtime-mini`\n\n(cost-optimized) — alongside the existing`gpt-realtime`\n\n.**Legacy preview values in operator YAML** now render in a \"Custom (legacy — will not connect)\" optgroup with a yellow warning banner above the form so the broken state is visible without silently swapping the operator's config.**Engine** emits a one-shot warning when`api_version: beta`\n\nis detected in config (exactly once per provider lifetime, not per reconnect attempt).**Docs**: full rewrite of`docs/Provider-OpenAI-Setup.md`\n\nmodel section + fix to`docs/TROUBLESHOOTING_GUIDE.md`\n\n.\n\n**v6.5.3 hotfix (2026-05-25) — OpenAI Realtime restored**\n\nOpenAI sunset the Realtime **Beta** API on 2026-05-12 and removed the `gpt-4o-realtime-preview-2024-12-17`\n\nmodel on 2026-05-07. Shipped `config/ai-agent.yaml`\n\nstill pinned `api_version: beta`\n\n+ that preview model, so every operator using OpenAI Realtime hit `error.code: beta_api_shape_disabled`\n\nand the WebSocket closed immediately. **Two-line config flip — no code change required**. The provider's GA wire-protocol path has shipped since v6.0.0; v6.5.3 just makes it the default everyone gets:\n\n`api_version: ga`\n\n(was`beta`\n\n)`model: gpt-realtime`\n\n(was`gpt-4o-realtime-preview-2024-12-17`\n\n)\n\nIf you have an `ai-agent.local.yaml`\n\nthat explicitly pins `api_version: beta`\n\n, remove the override or change it to `ga`\n\n. Refs: [OpenAI deprecations](https://developers.openai.com/api/docs/deprecations), [gpt-realtime](https://platform.openai.com/docs/models/gpt-realtime).\n\n**v6.5.2 (2026-05-24) — xAI Grok + multi-instance full-agent providers**\n\n- Fifth full-agent realtime provider — structurally parallel to OpenAI Realtime and Google Live, built on a multi-instance foundation from day one\n- μ-law @ 8 kHz caller input with no input resampling; observed xAI output is PCM16 @ 24 kHz and AAVA converts it to the configured Asterisk transport format\n- Five named voices (\n`eve`\n\n,`ara`\n\n,`rex`\n\n,`sal`\n\n,`leo`\n\n) plus custom voice ID free-text for cloned voices - Custom function-tools identical to OpenAI Realtime; xAI-native tools (\n`web_search`\n\n,`x_search`\n\n,`file_search`\n\n,`mcp`\n\n) accepted via YAML`extra_tools`\n\nescape hatch - Conservative long-session warning at 28 minutes for compatibility with older xAI limits; xAI's current Voice Agent model page lists a 120-minute maximum session\n- Setup guide:\n[docs/Provider-Grok-Setup.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Provider-Grok-Setup.md)\n\n- Run multiple instances of the same full-agent provider type with isolated credentials (e.g.\n`acme_google_live`\n\n+`globex_google_live`\n\nboth using`type: google_live`\n\n) - Per-instance credential files at\n`/app/project/secrets/providers/<provider_key>/{api-key,agent-id,vertex-json}`\n\n— the new per-provider Vertex upload path does NOT mutate`.env`\n\n- Route via\n`AI_PROVIDER`\n\nchannel var,`contexts.<name>.provider:`\n\nYAML, or DID-based dispatch with Asterisk`Gosub`\n\n- Setup guide:\n[docs/Multi-Instance-Full-Agent-Providers.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Multi-Instance-Full-Agent-Providers.md) **Breaking for multi-instance setups:** short aliases`AI_PROVIDER=openai`\n\n,`AI_PROVIDER=google`\n\n,`provider: deepgram_agent`\n\nnow fail validation — use exact provider instance keys instead. Single-instance setups using the canonical block names are unaffected.\n\n- Uniform per-instance credentials paste-style uploader across all full-agent provider forms (Grok, OpenAI Realtime, Deepgram, Google Live, ElevenLabs Agent)\n- EnvPage adds a new \"Per-Instance Provider Credentials\" status section so operators can audit credential file presence without SSH\n- Dashboard System Topology rebuilt: tri-state per-component health with 2-strike debounce (transient probe blips no longer flip dots red), responsive provider grid, multi-instance sub-rows grouped by provider type, Asterisk + AI Engine cards stretched to match Providers height\n- Backend probe timeouts bumped (ai_engine 1.5s → 5s; local_ai_server 2.5s → 5s) to stop legitimate localhost probes timing out under load\n- ~260 inline help tooltips backfilled across provider forms, Setup Wizard, and System pages — new\n`HelpTooltip`\n\nis viewport-aware (flips placement to keep popovers visible in scrolled modals)\n\n- Browser playback for compact\n`.ulaw`\n\nrecordings (Asterisk's 8 kHz μ-law output, ~10× smaller than PCM WAV) via server-side`audioop.ulaw2lin`\n\nWAV wrapping — no transcode dependency - Uppercase\n`.WAV`\n\n, compressed WAV, and`.gsm`\n\nrecordings transcode via`sox`\n\n;`AAVA_RECORDING_TRANSCODE_TIMEOUT_SEC`\n\nenv var (default 120s) governs the timeout\n\n- 💻 CPU-demo profile end-to-end — Faster-Whisper\n`tiny.en`\n\n+ Piper + Qwen 0.5B wired through the Admin UI; runtime Device/Compute selectors with CPU/`float16`\n\ngating; Filler Audio and LLM/TTS Overlap runtime toggles - 🛡️ Local provider hot-path hardening —\n`send_audio()`\n\nno longer blocks on per-frame reconnect;`asyncio.Lock`\n\nserializes`_reconnect()`\n\nagainst`_send_loop`\n\n's on-`ConnectionClosed`\n\npath - 🎨 Faster-Whisper verify path tolerates the runtime CUDA→CPU fallback so working CPU/int8 configurations no longer get rolled back as \"verification failed\"\n\n- 🔧 Local LLM tool-gated response (#368) — new WS protocol message types\n`tool_context`\n\n/`tool_result`\n\nv2; per-WebSocket fail-closed sync prevents cross-call ACL/policy/prompt leakage on reused connections - ☁️ Gemini 3.1 Flash Live verified compatible (no engine changes); Vertex AI mode is the production answer for #351 barge-in\n- 🎤 Deepgram Flux v2 + nova-3 default flip; Admin UI surfaces \"Flux Turn-Detection Tuning\" panel for flux-* models\n- 🩺 Admin UI HTTP-tool-test guard now reads\n`.env`\n\nfirst so Environment-page edits to`AAVA_HTTP_TOOL_TEST_*`\n\ntake effect without a container restart (#370)\n\nFor older releases, expand **Previous Versions** below. Full release notes in [CHANGELOG.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CHANGELOG.md).\n\n**Previous Versions**\n\n- 🗓️ Microsoft Calendar — Outlook / Microsoft 365 integration via device-code OAuth, Graph free/busy, per-context account binding, Tools UI Connect/Verify/Disconnect\n- 📅 Google Calendar — multi-account / per-context binding (#338), JSON upload + auto-discover, Domain-Wide Delegation, native free/busy mode\n- 🎯 Reschedule reliability — server-side\n`event_id`\n\nresolution + 400/404 fallback eliminates LLM-id-hallucination duplicate bookings - 🔧 Date/time prompt placeholders (\n`{today}`\n\n,`{current_date}`\n\n, etc.) so models stop reasoning with stale years - OpenAI Realtime duplicate-events fix (per-\n`response_id`\n\nasync-event gating); per-context`tool_overrides`\n\nnow actually take effect on OpenAI Realtime / Deepgram / Google Live; Google Live 30-voice catalog (#349)\n\n- ⚡ Streaming LLM→TTS overlap — sentence-boundary token streaming, sub-2s perceived latency on pipelines\n- Pipeline filler audio (instant \"One moment please\" acknowledgment) configurable via Admin UI\n- Qwen 2.5-1.5B Instruct recommended for CPU; ~15-30 tok/s vs Phi-3's ~0.8 tok/s\n- Direct PCM→µ-law conversion in all 5 TTS backends (10-50ms saved per response)\n- Preflight hardening — Buildx detection, RAM/disk/network checks, GPU install gated behind\n`--apply-fixes`\n\n- 📞 Attended transfer with three screening modes:\n`basic_tts`\n\n,`ai_briefing`\n\n,`caller_recording`\n\n- ExternalMedia RTP streaming delivery; provider-agnostic transfer-target tool guidance\n- 🗣️ Russian speech backends: Sherpa Offline STT (VAD-gated), T-one STT, Silero TTS (multi-language)\n- 🎧 Admin UI: fullscreen dashboard panels, per-message conversation timestamps, JSONPath\n`[*]`\n\nHTTP-tool wildcards\n\n- Microsoft Azure Speech Service STT & TTS pipeline adapters (REST batch, WebSocket streaming, SSML)\n- MiniMax LLM M2.7 via OpenAI-compatible API with tool-calling\n- Call Recording Playback in Admin UI Call Details modal\n- Azure SSRF prevention, PII logging discipline, input validation hardening\n\n- Backend enable/rebuild flow, model lifecycle UX, GPU ergonomics, CPU-first onboarding\n- Structured local tool gateway, hangup guardrails, tool-call parsing robustness\n`agent check --local`\n\n/`--remote`\n\nCLI verification\n\n- Operator config overrides (\n`ai-agent.local.yaml`\n\n), live agent transfer tool - Experimental ViciDial community-tested configuration notes, Asterisk config discovery in Admin UI\n- OpenAI Realtime GA API, Email system overhaul, NAT/GPU support\n\n- Pre-call HTTP lookups, in-call HTTP tools, and post-call webhooks (Milestone 24)\n- Deepgram Voice Agent language configuration\n- ExternalMedia RTP greeting cutoff fix\n\n**🌍 Pre-flight Script**: System compatibility checker with auto-fix mode.**🔧 Admin UI Fixes**: Models page, providers page, dashboard improvements.**🛠️ Developer Experience**: Code splitting, ESLint + Prettier.\n\n**🎤 New STT Backends**: Kroko ASR, Sherpa-ONNX.**🔊 Kokoro TTS**: High-quality neural TTS.**🔄 Model Management**: Dynamic backend switching from Dashboard.**📚 Documentation**: LOCAL_ONLY_SETUP.md guide.\n\n**🖥️ Admin UI**: Modern web interface ([http://localhost:3003](http://localhost:3003)).**🎙️ ElevenLabs Conversational AI**: Premium voice quality provider.**🎵 Background Music**: Ambient music during AI calls.\n\n**🔧 Complete Tool Support**: Works across ALL pipeline types.**📚 Documentation Overhaul**: Reorganized structure.**💬 Discord Community**: Official server integration.\n\n**🤖 Google Live API**: Gemini 2.0 Flash integration.**🚀 Interactive Setup**:`agent init`\n\nwizard (`agent quickstart`\n\nremains available for backward compatibility).\n\n**🔧 Tool Calling System**: Transfer calls, send emails.**🩺 Agent CLI Tools**:`doctor`\n\n,`troubleshoot`\n\n,`demo`\n\n.\n\n| Feature | Benefit |\n|---|---|\nAsterisk-Native |\nWorks directly with your existing Asterisk/FreePBX - no external telephony providers required. |\nTruly Open Source |\nMIT licensed with complete transparency and control. |\nModular Architecture |\nChoose cloud, local, or hybrid - mix providers as needed. |\nProduction-Ready |\nBattle-tested baselines with Call History-first debugging. |\nCost-Effective |\nLocal Hybrid costs ~$0.001-0.003/minute (LLM only). |\nPrivacy-First |\nKeep audio local while using cloud intelligence. |\n\n-\n**OpenAI Realtime**(Recommended for Quick Start)- Modern cloud AI with natural conversations (<2s response).\n- Config:\n`config/ai-agent.golden-openai.yaml`\n\n*Best for: Enterprise deployments, quick setup.*\n\n-\n**Deepgram Voice Agent**(Enterprise Cloud)- Advanced Think stage for complex reasoning (<3s response).\n- Config:\n`config/ai-agent.golden-deepgram.yaml`\n\n*Best for: Deepgram ecosystem, advanced features.*\n\n-\n**Google Live API**(Multimodal AI)- Gemini Live (Flash) with multimodal capabilities (<2s response).\n- Config:\n`config/ai-agent.golden-google-live.yaml`\n\n*Best for: Google ecosystem, advanced AI features.*\n\n-\n**ElevenLabs Agent**(Premium Voice Quality)- ElevenLabs Conversational AI with premium voices (<2s response).\n- Config:\n`config/ai-agent.golden-elevenlabs.yaml`\n\n*Best for: Voice quality priority, natural conversations.*\n\n-\n**Local Hybrid**(Privacy-Focused)- Local STT/TTS + Cloud LLM (OpenAI). Audio stays on-premises.\n- Config:\n`config/ai-agent.golden-local-hybrid.yaml`\n\n*Best for: Audio privacy, cost control, compliance.*\n\n-\n**Telnyx AI Inference**(Cost-Effective Multi-Model)- Local STT/TTS + Telnyx LLM with 53+ models (GPT-4o, Claude, Llama).\n- OpenAI-compatible API with competitive pricing.\n- Config:\n`config/ai-agent.golden-telnyx.yaml`\n\n*Best for: Model flexibility, cost optimization, multi-provider access.*\n\n-\n**xAI Grok Voice Agent**(Realtime Voice)- xAI realtime voice with five named voices (\n`eve`\n\n/`ara`\n\n/`rex`\n\n/`sal`\n\n/`leo`\n\n) or a custom cloned voice; μ-law @ 8 kHz caller input and observed PCM16 @ 24 kHz output converted for Asterisk. - Config:\n`config/ai-agent.golden-grok.yaml`\n\n*Best for: xAI ecosystem, telephony-native low-latency audio.*\n\n- xAI realtime voice with five named voices (\n\n**MiniMax LLM**(High-Performance Cost-Effective)- Local STT/TTS + MiniMax M3 LLM with enhanced reasoning and coding.\n- OpenAI-compatible API with tool-calling support.\n- Models:\n`MiniMax-M3`\n\n(default, latest flagship),`MiniMax-M2.7`\n\n(previous flagship),`MiniMax-M2.7-highspeed`\n\n(low-latency). - Activate: set\n`MINIMAX_API_KEY`\n\nin`.env`\n\n, then configure`providers.minimax_llm`\n\nin`config/ai-agent.yaml`\n\n(see the`minimax_llm`\n\nsection with`enabled: true`\n\n). *Best for: Long-context conversations, cost-effective high-performance LLM.*\n\nAVA also supports a **Fully Local** mode (100% on-premises, no cloud APIs). Three topologies are supported:\n\n| Topology | Latency | Best For |\n|---|---|---|\nCPU-Only |\n5-15s/turn | Privacy, testing |\nGPU (same box) |\n0.5-2s/turn | Production local |\nSplit-Server (remote GPU) |\n1-3s/turn | PBX on VPS + GPU box |\n\nGPU setup uses `docker-compose.gpu.yml`\n\noverlay with CUDA-enabled llama.cpp. Community-validated: RTX 4090 achieves ~1.0s E2E.\n\n- See:\n(canonical guide for all local topologies)[docs/LOCAL_ONLY_SETUP.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/LOCAL_ONLY_SETUP.md) - Hardware guidance:\n[docs/HARDWARE_REQUIREMENTS.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/HARDWARE_REQUIREMENTS.md)\n\nRun your own local LLM using [Ollama](https://ollama.ai) - perfect for privacy-focused deployments:\n\n```\n# In ai-agent.yaml\nactive_pipeline: local_hybrid\npipelines:\n  local_hybrid:\n    stt: local_stt\n    llm: ollama_llm\n    tts: local_tts\n```\n\n**Features:**\n\n**No API key required**- fully self-hosted on your network** Tool calling support**with compatible models (Llama 3.2, Mistral, Qwen)- Local Vosk STT + Your Ollama LLM + Local Piper TTS\n- Complete privacy - all processing stays on-premises\n\n**Requirements:**\n\n- Mac Mini, gaming PC, or server with Ollama installed\n- 8GB+ RAM (16GB+ recommended for larger models)\n- See\n[docs/OLLAMA_SETUP.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/OLLAMA_SETUP.md)for setup guide\n\n**Recommended Models:**\n\n| Model | Size | Tool Calling |\n|---|---|---|\n`llama3.2` |\n2GB | ✅ Yes |\n`mistral` |\n4GB | ✅ Yes |\n`qwen2.5` |\n4.7GB | ✅ Yes |\n\n**Tool Calling System**: AI-powered actions (transfers, emails) work with any provider.** Agent CLI Tools**:`setup`\n\n,`check`\n\n,`rca`\n\n,`update`\n\n,`version`\n\ncommands (legacy aliases:`init`\n\n,`doctor`\n\n,`troubleshoot`\n\n).**Modular Pipeline System**: Independent STT, LLM, and TTS provider selection.** Dual Transport Support**: AudioSocket (default in`config/ai-agent.yaml`\n\n) and ExternalMedia RTP (both supported — see the transport matrix).**Streaming-First Downstream**: Streaming playback when possible, with automatic fallback to file playback for robustness.** High-Performance Architecture**: Separate`ai_engine`\n\nand`local_ai_server`\n\ncontainers.**Observability**: Built-in** Call History**for per-call debugging + optional`/metrics`\n\nscraping.**State Management**: SessionStore for centralized, typed call state.** Barge-In Support**: Interrupt handling with configurable gating.\n\nModern web interface for configuration and system management.\n\n**Quick Start:**\n\n```\ndocker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui\n# Access at: http://localhost:3003\n# Retrieve one-time password: docker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password\n```\n\n**Key Features:**\n\n**Setup Wizard**: Visual provider configuration.** Dashboard**: Real-time system metrics, container status, and Asterisk connection indicator.** Asterisk Setup**: Live ARI status, module checklist, config audit with guided fix commands.** Live Logs**: WebSocket-based log streaming.** YAML Editor**: Monaco-based editor with validation.\n\nExperience our production-ready configurations with a single phone call:\n\n**Dial: (925) 736-6718**\n\n**Press 4**→ xAI Grok Realtime (NEW in v6.5.2)** Press 5**→ Google Live API (Multimodal AI with Gemini 2.0)** Press 6**→ Deepgram Voice Agent (Enterprise cloud with Think stage)** Press 7**→ OpenAI Realtime API (Modern cloud AI, most natural)** Press 8**→ Local Hybrid Pipeline (Privacy-focused, audio stays local)** Press 9**→ ElevenLabs Agent (Santa voice with background music)** Press 10**→ Fully Local Pipeline (100% on-premises, CPU-based)\n\nYour AI agent can perform real-world telephony actions through tool calling.\n\n```\nCaller: \"Transfer me to the sales team\"\nAgent: \"I'll connect you to our sales team right away.\"\n[Transfer to sales queue with queue music]\n```\n\n**Supported Destinations:**\n\n**Extensions**: Direct SIP/PJSIP endpoint transfers.** Queues**: ACD queue transfers with position announcements.** Ring Groups**: Multiple agents ring simultaneously.\n\n**Cancel Transfer**: \"Actually, cancel that\" (during ring).** Hangup Call**: Ends call gracefully with farewell.** Voicemail**: Routes to voicemail box.\n\n**Automatic Call Summaries**: Admins receive full transcripts and metadata.** Caller-Requested Transcripts**: \"Email me a transcript of this call.\"\n\n| Tool | Description | Status |\n|---|---|---|\n`transfer` |\nTransfer to extensions, queues, or ring groups | ✅ |\n`cancel_transfer` |\nCancel in-progress transfer (during ring) | ✅ |\n`hangup_call` |\nEnd call gracefully with farewell message | ✅ |\n`leave_voicemail` |\nRoute caller to voicemail extension | ✅ |\n`send_email_summary` |\nAuto-send call summaries to admins | ⚙️ Disabled by default |\n`request_transcript` |\nCaller-initiated email transcripts | ⚙️ Disabled by default |\n\n```\n# In ai-agent.yaml\ntools:\n  pre_call_lookup:\n    kind: generic_http_lookup\n    phase: pre_call\n    enabled: true\n    is_global: false\n  post_call_webhook:\n    kind: generic_webhook\n    phase: post_call\n    enabled: true\n    is_global: false\n\nin_call_tools:\n  intent_router:\n    kind: in_call_http_lookup\n    enabled: true\n    is_global: false\n\ncontexts:\n  default:\n    pre_call_tools:\n      - pre_call_lookup\n    tools:\n      - intent_router\n      - hangup_call\n    post_call_tools:\n      - post_call_webhook\n```\n\nProduction-ready CLI for operations and setup.\n\n**Installation:**\n\n```\ncurl -sSL https://raw.githubusercontent.com/hkjarral/Asterisk-AI-Voice-Agent/main/scripts/install-cli.sh | bash\n```\n\n**Commands:**\n\n```\nagent setup               # Interactive setup wizard (recommended)\nagent setup --list-targets # List configured providers and pipelines without changes\nagent check               # Standard diagnostics report (share this output when asking for help)\nagent check --local       # Verify local AI server (STT, LLM, TTS) on this host\nagent check --remote <ip> # Verify local AI server on a remote GPU machine\nagent update              # Pull latest code + rebuild/restart as needed\nagent rca --call <call_id> --no-llm # Deterministic post-call RCA\nagent config validate     # Validate provider, pipeline, transport, and audio configuration\nagent dialplan --agent default # Generate an AI_AGENT dialplan snippet\nagent version             # Version information\n```\n\n- Golden baseline configs (git-tracked, upstream-managed).`config/ai-agent.yaml`\n\n- Operator overrides (git-ignored). Any keys here are deep-merged on top of the base file at startup; all Admin UI and CLI writes go here so upstream updates never conflict.`config/ai-agent.local.yaml`\n\n- Secrets and API keys (git-ignored).`.env`\n\n**Example .env:**\n\n```\nOPENAI_API_KEY=sk-your-key-here\nDEEPGRAM_API_KEY=your-key-here\nASTERISK_ARI_USERNAME=asterisk\nASTERISK_ARI_PASSWORD=your-password\n```\n\nThe engine exposes Prometheus-format metrics on its health/metrics HTTP endpoint at\n`/metrics`\n\n(port `15000`\n\n). This endpoint binds to `127.0.0.1`\n\nby default, so it is only\nreachable from the engine host — scrape it locally, or set the health endpoint `host`\n\nto\n`0.0.0.0`\n\n(and firewall it) to expose it to an external Prometheus.\nPer-call debugging is handled via **Admin UI → Call History**.\n\nTwo-container architecture for performance and scalability:\n\n(Lightweight orchestrator): Connects to Asterisk via ARI, manages call lifecycle.`ai_engine`\n\n(Optional): Runs local STT/LLM/TTS models (Vosk, Faster Whisper, Whisper.cpp, Sherpa, Kroko, Piper, Kokoro, MeloTTS, llama.cpp).`local_ai_server`\n\n``` php\ngraph LR\n    A[Asterisk Server] <-->|ARI, RTP| B[ai_engine]\n    B <-->|API| C[AI Provider]\n    B <-->|WS| D[local_ai_server]\n    \n    style A fill:#f9f,stroke:#333,stroke-width:2px\n    style B fill:#bbf,stroke:#333,stroke-width:2px\n    style C fill:#bfb,stroke:#333,stroke-width:2px\n    style D fill:#fbf,stroke:#333,stroke-width:2px\n```\n\n| Requirement | Details |\n|---|---|\nArchitecture |\nx86_64 (AMD64) only |\nOS |\nLinux with systemd |\nSupported Distros |\nUbuntu 20.04+, Debian 11+, RHEL/Rocky/Alma 8+, Fedora 38+, Sangoma Linux |\n\nNote:ARM64 (Apple Silicon, Raspberry Pi) is not currently supported. See[Supported Platforms]for the full compatibility matrix.\n\n| Type | CPU | RAM | GPU | Disk |\n|---|---|---|---|---|\nCloud (OpenAI/Deepgram) |\n2+ cores | 4GB | None | 1GB |\nLocal Hybrid (cloud LLM) |\n4+ cores | 8GB+ | None | 2GB |\nFully Local (CPU) |\n4+ cores (2020+) | 8-16GB | None | 5GB |\nFully Local (GPU) |\n4+ cores | 8-16GB | RTX 3060+ | 10GB |\n\n- Docker + Docker Compose v2\n- Asterisk 18+ with ARI enabled\n- FreePBX (recommended) or vanilla Asterisk\n\nThe `preflight.sh`\n\nscript handles initial setup:\n\n- Seeds\n`.env`\n\nfrom`.env.example`\n\nwith your settings - Prompts for Asterisk config directory location\n- Sets\n`ASTERISK_UID`\n\n/`ASTERISK_GID`\n\nto match host permissions (fixes media access issues) - Re-running preflight often resolves permission problems\n\n[Configuration Reference](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Configuration-Reference.md)[Transport Compatibility](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Transport-Mode-Compatibility.md)[Tuning Recipes](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Tuning-Recipes.md)[Supported Platforms](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/SUPPORTED_PLATFORMS.md)[Local Profiles](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/LOCAL_PROFILES.md)[Monitoring Guide](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/MONITORING_GUIDE.md)\n\n—[Outbound Calling](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/OUTBOUND_CALLING.md)`Alpha`\n\n— scheduled campaigns, voicemail drop, consent gate—[FreeSWITCH (FS-PBX) Setup](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/FS-PBX-Setup-Instructions.md)`Community`\n\n— community-maintained guide—[ViciDial Setup](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/Vicidial-Setup.md)`Community`\n\n— community-tested configuration notes\n\n`Alpha`\n\n= usable but still hardening. `Community`\n\n= contributed and community-validated, not maintainer-tested on every release. Features without a label are stable.\n\n- What's next, planned milestones, and how to get involved[Roadmap](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/ROADMAP.md)[Developer Documentation](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/README.md)[Architecture Deep Dive](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/architecture-deep-dive.md)[Contributing Guide](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CONTRIBUTING.md)- Completed milestones 1-24[Milestone History](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/MILESTONE_HISTORY.md)\n\n**You don't need to be a developer to contribute.** File feature ideas, report bugs\nwith logs attached, improve documentation, or share your dialplan recipes — these are\nas valuable as code. If you do want to write code, see the Contributing Guide below.\n\n```\ngit clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git\ncd AVA-AI-Voice-Agent-for-Asterisk\n```\n\nThen load ** AVA.mdc** into your AI coding assistant (Claude, Cursor, Windsurf, Codex, Copilot, …) — it carries the project map, engineering guardrails, and contribution workflow — and tell it what you want to build or fix.\n\n| Guide | For |\n|---|---|\n|\nFull contribution guidelines and workflow |\n|\nDev environment setup in ~15 minutes |\n|\nCode standards for all contributions |\n|\nWhat to work on next |\n\n| Area | Guide | Reference |\n|---|---|---|\n| Full-Agent Provider |\n|\n\n[Implementation deep-dives](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/references)[Pipeline Development](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/pipeline-development.md)[Example pipelines](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/examples/pipelines)[Tool Development](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/tool-development.md)[Tool Calling Guide](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/TOOL_CALLING_GUIDE.md)[Developer Onboarding](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/DEVELOPER_ONBOARDING.md)- Project overview and first tasks[Developer Quickstart](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/quickstart.md)- Set up your dev environment[Developer Documentation](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/docs/contributing/README.md)- Full contributor docs\n\nhkjarral |\n\nArchitecture, Code\n\n**Abhishek** Telnyx LLM Provider\n\n**turgutguvercin** NumPy Resampler\n\n**Scarjit** Code\n\n**egorky** Azure STT/TTS Provider\n\n**alemstrom** Docs — PBX Setup\n\n**gcsuri** Code — Google Calendar\n\n**octo-patch** MiniMax LLM Provider\n\n**neilruaro-camb** CAMB AI TTS Provider\n\n**aoi-dev-0411** Transcript Search, Health Badges\n\n**exaland** Outbound .ULAW Compatibility\n\n**YosefAdPro** Agents API/OpenAPI\n\nSee [CONTRIBUTORS.md](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/CONTRIBUTORS.md) for the full list — contributions are recognized there, in release notes, and on Discord.\n\n- Support and discussions[Discord Server](https://discord.gg/ysg8fphxUe)[GitHub Issues](https://github.com/hkjarral/Asterisk-AI-Voice-Agent/issues)- Bug reports[GitHub Discussions](https://github.com/hkjarral/Asterisk-AI-Voice-Agent/discussions)- General chat\n\nThis project is licensed under the MIT License. See the [LICENSE](/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/blob/main/LICENSE) file for details.\n\nAsterisk AI Voice Agent is **free and open source**. If it's saving you money, consider supporting development:\n\nYour support funds:\n\n- 🐛 Faster bug fixes and issue responses\n- ✨ New provider integrations and features\n- 📚 Better documentation and tutorials\n\nIf you find this project useful, please also give it a ⭐️!", "url": "https://wpnews.pro/news/show-hn-self-hosted-voice-ai-agent-for-asterisk-freepbx", "canonical_source": "https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk", "published_at": "2026-07-13 02:51:34+00:00", "updated_at": "2026-07-13 03:05:18.750188+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools"], "entities": ["Asterisk", "FreePBX", "AVA-AI-Voice-Agent-for-Asterisk", "hkjarral"], "alternates": {"html": "https://wpnews.pro/news/show-hn-self-hosted-voice-ai-agent-for-asterisk-freepbx", "markdown": "https://wpnews.pro/news/show-hn-self-hosted-voice-ai-agent-for-asterisk-freepbx.md", "text": "https://wpnews.pro/news/show-hn-self-hosted-voice-ai-agent-for-asterisk-freepbx.txt", "jsonld": "https://wpnews.pro/news/show-hn-self-hosted-voice-ai-agent-for-asterisk-freepbx.jsonld"}}