Skip to main content
Agentic AI requires a public URL for Twilio to send webhook requests and establish Media Stream WebSocket connections. During local development, you’ll need a tunnel service to expose your local server.

​
Why You Need a Tunnel

Twilio’s servers need to reach your application:
  1. Voice Webhooks - TwiML instructions when a call starts (POST /twilio/voice)
  2. Media Streams - Real-time audio WebSocket (WSS /twilio/media-stream)
Since your local machine isn’t publicly accessible, a tunnel creates a secure connection between Twilio and your local server.

​
Tunnel Providers

Agentic AI supports two popular tunnel providers:

ngrok

Popular, easy to use, generous free tier

Cloudflare Tunnel

Enterprise-grade, unlimited bandwidth, free

​
ngrok Setup

ngrok is the most popular tunneling solution and easiest to get started with.

​
Step 1: Install ngrok

brew install ngrok

​
Step 2: Get Your Auth Token

  1. Sign up at ngrok.com
  2. Go to dashboard.ngrok.com/get-started/your-authtoken
  3. Copy your authtoken

​
Step 3: Configure ngrok

ngrok config add-authtoken YOUR_AUTHTOKEN_HERE

​
Step 4: Start the Tunnel

agenticai tunnel start
You’ll see output like: 
Session Status                online
Account                       [email protected]
Version                       3.x.x
Region                        United States (us)
Forwarding                    https://abc123.ngrok.io -> http://localhost:8080
Copy the https://abc123.ngrok.io URL - this is your webhook URL!

​
Step 5: Configure Agentic AI

Add the ngrok URL to your .env (optional): 
# Optional: Set a fixed URL for paid plans
NGROK_URL=https://your-custom-domain.ngrok.io
Or pass it when starting the service: 
agenticai service install --webhook-url https://abc123.ngrok.io
agenticai service start

​
ngrok Free vs Paid

