Skip to main content
Starts the FastAPI webhook server that handles incoming Twilio calls and media streams.

​
Usage

agenticai server [OPTIONS]

​
Options

​
--host
string
default:"0.0.0.0"
Server host to bind toShort form: -hDefault: Loaded from config.yaml (server.host), typically 0.0.0.0Example:
agenticai server --host 127.0.0.1
​
--port
integer
default:"8080"
Server port to listen onShort form: -pDefault: Loaded from config.yaml (server.port), typically 8080Example:
agenticai server --port 3000
​
--config
string
default:"config.yaml"
Path to configuration fileShort form: -cGlobal option - Applies to all commandsExample:
agenticai --config custom.yaml server

​
What It Does

The server command:
  1. Loads configuration from config.yaml and .env
  2. Starts a FastAPI application with:
    • Twilio webhook endpoints (/twilio/voice, /twilio/stream)
    • Health check endpoint (/health)
    • Call API endpoint (/api/call)
  3. Initializes the CallManager for handling phone calls
  4. Sets up WebSocket connections for Twilio Media Streams
  5. Runs indefinitely until stopped (Ctrl+C)

​
Endpoints

When the server starts, the following endpoints are available:

​
Voice Webhook

POST /twilio/voice
Handles incoming calls from Twilio. Returns TwiML to establish media stream.

​
Media Stream WebSocket

WS /twilio/stream
Bidirectional WebSocket for real-time audio streaming between Twilio and OpenAI Realtime API.

​
Call API

POST /api/call
Trigger outbound calls programmatically (used by agenticai trigger).

​
Health Check

GET /health
Returns 200 OK if server is running.

​
Examples

​
Basic Usage

Start the server with default settings: 
agenticai server
Output: 
Starting server on 0.0.0.0:8080
Webhook path: /twilio/voice
WebSocket path: /twilio/stream
INFO:     Started server process [12345]
INFO:     Uvicorn running on http://0.0.0.0:8080

​
Custom Port

Run on a different port: 
agenticai server --port 3000

​
Localhost Only

Bind to localhost for development: 
agenticai server --host 127.0.0.1 --port 8080

​
Custom Configuration

Use a different config file: 
agenticai --config production.yaml server

​
Development Workflow

Typical development setup: 
# Terminal 1: Start the server
agenticai server

# Terminal 2: Start ngrok tunnel
ngrok http 8080
# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)

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

​
Production Notes

The server command runs in the foreground and will stop when the terminal closes. For production use:

​
Daemon Mode

For running the server with the scheduler enabled: 
agenticai daemon --webhook-url https://your-permanent-url.com
This runs the server plus the call scheduler for automated calls.

​
Daemon Options

​
--webhook-url
string
required
Public webhook base URL for Twilio callbacksShort form: -wExample:
agenticai daemon --webhook-url https://your-url.ngrok.io
Example Output: 
Starting Agentic AI in daemon mode
Scheduler started
  morning-reminders: 2026-03-04 09:00:00
  afternoon-followup: 2026-03-04 14:00:00
INFO:     Uvicorn running on http://0.0.0.0:8080

​
Logs

The server logs all events using structlog:
  • Request handling
  • WebSocket connections
  • Call lifecycle events
  • Audio stream status
  • Gateway messages
Example log output: 
2026-03-03T10:30:45 [info     ] Incoming call from +15551234567 call_id=CA123...
2026-03-03T10:30:46 [info     ] WebSocket connected           stream_sid=ST456...
2026-03-03T10:30:47 [info     ] OpenAI Realtime session started
2026-03-03T10:31:15 [info     ] Call completed                duration=28s

​
Configuration

The server uses these config values: 
server:
  host: "0.0.0.0"        # Overridden by --host
  port: 8080             # Overridden by --port
  webhook_path: "/twilio/voice"
  websocket_path: "/twilio/stream"

twilio:
  account_sid: ${TWILIO_ACCOUNT_SID}
  auth_token: ${TWILIO_AUTH_TOKEN}
  from_number: ${TWILIO_PHONE_NUMBER}

openai_realtime:
  api_key: ${OPENAI_API_KEY}
  model: "gpt-4o-realtime-preview-2024-12-17"
  voice: "alloy"

​
Troubleshooting

​
Server won’t start

Error: Address already in use Solution: Port 8080 is already in use. Either stop the other process or use a different port: 
agenticai server --port 3000

​
Configuration not found

Error: Configuration file not found. Create config.yaml first. Solution: Create config.yaml or run the setup wizard: 
agenticai setup

​
Twilio webhooks failing

Checklist:
  1. Server is running and accessible
  2. ngrok/tunnel is active
  3. Twilio webhook URL is set to https://your-url.ngrok.io/twilio/voice
  4. Firewall allows incoming connections on port 8080

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us