Get the Admin UI running in 2 minutes.

For a complete first successful call walkthrough (dialplan + transport selection + verification), see:

# Clone repository
git clone https://github.com/hkjarral/Asterisk-AI-Voice-Agent.git
cd Asterisk-AI-Voice-Agent

# Run preflight with auto-fix (creates .env, generates JWT_SECRET)
sudo ./preflight.sh --apply-fixes

Important: Preflight creates your .env file and generates a secure JWT_SECRET. Always run this first!

# Start the Admin UI container
docker compose up -d --build admin-ui

Open in your browser:

• Local: http://localhost:3003
• Remote server: http://<server-ip>:3003

Default Login: admin / admin

Follow the Setup Wizard to configure your providers and make a test call.

⚠️ Security: The Admin UI is accessible on the network. Change the default password immediately and restrict port 3003 via firewall, VPN, or reverse proxy for production use.

# Start ai-engine (required for health checks)
docker compose up -d --build ai-engine

# Check ai-engine health
curl http://localhost:15000/health
# Expected: {"status":"healthy"}

# View logs for any errors
docker compose logs ai-engine | tail -20

The wizard will generate the necessary dialplan configuration for your Asterisk server.

Transport selection is configuration-dependent (not strictly “pipelines vs full agents”). Use the validated matrix in:

For users who prefer the command line or need headless setup.

./install.sh
agent quickstart

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Start services
docker compose up -d

Add this to your FreePBX (extensions_custom.conf):

[from-ai-agent]
exten => s,1,NoOp(Asterisk AI Voice Agent v4.5.3)
 same => n,Stasis(asterisk-ai-voice-agent)
 same => n,Hangup()

Health check:

View logs:

docker compose logs -f ai-engine

1. OpenAI Realtime (Recommended for Quick Start)

   • Modern cloud AI with natural conversations (<2s response).
   • Config: config/ai-agent.golden-openai.yaml
   • Best for: Enterprise deployments, quick setup.

2. Deepgram Voice Agent (Enterprise Cloud)

   • Advanced Think stage for complex reasoning (<3s response).
   • Config: config/ai-agent.golden-deepgram.yaml
   • Best for: Deepgram ecosystem, advanced features.

3. Google Live API (Multimodal AI)

   • Gemini Live (Flash) with multimodal capabilities (<2s response).
   • Config: config/ai-agent.golden-google-live.yaml
   • Best for: Google ecosystem, advanced AI features.

4. ElevenLabs Agent (Premium Voice Quality)

   • ElevenLabs Conversational AI with premium voices (<2s response).
   • Config: config/ai-agent.golden-elevenlabs.yaml
   • Best for: Voice quality priority, natural conversations.

5. Local Hybrid (Privacy-Focused)

   • Local STT/TTS + Cloud LLM (OpenAI). Audio stays on-premises.
   • Config: config/ai-agent.golden-local-hybrid.yaml
   • Best for: Audio privacy, cost control, compliance.

Run your own local LLM using Ollama - perfect for privacy-focused deployments:

# In ai-agent.yaml
active_pipeline: local_ollama

Features:

• 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
• Complete privacy - all processing stays on-premises

Requirements:

• Mac Mini, gaming PC, or server with Ollama installed
• 8GB+ RAM (16GB+ recommended for larger models)
• See docs/OLLAMA_SETUP.md for setup guide

Recommended Models:

• Tool Calling System: AI-powered actions (transfers, emails) work with any provider.
• Agent CLI Tools: doctor, troubleshoot, demo, init commands.
• Modular Pipeline System: Independent STT, LLM, and TTS provider selection.
• Dual Transport Support: AudioSocket and ExternalMedia RTP (see Transport Compatibility matrix).
• High-Performance Architecture: Separate ai-engine and local-ai-server containers.
• Observability: Built-in Call History for per-call debugging + optional /metrics scraping.
• State Management: SessionStore for centralized, typed call state.
• Barge-In Support: Interrupt handling with configurable gating.

Modern web interface for configuration and system management.

Quick Start:

docker compose up -d admin-ui
# Access at: http://localhost:3003
# Login: admin / admin (change immediately!)

Key Features:

• Setup Wizard: Visual provider configuration.
• Dashboard: Real-time system metrics and container status.
• Live Logs: WebSocket-based log streaming.
• YAML Editor: Monaco-based editor with validation.

Experience our production-ready configurations with a single phone call:

Dial: (925) 736-6718

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

Your AI agent can perform real-world telephony actions through tool calling.

Caller: "Transfer me to the sales team"
Agent: "I'll connect you to our sales team right away."
[Transfer to sales queue with queue music]

Supported Destinations:

• Extensions: Direct SIP/PJSIP endpoint transfers.
• Queues: ACD queue transfers with position announcements.
• Ring Groups: Multiple agents ring simultaneously.

• Cancel Transfer: "Actually, cancel that" (during ring).
• Hangup Call: Ends call gracefully with farewell.
• Voicemail: Routes to voicemail box.

• Automatic Call Summaries: Admins receive full transcripts and metadata.
• Caller-Requested Transcripts: "Email me a transcript of this call."

Production-ready CLI for operations and setup.

Installation:

curl -sSL https://raw.githubusercontent.com/hkjarral/Asterisk-AI-Voice-Agent/main/scripts/install-cli.sh | bash

Commands:

agent quickstart          # Interactive setup wizard
agent dialplan            # Generate dialplan snippets
agent config validate     # Validate configuration
agent doctor --fix        # System health check
agent troubleshoot        # Analyze specific call
agent demo                # Demo features

Example .env:

OPENAI_API_KEY=sk-your-key-here
DEEPGRAM_API_KEY=your-key-here
ASTERISK_ARI_USERNAME=asterisk
ASTERISK_ARI_PASSWORD=your-password

The engine exposes Prometheus-format metrics at http://<engine-host>:15000/metrics. Per-call debugging is handled via Admin UI → Call History.

Two-container architecture for performance and scalability:

1. ai-engine (Lightweight orchestrator): Connects to Asterisk via ARI, manages call lifecycle.
2. local-ai-server (Optional): Runs local STT/LLM/TTS models (Vosk, Sherpa, Kroko, Piper, Kokoro, llama.cpp).

graph LR
    A[Asterisk Server] <-->|ARI, RTP| B[ai-engine]
    B <-->|API| C[AI Provider]
    B <-->|WS| D[local-ai-server]
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px
    style C fill:#bfb,stroke:#333,stroke-width:2px
    style D fill:#fbf,stroke:#333,stroke-width:2px

Note: ARM64 (Apple Silicon, Raspberry Pi) is not currently supported. See Supported Platforms for the full compatibility matrix.

• Docker + Docker Compose v2
• Asterisk 18+ with ARI enabled
• FreePBX (recommended) or vanilla Asterisk

The preflight.sh script handles initial setup:

• Seeds .env from .env.example with your settings
• Prompts for Asterisk config directory location
• Sets ASTERISK_UID/ASTERISK_GID to match host permissions (fixes media access issues)
• Re-running preflight often resolves permission problems

Contributions are welcome! Please see our Contributing Guide.

This project is licensed under the MIT License. See the LICENSE file for details.

If you find this project useful, please give it a ⭐️ on GitHub!