FreeSWITCH Proxy with LiveKit AI Integration

A production-ready FreeSWITCH Docker deployment with web UI, SSL/TLS support, and LiveKit cloud integration for AI-powered call handling.

🚀 Features

FreeSWITCH PBX: Complete SIP telephony server running in Docker
Web Management UI: Secure HTTPS control panel for system management
LiveKit Integration: Ready for AI agent voice calls with natural ring simulation
SSL/TLS Security: Let's Encrypt certificate with auto-renewal
PostgreSQL Database: For configuration and call records
Call Recording: Automatic recording of all calls
Ring Simulation: 2-5 seconds random ring before AI answers

📋 System Architecture

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Incoming      │────▶│  FreeSWITCH  │────▶│  LiveKit Cloud  │
│   SIP Calls     │     │   (Docker)   │     │   AI Agents     │
└─────────────────┘     └──────────────┘     └─────────────────┘
                              │
                              ▼
                        ┌──────────────┐
                        │   Web UI     │
                        │  (HTTPS)     │
                        └──────────────┘

🔧 Quick Start

Prerequisites

Docker & Docker Compose installed
Domain name (using ladgig.com)
LiveKit Cloud account

Installation

Clone the repository:

git clone https://github.com/yourusername/freeswitch-proxy.git
cd freeswitch-proxy

Configure LiveKit credentials: Edit configs/vars.xml and update:

<X-PRE-PROCESS cmd="set" data="livekit_cloud_host=your-app.livekit.cloud"/>
<X-PRE-PROCESS cmd="set" data="livekit_cloud_api_key=YOUR_API_KEY"/>
<X-PRE-PROCESS cmd="set" data="livekit_cloud_api_secret=YOUR_API_SECRET"/>

Start services:

# Start FreeSWITCH and database
docker-compose -f docker-compose.fusionpbx.yml up -d

# Start secure web UI
docker-compose -f docker-compose.secure-ui.yml up -d

Access Web UI:

URL: https://ladgig.com
Username: admin
Password: Admin2025!

📁 Project Structure

freeswitch/
├── configs/                 # FreeSWITCH configuration files
│   ├── dialplan/           # Call routing rules
│   │   ├── ivr.xml         # IVR configuration
│   │   └── livekit-ai-agent.xml  # AI agent routing
│   ├── sip_profiles/       # SIP endpoints
│   │   ├── internal.xml    # Internal profile (5060)
│   │   ├── external.xml    # External profile (5080)
│   │   └── livekit.xml     # LiveKit profile (5061)
│   ├── scripts/            # Lua call handling scripts
│   │   └── ai_agent_handler.lua  # AI agent call flow
│   └── vars.xml            # Global variables & settings
├── docker/                 # Docker build files
│   └── Dockerfile          # FreeSWITCH container
├── simple-webui/           # Web management interface
│   └── index.php           # Control panel
├── ssl/                    # SSL certificates
├── scripts/                # Utility scripts
│   ├── renew-ssl.sh       # SSL renewal script
│   └── generate-ssl.sh    # Certificate generation
├── docker-compose.yml      # Main services
├── docker-compose.secure-ui.yml  # HTTPS web UI
└── nginx-ssl.conf         # Nginx HTTPS configuration

🔐 Security Features

SSL/TLS Certificate

Provider: Let's Encrypt (trusted CA)
Domain: ladgig.com
Auto-renewal: Daily check at 3 AM
Valid until: November 3, 2025

Access Control

HTTPS enforced (HTTP auto-redirects)
Secure admin credentials
PostgreSQL database isolated in Docker network
FreeSWITCH ESL password protected

📞 Call Flow

Incoming Call → FreeSWITCH receives on SIP port 5060/5080
Ring Simulation → 2-5 seconds random ring tone
Auto Answer → Call answered automatically
LiveKit Bridge → Connected to AI agent in cloud
Recording → Entire call recorded to WAV file

🛠️ Configuration

SIP Settings

Internal: Port 5060 (for extensions)
External: Port 5080 (for trunks)
LiveKit: Port 5061 (for WebRTC)
RTP Ports: 16384-32768

