agenticai tunnel

Start and manage tunnels (ngrok or Cloudflare) to expose your local Agentic AI server to Twilio’s webhooks. Twilio requires a public HTTPS URL to send call events.

Commands

agenticai tunnel start

Start a tunnel to expose the local server.

agenticai tunnel start [OPTIONS]

Options

--provider

string

default:"ngrok"

Tunnel provider to useShort form: -pOptions: ngrok or cloudflareDefault: ngrokExample:

agenticai tunnel start --provider cloudflare

--port

integer

default:8080

Local port to exposeDefault: 8080Example:

agenticai tunnel start --port 3000

agenticai tunnel info

Show tunnel setup information and options.

agenticai tunnel info

Example Output:

┌────────────────────────────────────────────────────┐
│ Tunnel Options                                     │
├────────────────────────────────────────────────────┤
│ 1. ngrok (Default)                                 │
│    • Free tier available                           │
│    • Paid plans for fixed URLs                     │
│    • Install: brew install ngrok                   │
│    • Run: agenticai tunnel start                   │
│                                                    │
│ 2. Cloudflare Tunnel (Free alternative)           │
│    • No account required                           │
│    • Free random URL                               │
│    • Install: brew install cloudflared             │
│    • Run: agenticai tunnel start --provider cloudflare │
│                                                    │
│ After starting tunnel:                             │
│    1. Copy the public URL shown                    │
│    2. Set: export NGROK_URL=<url>                  │
│    3. Install service: agenticai service install --webhook-url <url> │
└────────────────────────────────────────────────────┘

Tunnel Providers

ngrok (Default)

ngrok provides secure tunnels to localhost. Installation:

# macOS
brew install ngrok

# Linux
sudo snap install ngrok

# Windows
choco install ngrok

# Or download from https://ngrok.com/download

Usage:

agenticai tunnel start

Example Output:

┌──────────────────────────────────────────┐
│ Starting ngrok Tunnel                    │
│                                          │
│ Exposing: http://localhost:8080          │
└──────────────────────────────────────────┘

ngrok                                                           
                                                                
Session Status                online                            
Account                       your-email@example.com (Plan: Free)
Version                       3.6.0                             
Region                        United States (us)                
Latency                       25ms                              
Web Interface                 http://127.0.0.1:4040             
Forwarding                    https://abc123.ngrok.io -> http://localhost:8080
                                                                
Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Copy the HTTPS URL (e.g., https://abc123.ngrok.io) and use it with:

export NGROK_URL=https://abc123.ngrok.io

Free tier limitations:

Random URL changes on each restart
Session timeout after 2 hours

Paid tier benefits:

Fixed domain (e.g., your-app.ngrok.io)
No session timeout
Custom domains

Cloudflare Tunnel

Cloudflare Tunnel provides free tunnels without an account. Installation:

# macOS
brew install cloudflared

# Linux
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

# Windows
choco install cloudflared

# Or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/

Usage:

agenticai tunnel start --provider cloudflare

Example Output:

┌──────────────────────────────────────────┐
│ Starting Cloudflare Tunnel               │
│                                          │
│ Exposing: http://localhost:8080          │
│ Free tunnel with random URL              │
└──────────────────────────────────────────┘

Copy the URL that appears and set it as AGENTICAI_WEBHOOK_URL
Or use it with: agenticai service install --webhook-url <url>

2026-03-03T10:30:45Z INF +--------------------------------------------------------------------------------------------+
2026-03-03T10:30:45Z INF |  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable):  |
2026-03-03T10:30:45Z INF |  https://abc-def-123.trycloudflare.com                                                      |
2026-03-03T10:30:45Z INF +--------------------------------------------------------------------------------------------+

