Pipecat Cloud is a managed platform for hosting and scaling Pipecat agents in production.

​
Prerequisites

Before you begin, you’ll need:

Quickstart Guide

Follow a step-by-step guided experience to deploy your first agent

​
Choosing a starting point

Pipecat Cloud offers several ways to get started:

  1. Use a starter template - Pre-built agent configurations for common use cases
  2. Build from the base image - Create a custom agent using the official base image
  3. Clone the starter project - A bare-bones project template to customize

​
Starter templates

Pipecat Cloud provides several ready-made templates for common agent types:

TemplateDescription
voiceVoice conversation agent with STT, LLM and TTS
twilioTelephony agent that works with Twilio
natural_conversationAgent focused on natural dialogue flow, allowing a user time to think
openai_realtimeAgent using OpenAI’s Realtime API
gemini_multimodal_liveMultimodal agent using Google’s Gemini Multimodal Live API
visionComputer vision agent that can analyze images

These templates include a functioning implementation and Dockerfile. You can use them directly:

# Clone the repository
git clone https://github.com/daily-co/pipecat-cloud-images.git

# Navigate to a starter template
cd pipecat-cloud-images/pipecat-starters/voice

# Customize the agent for your needs

​
Project structure

Whether using a starter template or building from scratch, a basic Pipecat Cloud project typically includes:

my-agent/
├── bot.py             # Your Pipecat pipeline
├── Dockerfile         # Container definition
├── requirements.txt   # Python dependencies
└── pcc-deploy.toml    # Deployment config (optional)

​
Agent implementation with bot.py

Your agent’s bot.py code must include a specific bot() function that serves as the entry point for Pipecat Cloud. This function has different signatures depending on the transport method:

​
For WebRTC/Daily transports

async def bot(args: DailySessionArguments):
    """Main bot entry point compatible with the FastAPI route handler.

    Args:
        config: The configuration object from the request body
        room_url: The Daily room URL
        token: The Daily room token
        session_id: The session ID for logging
    """
    logger.info(f"Bot process initialized {args.room_url} {args.token}")

    try:
        await main(args.room_url, args.token)
        logger.info("Bot process completed")
    except Exception as e:
        logger.exception(f"Error in bot process: {str(e)}")
        raise

​
For WebSocket transports (e.g., Twilio)

async def bot(args: WebSocketSessionArguments):
    """Main bot entry point for WebSocket connections.

    Args:
        ws: The WebSocket connection
        session_id: The session ID for logging
    """
    logger.info("WebSocket bot process initialized")

    try:
        await main(args.websocket)
        logger.info("WebSocket bot process completed")
    except Exception as e:
        logger.exception(f"Error in WebSocket bot process: {str(e)}")
        raise

Complete Example: Voice Bot

View a complete WebRTC voice bot implementation

Complete Example: Twilio Bot

View a complete Twilio WebSocket bot implementation

​
Example Dockerfile

Pipecat Cloud provides base images that include common dependencies for Pipecat agents:

FROM dailyco/pipecat-base:latest

COPY ./requirements.txt requirements.txt
RUN pip install --no-cache-dir --upgrade -r requirements.txt

COPY ./bot.py bot.py

This Dockerfile:

  1. Uses the official Pipecat base image
  2. Installs Python dependencies from requirements.txt
  3. Copies your bot.py file to the container

The base image (dailyco/pipecat-base) includes the HTTP API server, session management, and platform integration required to run on Pipecat Cloud. See the base image source code for details.

​
Building and pushing your Docker image

With your project structure in place, build and push your Docker image:

# Build the image
docker build --platform=linux/arm64 -t my-first-agent:latest .

# Tag the image for your repository
docker tag my-first-agent:latest your-username/my-first-agent:0.1

# Push the tagged image to the repository
docker push your-username/my-first-agent:0.1

Pipecat Cloud requires ARM64 images. Make sure to specify the --platform=linux/arm64 flag when building.

​
Managing secrets

Your agent likely requires API keys and other credentials. Create a secret set to store them securely:

# Create an .env file with your credentials
touch .env

# Create a secret set from the file
pcc secrets set my-first-agent-secrets --file .env

​
Deploying your agent

Deploy your agent with the CLI:

pcc deploy my-first-agent your-username/my-first-agent:0.1 --secret-set my-first-agent-secrets

For a more maintainable approach, create a pcc-deploy.toml file:

agent_name = "my-first-agent"
image = "your-username/my-first-agent:0.1"
secret_set = "my-first-agent-secrets"
image_credentials = "my-first-agent-image-credentials"  # For private repos

[scaling]
    min_instances = 0

Then deploy using:

pcc deploy

​
Starting a session

Once deployed, you can start a session with your agent:

# Create and set a public access key if needed
pcc organizations keys create
pcc organizations keys use

# Start a session using Daily for WebRTC
pcc agent start my-first-agent --use-daily

This will open a Daily room where you can interact with your agent.

​
Checking deployment status

Monitor your agent deployment:

# Check deployment status
pcc agent status my-first-agent

# View deployment logs
pcc agent logs my-first-agent

​
Next steps

Agent Images

Learn about containerizing your agent

Secrets

Managing sensitive information

Scaling

Configure scaling for production workloads

Active Sessions

Understand how sessions work