Database

Type: PostgreSQL 13
Database: fusionpbx
User: fusionpbx
Internal Access Only

LiveKit Integration

Automatic room creation per call
UUID-based room naming
OPUS codec support
WebRTC compatible

🚦 Service Management

Check Status

# View running containers
docker ps

# Check FreeSWITCH status
docker exec freeswitch-server fs_cli -x "status"

# View active calls
docker exec freeswitch-server fs_cli -x "show calls"

# Check logs
docker-compose logs -f freeswitch

Restart Services

# Restart FreeSWITCH
docker restart freeswitch-server

# Restart Web UI
docker restart freeswitch-webui-secure

# Restart Nginx
docker restart nginx-ssl-proxy

📊 Monitoring

Web UI Dashboard

Access https://ladgig.com to view:

FreeSWITCH status
Database connection
System information
Active calls
Extensions

API Status Endpoint

curl https://ladgig.com/api-status.php

Returns JSON with service status.

🔄 Maintenance

SSL Certificate Renewal

Automatic via cron, or manual:

./scripts/renew-ssl.sh

Backup

# Backup PostgreSQL
docker exec fusionpbx-db pg_dump -U fusionpbx fusionpbx > backup.sql

# Backup configurations
tar -czf configs-backup.tar.gz configs/

Update FreeSWITCH

docker-compose pull
docker-compose up -d

🐛 Troubleshooting

No Audio

Check RTP ports in firewall
Verify NAT settings in vars.xml
Test with local extension first

LiveKit Connection Failed

Verify API credentials in vars.xml
Check network connectivity
Review FreeSWITCH logs

Web UI Not Loading

Check nginx-ssl-proxy is running
Verify SSL certificate is valid
Check port 443 is open

📝 Important Files

Credentials & Configuration

credentials-freeswitch.md - All system credentials (git-ignored)
configs/vars.xml - Main configuration variables
configs/livekit-cloud.conf - LiveKit settings
.env - Environment variables

Documentation

LIVEKIT-SETUP-GUIDE.md - LiveKit integration guide
CLAUDE.md - Development context
This README

🔗 Ports & Endpoints

Service	Port	Purpose
HTTP	80	Redirects to HTTPS
HTTPS	443	Web UI (secure)
SIP Internal	5060	Internal extensions
SIP External	5080	External trunks
SIP LiveKit	5061	LiveKit integration
ESL	8021	Event Socket Layer
RTP	16384-32768	Media/Audio

🤝 LiveKit Cloud Setup

Create SIP trunk pointing to ladgig.com:5080
Configure AI agent to join rooms with prefix ai-room-*
Set agent participant name as ai-agent
Enable OPUS codec
Configure webhook for call events (optional)

📜 License

This project uses FreeSWITCH (MPL 1.1 License) and various open-source components.

🆘 Support

For issues or questions:

Check logs: docker-compose logs
Review FreeSWITCH CLI: docker exec -it freeswitch-server fs_cli
Verify services: https://ladgig.com/api-status.php
Check documentation in /docs folder

Last Updated: August 6, 2025 Version: 1.0.0 Domain: ladgig.com

Name		Name	Last commit message	Last commit date
configs		configs
docker		docker
docs		docs
nginx		nginx
production		production
scripts		scripts
simple-webui		simple-webui
ssl		ssl
.env		.env
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
DEPLOYMENT-SUMMARY.md		DEPLOYMENT-SUMMARY.md
LIVEKIT-SETUP-GUIDE.md		LIVEKIT-SETUP-GUIDE.md
README.md		README.md
cookies.txt		cookies.txt
docker-compose.fusionpbx-v2.yml		docker-compose.fusionpbx-v2.yml
docker-compose.fusionpbx.yml		docker-compose.fusionpbx.yml
docker-compose.secure-ui.yml		docker-compose.secure-ui.yml
docker-compose.simple-ui.yml		docker-compose.simple-ui.yml
docker-compose.yml		docker-compose.yml
nginx-ssl.conf		nginx-ssl.conf

Latest commit

History

Folders and files

Repository files navigation