FeatureFreePaid ($8/month)
Tunnel count1 online tunnel3+ tunnels
URL formatRandom (https://abc123.ngrok.io)Custom domain
URL persistenceChanges on restartFixed domain
Rate limiting40 requests/minuteHigher limits
Best forDevelopmentProduction
Free ngrok URLs change every time you restart ngrok. You’ll need to update your Twilio webhook configuration each time.

​
Cloudflare Tunnel

Cloudflare Tunnel (formerly Argo Tunnel) is a free, enterprise-grade alternative with unlimited bandwidth.

​
Step 1: Install cloudflared

brew install cloudflare/cloudflare/cloudflared

​
Step 2: Authenticate

cloudflared tunnel login
This opens a browser where you’ll authorize cloudflared to your Cloudflare account.

​
Step 3: Create a Tunnel

# Create a named tunnel
cloudflared tunnel create agenticai

# Note the Tunnel ID that appears (e.g., "abc123-def456-ghi789")

​
Step 4: Configure the Tunnel

Create ~/.cloudflared/config.yml: 
tunnel: agenticai
credentials-file: /home/YOUR_USER/.cloudflared/abc123-def456-ghi789.json

ingress:
  - hostname: agenticai.yourdomain.com
    service: http://localhost:8080
  - service: http_status:404
Replace:
  • YOUR_USER with your username
  • abc123-def456-ghi789 with your actual tunnel ID
  • agenticai.yourdomain.com with a subdomain you own

​
Step 5: Add DNS Record

cloudflared tunnel route dns agenticai agenticai.yourdomain.com
This creates a CNAME record pointing to your tunnel.

​
Step 6: Start the Tunnel

cloudflared tunnel run agenticai
Your tunnel is now active at https://agenticai.yourdomain.com!

​
Step 7: Configure Agentic AI

Update config.yaml: 
tunnel:
  enabled: true
  provider: "cloudflare"
  url: "https://agenticai.yourdomain.com"

​
Run as a Service

Install cloudflared as a system service for automatic startup: 
sudo cloudflared service install
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

​
Cloudflare Tunnel Benefits

  • Free, unlimited bandwidth
  • Fixed custom domain
  • DDoS protection
  • No rate limiting
  • Enterprise-grade reliability
  • Survives restarts
Cloudflare Tunnel requires you to own a domain managed by Cloudflare.

​
Configuration Reference

Configure tunnel behavior in config.yaml: 
tunnel:
  enabled: false  # Auto-start tunnel with Agentic AI
  provider: "ngrok"  # or "cloudflare"
  url: ${NGROK_URL:}  # Fixed URL (paid plans)
​
tunnel.enabled
boolean
default:false
Enable automatic tunnel startup.
Most users should manage tunnels separately and set this to false.
Set to true only if you want Agentic AI to manage the tunnel process.
​
tunnel.provider
string
default:"ngrok"
The tunnel provider to use.Options:
  • ngrok - Most popular, easy setup
  • cloudflare - Enterprise-grade, custom domain
​
tunnel.url
string
A fixed tunnel URL (for paid plans with custom domains).Examples:
  • ngrok: https://myapp.ngrok.io
  • Cloudflare: https://agenticai.yourdomain.com
If empty, the URL must be provided when starting the service:
agenticai service install --webhook-url https://abc123.ngrok.io

​
Setting Up Twilio Webhooks

Once your tunnel is running, configure Twilio to use it:

​
For Incoming Calls

  1. Go to Twilio Console → Phone Numbers → Manage → Active Numbers
  2. Click your phone number
  3. Under “Voice & Fax” → “A call comes in”:
    • Set to: Webhook
    • URL: https://your-tunnel-url.com/twilio/voice
    • Method: HTTP POST
  4. Click Save

​
For Outgoing Calls

When triggering calls via CLI, pass the webhook URL: 
agenticai trigger --to +1234567890 --webhook-url https://your-tunnel-url.com
The CLI automatically appends /twilio/voice to the webhook path.

​
Webhook Endpoints

Your tunnel exposes these endpoints:
EndpointProtocolPurpose
/twilio/voiceHTTP POSTTwiML webhook for call setup
/twilio/media-streamWebSocketReal-time audio streaming
/healthHTTP GETHealth check

​
Testing Your Tunnel

​
1. Test HTTP Webhook

curl -X POST https://your-tunnel-url.com/twilio/voice \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "From=+1234567890&To=+0987654321"
You should receive a TwiML response.

​
2. Test WebSocket Connection

Use a WebSocket client: 
wscat -c wss://your-tunnel-url.com/twilio/media-stream

​
3. Test with Actual Call

agenticai trigger --to +1234567890 --webhook-url https://your-tunnel-url.com
Your phone should ring!

​
Production Considerations

For production deployments, avoid tunnels entirely. Deploy to a cloud provider with a public IP.
  1. Deploy to cloud - AWS, GCP, Azure, DigitalOcean, etc.
  2. Use a real domain - e.g., api.yourcompany.com
  3. Enable HTTPS - Let’s Encrypt or cloud provider SSL
  4. Set up monitoring - Track webhook health
  5. Configure firewall - Only allow Twilio IPs

​
When to Use Tunnels

  • Local development and testing
  • Demos and proof-of-concepts
  • Debugging webhook issues
  • Short-term staging environments

​
When NOT to Use Tunnels

  • Production deployments
  • High-traffic applications
  • Mission-critical services
  • Compliance-sensitive environments

​
Troubleshooting

​
Tunnel not connecting

ngrok: 
# Check if ngrok is running
ps aux | grep ngrok

# Restart tunnel
pkill ngrok
ngrok http 8080
Cloudflare: 
# Check tunnel status
cloudflared tunnel list
cloudflared tunnel info agenticai

# Check service logs
sudo journalctl -u cloudflared -f

​
Twilio can’t reach webhook

  1. Verify tunnel is running:
curl https://your-tunnel-url.com/health
  1. Check Agentic AI server is running:
agenticai service status
  1. Check firewall - Ensure port 8080 is accessible locally
  2. Check Twilio webhook logs:

​
Random disconnections

  • ngrok free tier - Has timeout limits, upgrade or switch to Cloudflare
  • Network instability - Check your internet connection
  • Server crashes - Check Agentic AI logs: agenticai service logs

​
URL changes on restart (ngrok)

Free ngrok URLs are temporary. Options:
  1. Upgrade to paid - Get a fixed domain ($8/month)
  2. Use Cloudflare Tunnel - Free fixed domain
  3. Script the update - Auto-update Twilio webhooks on restart

​
SSL/TLS errors

Twilio requires HTTPS. Both ngrok and Cloudflare provide automatic SSL:
  • ngrok: https://abc123.ngrok.io (automatic)
  • Cloudflare: https://agenticai.yourdomain.com (automatic)
Do NOT use http:// URLs with Twilio.

​
Advanced: Custom Tunnel Integration

If you’re using a different tunnel provider (localtunnel, bore, etc.), configure it manually:
  1. Start your custom tunnel
  2. Set tunnel.enabled: false in config.yaml
  3. Pass the webhook URL when starting:
agenticai service install --webhook-url https://your-custom-tunnel.com

Build docs developers (and LLMs) love

Get started for freeTalk to us