Quickstart

Prerequisites

System requirements

Python 3.10+
Linux, MacOS, or Windows Subsystem for Linux (WSL)
Docker installed on your system
Access to a container registry (e.g., Docker Hub, GitHub Container Registry, etc.)

Install Docker

Docker Desktop is recommended for development environments as it provides a comprehensive GUI and tools.

macOS

Windows

Linux

Set up a container registry

Create a Docker Hub account

If you don’t already have a Docker Hub account, create one for free.

While other container registries will work, this guide uses Docker Hub in its examples.

After creating your account, log in via your terminal:

docker login

Learn about different Docker login options in the official documentation.

No repository creation needed yet

Unlike some services, with Docker Hub you don’t need to create a repository in advance.When you push your first image later in this guide, a repository will be automatically created with the name you specify.

Take note of your Docker Hub username - you’ll need it when pushing your agent image in later steps.

Create service accounts

The Pipecat Cloud starter agent uses OpenAI for LLM inference and Cartesia for text-to-speech. You will need API keys for both services.

Create your starter project

A bare-bones voice AI agent template is available to help you get started. You’ll need to set up your Python environment and authenticate with Pipecat Cloud before initializing the starter project. First, create a new directory for your project:

mkdir pipecat-cloud-starter && cd pipecat-cloud-starter

Configure your Python environment

We recommend using a virtual environment to isolate your project dependencies:

Using uv (recommended)

uv is a fast, modern Python package installer and environment manager.

# Install uv
pip install uv

# Create a virtual environment
uv venv

# Activate the environment
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows

Can’t pip install uv? Follow the uv installation instructions instead.

Using venv (standard)

Python’s built-in venv module:

# Create a virtual environment
python -m venv .venv

# Activate the environment
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows

Set up Pipecat Cloud

Create a Pipecat Cloud account

Create an account at pipecat.daily.co.

You must have valid billing information associated with your account in order to deploy agents.

Install Pipecat Cloud CLI

With your environment activated, install the Pipecat Cloud CLI:

pip install pipecatcloud

The Pipecat Cloud CLI can be used with either pipecatcloud or pcc as the command prefix.

Authenticate

Run pcc auth login to authenticate via your browser (if this doesn’t work, try python -m pipecatcloud auth login.)

If you are working as part of a team, you can also create an organization and invite other Pipecat Cloud accounts to collaborate. See Accounts and Organizations for more information.

Initialize the starter project

Now, use the Pipecat Cloud CLI to download the starter template:

pcc init

This command downloads a template that includes everything you need to build and deploy your first voice AI agent.

The starter template comes from the pipecat-cloud-starter GitHub repository.

Project structure The starter project includes these key files:

bot.py: Python entry-point containing your Pipecat agent pipeline
Dockerfile: Dockerfile for building the agent container
requirements.txt: Python dependencies used by your agent code
pcc-deploy.toml: Pipecat Cloud deployment configuration file (optional)

Deploy the agent

Pipecat Cloud expects a built Docker image that includes the agent code and all dependencies.

Most agent images will extend from one of the Pipecat Cloud base images. These images include key dependencies and configurations that ensure your agent will run correctly, efficiently and securely. You can browse the base images on Docker Hub.

For more information about how to containerize your agent code, see Agent Images.

Build and push your Docker image

Build your Docker image From within your project directory, run Docker build:

docker build --platform=linux/arm64 -t my-first-agent:latest .

This command builds a Docker image named my-first-agent with the tag latest from the current directory.

The --platform=linux/arm64 flag is required as Pipecat Cloud runs on ARM64 architecture.

Tag your Docker image Using the Docker image you just built, tag it with your Docker Hub username and a version number. The tag should be [your-username]/[image-name]:[version-number].

docker tag my-first-agent:latest your-username/my-first-agent:0.1

Push your Docker image After tagging your image, you can push it to your Docker Hub registry:

docker push your-username/my-first-agent:0.1

While in beta, Pipecat Cloud requires that your agent image is pushed to your own repository, such as Docker Hub. Both public and private repositories are supported.

Add secrets

Secrets are a secure way to manage sensitive information such as API keys, passwords, and other credentials. The starter project requires the following API keys:

OpenAI API key
Cartesia API key
Daily API key (automatically provided through your Pipecat Cloud account)

Pipecat Cloud organizes your secrets into secret sets. This allows you to re-use the same set of secrets across multiple agents within your organization. Creating a secret set from a file (recommended) The starter project includes an env.example file that you can use as a template. Create a copy of this file and add your actual API keys:

# Copy the example file
cp env.example .env

# Edit the file with your API keys
# CARTESIA_API_KEY=your_cartesia_key
# OPENAI_API_KEY=your_openai_key

Then, create a secret set from this file:

pcc secrets set my-first-agent-secrets --file .env

Alternative: Creating secrets directly via CLI

For more information on managing secrets, see Secrets.

Create a deployment

The CLI deploy command requires three key pieces of information:

The name of your agent on Pipecat Cloud
The repository and tag of your Docker image
The secrets set to use for environment variables

Let’s deploy the agent using your pushed image:

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

When you run this command, you’ll be asked to confirm your deployment configuration before proceeding.

The starter project includes a pcc-deploy.toml file that already has the agent name, image reference, and secret set configured. If you’re using this file, you can simply run pcc deploy without additional arguments.See the Deployments section to learn more.

Using credentials for private repositories

If your repository is private you can provide the deploy command access credentials by specifying image pull secrets via the --credentials flag:

# Create an image pull secret (you'll be prompted for credentials)
pcc secrets image-pull-secret pull-secret https://index.docker.io/v1/