Copy the URL (e.g., https://abc-def-123.trycloudflare.com) and use it. Benefits:

Completely free
No account required
No session timeout

Limitations:

Random URL (changes on restart)
For permanent URLs, use Cloudflare Tunnel with an account

Examples

ngrok Tunnel

# Start ngrok tunnel (default)
agenticai tunnel start

# Custom port
agenticai tunnel start --port 3000

# Set environment variable
export NGROK_URL=https://abc123.ngrok.io

# Use in commands
agenticai trigger --to +15551234567

Cloudflare Tunnel

# Start Cloudflare tunnel
agenticai tunnel start --provider cloudflare

# Copy the URL shown
# https://abc-def-123.trycloudflare.com

# Use in service installation
agenticai service install --webhook-url https://abc-def-123.trycloudflare.com

Development Workflow

# Terminal 1: Start server
agenticai server

# Terminal 2: Start tunnel
agenticai tunnel start
# Copy URL: https://abc123.ngrok.io

# Terminal 3: Set env and trigger calls
export NGROK_URL=https://abc123.ngrok.io
agenticai trigger --to +15551234567

Production Setup

For production, use a permanent tunnel: Option 1: ngrok with custom domain (paid)

# Requires ngrok paid plan
ngrok http 8080 --domain your-app.ngrok.io

# Install service with fixed URL
agenticai service install --webhook-url https://your-app.ngrok.io

Option 2: Cloudflare Tunnel with account (free)

# Authenticate
cloudflared tunnel login

# Create tunnel
cloudflared tunnel create agenticai

# Configure and run
cloudflared tunnel --url http://localhost:8080 route dns agenticai your-domain.com

# Install service
agenticai service install --webhook-url https://your-domain.com

Option 3: Deploy to cloud Deploy to a server with a public IP and use that URL directly (no tunnel needed).

Tunnel Management

Stop Tunnel

Press Ctrl+C to stop the tunnel:

^C
Tunnel stopped.

Multiple Tunnels

You can run multiple tunnels to different ports:

# Terminal 1: Server on 8080
agenticai server --port 8080

# Terminal 2: Tunnel for 8080
agenticai tunnel start --port 8080

# Terminal 3: Another service on 3000
python -m http.server 3000

# Terminal 4: Tunnel for 3000
ngrok http 3000

Tunnel Logs

ngrok provides a web interface at http://127.0.0.1:4040 with:

Request inspector
Replay requests
Traffic logs
Connection status

Environment Variables

NGROK_URL

Set the webhook URL for quick access:

# Set once
export NGROK_URL=https://abc123.ngrok.io

# Use in commands (webhook-url is optional)
agenticai trigger --to +15551234567

Add to .env for persistence:

NGROK_URL=https://abc123.ngrok.io

AGENTICAI_WEBHOOK_URL

Alternative env var for services:

export AGENTICAI_WEBHOOK_URL=https://abc123.ngrok.io

Troubleshooting

ngrok Not Found

Error: ngrok not found. Solution:

# macOS
brew install ngrok

# Or download from https://ngrok.com/download

cloudflared Not Found

Error: cloudflared not found. Solution:

# macOS
brew install cloudflared

# Or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/

Tunnel Connection Refused

Error: Tunnel can’t connect to localhost:8080 Solution: Ensure server is running:

# Start server first
agenticai server

# Then start tunnel
agenticai tunnel start

Twilio Can’t Reach Webhook

Checklist:

✅ Tunnel is running
✅ Server is running
✅ Webhook URL uses HTTPS (not HTTP)
✅ URL is correct in Twilio Console
✅ Firewall allows connections

Test manually:

curl https://your-url.ngrok.io/health
# Should return: {"status":"ok"}

ngrok Session Expired

Error: Tunnel disconnected after 2 hours (free tier) Solutions:

Restart tunnel: agenticai tunnel start
Upgrade to ngrok paid plan for unlimited sessions
Use Cloudflare Tunnel (no timeout)

Security Notes

Tunnels expose your local server to the internet. Only expose what’s necessary.

Best practices:

Use tunnels only for Twilio webhooks
Don’t expose development databases
Use authentication for sensitive endpoints
Monitor tunnel traffic
Use paid tunnels for production (fixed URLs, better security)

Commands

Commands

agenticai tunnel start

Options

agenticai tunnel info

Tunnel Providers

ngrok (Default)

Cloudflare Tunnel

Examples

ngrok Tunnel

Cloudflare Tunnel

Development Workflow

Production Setup

Tunnel Management

Stop Tunnel

Multiple Tunnels

Tunnel Logs

Environment Variables

NGROK_URL

AGENTICAI_WEBHOOK_URL

Troubleshooting

ngrok Not Found

cloudflared Not Found

Tunnel Connection Refused

Twilio Can’t Reach Webhook

ngrok Session Expired

Security Notes

See Also

Build docs developers (and LLMs) love

Commands

Documentation Index

​Commands

​agenticai tunnel start

​Options

​agenticai tunnel info

​Tunnel Providers

​ngrok (Default)

​Cloudflare Tunnel

​Examples

​ngrok Tunnel

​Cloudflare Tunnel

​Development Workflow

​Production Setup

​Tunnel Management

​Stop Tunnel

​Multiple Tunnels

​Tunnel Logs

​Environment Variables

​NGROK_URL

​AGENTICAI_WEBHOOK_URL

​Troubleshooting

​ngrok Not Found

​cloudflared Not Found

​Tunnel Connection Refused

​Twilio Can’t Reach Webhook

​ngrok Session Expired

​Security Notes

​See Also

Build docs developers (and LLMs) love

Commands

agenticai tunnel start

Options

agenticai tunnel info

Tunnel Providers

ngrok (Default)

Cloudflare Tunnel

Examples

ngrok Tunnel

Cloudflare Tunnel

Development Workflow

Production Setup

Tunnel Management

Stop Tunnel

Multiple Tunnels

Tunnel Logs

Environment Variables

NGROK_URL

AGENTICAI_WEBHOOK_URL

Troubleshooting

ngrok Not Found

cloudflared Not Found

Tunnel Connection Refused

Twilio Can’t Reach Webhook

ngrok Session Expired

Security Notes

See Also