Pipecat Cloud agents are designed to be run from containerized images. This allows you to run the agent in a controlled environment, with all the dependencies and configurations needed.

Your project defines the environment that your agent will run using Docker and built using a Dockerfile in the root directory of the project.

For example, your Dockerfile might look like this:

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

​
Using an official base image

Pipecat Cloud provides a series of base images that we recommend for most use-cases. Base images provide:

  • Simplified development and deployment
  • Optimizations for performance and security
  • Pre-installed system dependencies for most multi-modal agent use-cases

Using a base image reduces complexity in your project but requires you to adhere to a specific project structure.

  • Your project must contain a bot.py file that defines the agent pipeline
  • The bot.py must contain a bot() method that is the entry point for your agent pipeline
  • The bot() method must be asynchronous, e.g. async def bot():

You do not need to specify a CMD as part of your Dockerfile - the base image is configured to run your bot.py module.

You can browse available base images in the Pipecat Cloud Docker Hub .

​
Available base images

NameDescription
dailyco/pipecat-baseMulti-modal Pipecat optimized, suitable for most use-case
dailyco/pipecat-starters-voiceBasic voice bot with Deepgram STT, OpenAI LLM, and Cartesia TTS services
dailyco/pipecat-starters-twilioBasic voice bot using Twilio websockets
dailyco/pipecat-starters-gemini_multimodal_liveVoice bot using Google’s Gemini Multimodal Live with integrated audio, video, and speech processing
dailyco/pipecat-starters-natural_conversationVoice bot with dual-LLM architecture for natural conversation flow and utterance detection
dailyco/pipecat-starters-openai_realtimeVoice bot using OpenAI’s Realtime Beta API with integrated audio streaming, STT, LLM, and TTS
dailyco/pipecat-starters-visionVoice and vision bot with camera analysis capabilities using Anthropic Claude and custom image tools

​
Using a custom image

For more complex use-cases, you can use a custom image.

When doing so, we recommend following best practices to ensure your agent instance runs optimally on the platform.

Our base image is open source and serves as a useful blueprint for configuring your custom agent image.

​
Agent image structure

Custom agent images are for advanced use cases. For most teams, we recommend using our base images. If needed, consult the base image code as a reference.

For unsupported use cases, contact us at help@daily.co or via Discord.

Pipecat Cloud agent images must adhere to a specific structure to run on the platform. Our base images abstract away much of this complexity, but if you are building a custom image, you must ensure your agent adheres to the following:

  • HTTP API that can handle requests from the platform to configure and run agent instances.
  • The necessary system level dependencies (such as Python.)

In order to start an instance of your custom agent, you must expose a HTTP POST /bot route that will be called by the platform.

We recommend using FastAPI to create this route. Please refer to the base image code for an example of how to do this.

​
Building the image

While in beta, Pipecat Cloud requires all images to be built to target Linux on ARM. This is the most common platform for cloud deployments.

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

Your agent image should include:

  • All dependencies required for your agent to run.
  • Assets (such as images or models) available in the container filesystem
  • The entry point for your agent (usually a Python script)
  • Additional system dependencies (if required)

​
Best practices

  • Keep your image as small as possible. Use multi-stage builds to reduce the size of the final image.
  • Use a .dockerignore file to exclude unnecessary files from the image.
  • Pipecat Cloud will automatically restart your agent if it crashes. Ensure your agent can handle this gracefully.
  • Use Secrets to securely store sensitive information in your agent image.
  • To optimize for fast start-ups, avoid long running or blocking processes during initialization.
Accounts and OrganizationsDeployments