# Then use it in your deployment
pcc deploy my-first-agent your-username/my-first-agent:0.1 --credentials pull-secret

Learn more about Image Pull Secrets including how to create them for Docker Hub.

For more deployment configuration options, see the deploy reference docs.

Check the status of your deployment

Assuming the deployment was successful, you can check the status of your agent using the CLI:

# Deployment status
pcc agent status my-first-agent

# List deployment history
pcc agent deployments my-first-agent

Scale the deployment

Right now, your deployment has been made with the default runtime configuration. This means that your agent defaults to “scale-to-zero”, with no minimum agent instances to serve on-demand session requests. If you were to attempt to connect with your agent now, it’s likely you’d encounter a cold start while the agent spins up. Cold starts typically take around 10 seconds. To avoid this, you can scale your deployment to a minimum of one instance:

pcc deploy my-first-agent your-username/my-first-agent:0.1 --min-agents 1

This will provide you with one warm instance ready to serve any active sessions.

By default, idle agent instances are maintained for 5 minutes before being terminated when using scale-to-zero. For more information, see Scaling.

Setting --min-agents to 1 or greater will incur charges even when the agent is not in use.

Start an active session

Now that your agent has been deployed, you can start an active session to interact with it. Creating active sessions requires passing a valid API key for your namespace or organization. This is used to authenticate the request and prevent unauthorized access.

Create a public access key

pcc organizations keys create

Running this command will ask if you’d like to set this key as your default. Doing so will associate the created key with your current namespace, allowing you to omit the --api-key flag in future requests. Next set the key to be used with your agent:

pcc organizations keys use

When prompted, select your agent from the list.

Talk to your agent

The starter project is configured to use Daily as a WebRTC transport. Pipecat Cloud has a direct integration with Daily, meaning you are issued a Daily API key when you create an account.

pcc agent start my-first-agent --use-daily

This command will start a new active session with your agent. Since you are using Daily, you will be given a URL in the terminal to open in your browser. This will open a new tab where you can interact with your agent.

When using the Daily key associated with your Pipecat Cloud account, your Daily voice minutes for one human and one bot are free.Additional charges apply for features like recording, transcription, and PSTN/SIP. See Daily’s pricing page for more information.

Alternative ways to start a session

In addition to the CLI approach shown above, you can start sessions programmatically:

Use the REST API

curl --location --request POST 'https://api.pipecat.daily.co/v1/public/my-first-agent/start' \
  --header 'Authorization: Bearer YOUR_PUBLIC_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "createDailyRoom": true,
    "body": {"custom": "data"}
  }'

Use the Python SDK

import asyncio

from pipecatcloud.exception import AgentStartError
from pipecatcloud.session import Session, SessionParams


async def main():
    try:
        # Create session object
        session = Session(
            agent_name="my-first-agent",
            api_key=API_KEY,  # Replace with your actual API key
            params=SessionParams(
                use_daily=True,  # Optional: Creates a Daily room
                daily_room_properties={"start_video_off": False},
                data={"key": "value"},
            ),
        )

        # Start the session
        response = await session.start()

        # Get Daily room URL
        daily_url = f"{response['dailyRoom']}?t={response['dailyToken']}"
        print(f"Join Daily room: {daily_url}")

except AgentStartError as e:
        print(f"Error starting agent: {e}")
    except Exception as e:
        print(f"Unexpected error: {e}")


# Run the async function
if __name__ == "__main__":
    asyncio.run(main())

These approaches are particularly useful when integrating agent sessions into your own applications, such as web interfaces or backend services.

For more information on starting sessions, see Active Sessions.

Monitor and Troubleshoot

Once your agent is deployed, you can use the following commands to monitor its status and troubleshoot any issues:

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

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

These commands provide visibility into your agent’s operation and can help diagnose problems if your agent isn’t functioning as expected.

Next Steps

Congratulations! You have successfully deployed your first agent to Pipecat Cloud. As a next step, we recommend exploring how you can make your deployment production ready. See Scaling for more information on scaling your deployment.

Deploying your bot

Pipecat Cloud

Pipecat Cloud: REST Reference

Pipecat Cloud: CLI Reference

Pipecat Cloud: SDK Reference

Prerequisites

System requirements

Install Docker

Set up a container registry

Create service accounts

Create your starter project

Configure your Python environment

Set up Pipecat Cloud

Initialize the starter project

Deploy the agent

Build and push your Docker image

Add secrets

Create a deployment

Check the status of your deployment

Scale the deployment

Start an active session

Create a public access key

Talk to your agent

Use the REST API

Use the Python SDK

Monitor and Troubleshoot

Next Steps

Deploying your bot

Pipecat Cloud

Pipecat Cloud: REST Reference

Pipecat Cloud: CLI Reference

Pipecat Cloud: SDK Reference

​Prerequisites

​System requirements

​Install Docker

​Set up a container registry

​Create service accounts

​Create your starter project

​Configure your Python environment

​Set up Pipecat Cloud

​Initialize the starter project

​Deploy the agent

​Build and push your Docker image

​Add secrets

​Create a deployment

​Check the status of your deployment

​Scale the deployment

​Start an active session

​Create a public access key

​Talk to your agent

​Monitor and Troubleshoot

​Next Steps

Prerequisites

System requirements

Install Docker

Set up a container registry

Create service accounts

Create your starter project

Configure your Python environment

Set up Pipecat Cloud

Initialize the starter project

Deploy the agent

Build and push your Docker image

Add secrets

Create a deployment

Check the status of your deployment

Scale the deployment

Start an active session

Create a public access key

Talk to your agent

Monitor and Troubleshoot

Next Steps