run

Pipecat development runner.

This development runner executes Pipecat bots and provides the supporting infrastructure they need - creating Daily rooms and tokens, managing WebRTC connections, and setting up telephony webhook/WebSocket infrastructure. It supports multiple transport types with a unified interface.

Install with:

pip install pipecat-ai[runner]

All bots must implement a bot(runner_args) async function as the entry point. The server automatically discovers and executes this function when connections are established.

By default the runner starts a single FastAPI server that supports WebRTC, Daily, and telephony transports simultaneously. Clients declare which transport they want via the transport field in the /start request body (default: "webrtc").

Single transport example:

async def bot(runner_args: RunnerArguments):
    transport = DailyTransport(
        runner_args.room_url,
        runner_args.token,
        "Bot",
        DailyParams(...)
    )
    # Your bot logic here
    await run_pipeline(transport)

if __name__ == "__main__":
    from pipecat.runner.run import main
    main()

Multiple transport example:

async def bot(runner_args: RunnerArguments):
    # Type-safe transport detection
    if isinstance(runner_args, DailyRunnerArguments):
        transport = setup_daily_transport(runner_args)  # Your application code
    elif isinstance(runner_args, SmallWebRTCRunnerArguments):
        transport = setup_webrtc_transport(runner_args)  # Your application code
    elif isinstance(runner_args, WebSocketRunnerArguments):
        transport = setup_telephony_transport(runner_args)  # Your application code

    # Your bot implementation
    await run_pipeline(transport)

Supported transports:

  • Daily - Creates rooms and tokens, runs bot as participant

  • WebRTC - Provides local WebRTC interface with prebuilt UI

  • Telephony - Handles webhook and WebSocket connections for Twilio, Telnyx, Plivo, Exotel

The /start endpoint accepts:

{
    "transport": "webrtc",        // "webrtc" | "daily" | "twilio" | "telnyx" |
                                  // "plivo" | "exotel" — default: "webrtc"

    // WebRTC-specific
    "enableDefaultIceServers": false,
    "body": {...},

    // Daily-specific
    "createDailyRoom": true,
    "dailyRoomProperties": {...},
    "dailyMeetingTokenProperties": {...},
    "body": {...}
}

To run locally:

  • All transports (default): python bot.py

  • WebRTC only: python bot.py -t webrtc

  • ESP32: python bot.py -t webrtc --esp32 --host 192.168.1.100

  • Daily only: python bot.py -t daily

  • Daily (direct, testing only): python bot.py -d

  • Telephony: python bot.py -t twilio -x your_username.ngrok.io

  • Exotel: python bot.py -t exotel (no proxy needed, but ngrok connection to HTTP 7860 is required)

  • WhatsApp: python bot.py --whatsapp

pipecat.runner.run.app: fastapi.FastAPI

The FastAPI application instance.

Import this to add custom routes from other packages before calling main():

from pipecat.runner.run import app, main

@app.get("/my-route")
async def my_route():
    return {"hello": "world"}

if __name__ == "__main__":
    main()
pipecat.runner.run.runner_downloads_folder() → str | None[source]

Returns the folder where files are stored for later download.

pipecat.runner.run.runner_host() → str[source]

Returns the host name of this runner.

pipecat.runner.run.runner_port() → int[source]

Returns the port of this runner.

pipecat.runner.run.main(parser: ArgumentParser | None = None)[source]

Start the Pipecat development runner.

Parses command-line arguments and starts a FastAPI server that supports WebRTC, Daily, and telephony transports simultaneously. Clients declare which transport to use via the transport field in the /start body.

When -t is provided, the server restricts /start to that transport only and displays transport-specific startup information.

The runner discovers and runs any bot(runner_args) function found in the calling module.

Command-line arguments:

  • –host: Server host address (default: localhost)

  • –port: Server port (default: 7860)

  • -t/–transport: Restrict to a single transport and set as default for /start (daily, webrtc, twilio, telnyx, plivo, exotel). Omit to support all transports.

  • -x/–proxy: Public proxy hostname for telephony webhooks

  • -d/–direct: Connect directly to Daily room (automatically sets transport to daily)

  • -f/–folder: Path to downloads folder

  • –dialin: Enable Daily PSTN dial-in webhook handling

  • –esp32: Enable SDP munging for ESP32 compatibility (requires –host with IP address)

  • –whatsapp: Ensure required WhatsApp environment variables are present

  • -v/–verbose: Increase logging verbosity

Parameters:

parser – Optional custom argument parser. If provided, default runner arguments are added to it so bots can define their own CLI arguments. Custom arguments should not conflict with the default ones. Custom args are accessible via runner_args.cli_args.