> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Run your first Pipecat bot in under 5 minutes
This quickstart guide will help you build and deploy your first Pipecat voice AI bot. You'll create a simple conversational agent that you can talk to in real-time, then deploy it to production on Pipecat Cloud.
**Two steps**: Local Development (5 min) β Production Deployment (5 min)
## Step 1: Local Development
### Prerequisites
**Environment**
* Python 3.11 or later
* [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager installed
Adding Pipecat to an existing project instead of scaffolding a new one? See
[Installation](/pipecat/get-started/introduction#installation) for manual
setup.
**AI Service API Keys**
This quickstart uses three AI services working together in a pipeline. You'll need API keys from each service:
Create an account and generate your API key for real-time
speech recognition.
Create an account and generate an API key for intelligent conversation
responses.
Sign up and generate your API key for natural voice
synthesis.
Have these API keys ready. You'll add them to your environment file in the next section.
### Setup
1. Install the Pipecat CLI and scaffold the quickstart project
```bash theme={null}
# Install the Pipecat CLI
uv tool install pipecat-ai-cli
# Scaffold the quickstart project
pipecat init quickstart
# Change to the project directory
cd pipecat-quickstart
```
2. Configure your API keys
Create your environment file:
```bash theme={null}
cp env.example .env
```
Open the `.env` file in your text editor and add your API keys:
```ini theme={null}
DEEPGRAM_API_KEY=your_deepgram_api_key
OPENAI_API_KEY=your_openai_api_key
CARTESIA_API_KEY=your_cartesia_api_key
```
3. Set up virtual environment and install dependencies
```bash theme={null}
uv sync
```
### Run your bot locally
Now you're ready to run your bot! Start it with
```bash theme={null}
uv run bot.py
```
You should see output similar to this:
```
π WebRTC server starting at http://localhost:7860/client
Open this URL in your browser to connect!
```
Open [http://localhost:7860/client](http://localhost:7860/client) in your browser and click **Connect** to start talking to your bot.
**First run note**: The initial startup may take \~20 seconds as Pipecat
downloads required models and imports. Subsequent runs will be much faster.
π **Success!** Your bot is running locally. Now let's deploy it to production so others can use it.
***
## Step 2: Deploy to Production
Transform your local bot into a production-ready service. Pipecat Cloud handles scaling, monitoring, and global deployment.
### Prerequisites
1. Sign up for Pipecat Cloud
[Create your Pipecat Cloud account](https://pipecat.daily.co/sign-up) to deploy and manage your bots.
2. Pipecat CLI
Log in to Pipecat Cloud using the CLI to get started:
```bash theme={null}
pipecat cloud auth login
```
Select `Allow` to authenticate your CLI session in the browser page that opens.
### Your deployment configuration
The `pcc-deploy.toml` file tells Pipecat Cloud how to build and deploy your bot:
```toml theme={null}
agent_name = "pipecat-quickstart"
secret_set = "pipecat-quickstart-secrets"
[scaling]
min_agents = 1
```
**Understanding the configuration:**
* `agent_name`: Your bot's name in Pipecat Cloud
* `secret_set`: Where your API keys are stored securely
* `min_agents`: Number of bot instances to keep ready (1 = instant start)
### Configure secrets
Upload your API keys to Pipecat Cloud's secure storage:
```bash theme={null}
pipecat cloud secrets set pipecat-quickstart-secrets --file .env
```
This creates a secret set called `pipecat-quickstart-secrets` (matching your TOML file) and uploads all your API keys from `.env`.
### Build and Deploy
Build and deploy your bot to Pipecat Cloud:
```bash theme={null}
pipecat cloud deploy
```
The CLI automatically builds your image using the pcc-deploy.toml file and Dockerfile in your project and deploys it to Pipecat Cloud β no container registry needed.
Want to use your own container registry? See the [container registries
guide](/pipecat-cloud/guides/container-registries/overview) for advanced
deployment options.
### Connect to your agent
1. Open your [Pipecat Cloud dashboard](https://pipecat.daily.co/)
2. Select your `pipecat-quickstart` agent β **Sandbox**
3. Allow microphone access and click **Connect**
π **Your bot is now live in production!**
Explore advanced Pipecat Cloud features like scaling, monitoring, secrets
management, and production best practices.
***
## Understanding the Quickstart Bot
Let's walk through the generated `bot.py` to understand what's happening. When you speak to your bot, here's the real-time pipeline that processes your conversation:
1. **Audio Capture**: Your browser captures microphone audio and sends it via WebRTC
2. **Voice Activity Detection**: Silero VAD detects when you start and stop speaking
3. **Speech Recognition**: Deepgram converts your speech to text in real-time
4. **Language Processing**: OpenAI's GPT model generates an intelligent response
5. **Speech Synthesis**: Cartesia converts the response text back to natural speech
6. **Audio Playback**: The generated audio streams back to your browser
Each step happens with minimal latency, typically completing the full round-trip in under one second.
### AI Services
Your bot uses three AI services, each configured with API keys from your `.env` file:
```python theme={null}
# Create AI Services
stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))
tts = CartesiaTTSService(
api_key=os.getenv("CARTESIA_API_KEY"),
settings=CartesiaTTSService.Settings(
voice=os.getenv("CARTESIA_VOICE_ID", "71a7ad14-091c-4e8e-a314-022ece01c121"),
),
)
llm = OpenAIRealtimeLLMService(
api_key=os.getenv("OPENAI_API_KEY"),
settings=OpenAIRealtimeLLMService.Settings(
model=os.getenv("OPENAI_MODEL", "gpt-4.1"),
system_instruction="You are a helpful assistant.",
),
)
```
Pipecat supports many different AI services. You can swap out Deepgram for Soniox, OpenAI for Anthropic, or Cartesia for ElevenLabs without changing the rest of your code.
See the [supported services documentation](/api-reference/server/services/supported-services) for all available options.
### Context and Messages
Your bot maintains conversation history using a context object, enabling multi-turn interactions where the bot remembers what was said earlier.
The context is initialized and used to store the conversation history by the context aggregators:
```python theme={null}
context = LLMContext()
user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
context,
user_params=LLMUserAggregatorParams(
vad_analyzer=SileroVADAnalyzer(),
),
)
```
### RTVI Protocol
When building web or mobile clients, you can use [Pipecat's client SDKs](/client/introduction) that communicate with your bot via the [RTVI (Real-Time Voice Interaction) protocol](/client/rtvi-standard). Pipecat comes with RTVI enabled by default, allowing your the Pipecat server and client to exchange messages and events in real-time.
### Pipeline Configuration
The core of your bot is a Pipeline that processes data through a series of processors:
```python theme={null}
# Create the pipeline with the processors
pipeline = Pipeline([
transport.input(), # Receive audio from browser
stt, # Speech-to-text (Deepgram)
user_aggregator, # Add user message to context
llm, # Language model (OpenAI)
tts, # Text-to-speech (Cartesia)
transport.output(), # Send audio back to browser
assistant_aggregator, # Add bot response to context
])
```
Data flows through the pipeline as "frames", objects containing audio, text, or other data types. The ordering is crucial: audio must be transcribed before it can be processed by the LLM, and text must be synthesized before it can be played back.
The pipeline is managed by a PipelineTask:
```python theme={null}
# Create a PipelineTask to manage the pipeline execution
task = PipelineTask(
pipeline,
params=PipelineParams(
enable_metrics=True,
enable_usage_metrics=True,
),
)
```
The task handles pipeline execution, collects metrics, and manages RTVI events through [observers](/api-reference/server/utilities/observers/observer-pattern).
### Event Handlers
Event handlers manage the bot's lifecycle and user interactions:
```python theme={null}
# Event handler for when a client connects
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, client):
logger.info(f"Client connected")
# Add a greeting message to the context
context.add_message("developer", "Say hello and briefly introduce yourself.")
# Prompt the bot to start talking when the client connects
await task.queue_frames([LLMRunFrame()])
# Event handler for when a client disconnects
@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, client):
logger.info(f"Client disconnected")
# Cancel the task when the client disconnects
# This stops the pipeline and all processors, cleaning up resources
await task.cancel()
```
When a client connects, the bot adds a greeting instruction and queues a context frame to initiate the conversation. When disconnecting, it properly cancels the task to clean up resources.
### Running the Pipeline
Finally, the pipeline is executed by a PipelineRunner:
```python theme={null}
# Create a PipelineRunner to run the task
runner = PipelineRunner(handle_sigint=False)
# Finally, run the task using the runner
# This will start the pipeline and begin processing frames
await runner.run(task)
```
The runner manages the pipeline's execution lifecycle. Note that `handle_sigint=False` because the main runner handles system signals.
### Bot Entry Point
The quickstart uses Pipecat's runner system:
```python theme={null}
async def bot(runner_args: RunnerArguments):
"""Main bot entry point."""
# Configure transport parameters for different environments
transport_params = {
"daily": lambda: DailyParams(
audio_in_enabled=True,
audio_out_enabled=True,
),
"webrtc": lambda: TransportParams(
audio_in_enabled=True,
audio_out_enabled=True,
),
}
transport = await create_transport(runner_args, transport_params)
await run_bot(transport, runner_args)
if __name__ == "__main__":
from pipecat.runner.run import main
main()
```
This runner automatically handles WebRTC connection setup and management, making it easy to get started with minimal configuration. The same code works for both local development and production deployment.
**Production ready**: This bot pattern is fully compatible with Pipecat Cloud,
meaning you can deploy your bot without any code changes.
## Troubleshooting
* **Browser permissions**: Make sure to allow microphone access when prompted by your browser.
* **Connection issues**: If the WebRTC connection fails, first try a different browser. If that fails, make sure you don't have a VPN or firewall rules blocking traffic. WebRTC uses UDP to communicate.
* **Audio issues**: Check that your microphone and speakers are working and not muted.
## Next Steps
Congratulations! You've built and deployed your first Pipecat bot. Here's what to do next based on your goals:
### π Ready to Build Your Own Application?
The quickstart gave you a working example, but the Pipecat CLI helps you scaffold production-ready projects with your choice of platform (phone vs web/mobile), transport providers, and AI servicesβall tailored to your specific use case.
Use the CLI to scaffold phone or web/mobile projects customized for your needs
### π§ Want to Understand How It Works?
Dive deeper into Pipecat's architecture and learn how to build custom solutions.
Master pipelines, processors, transports, and context management
30+ production-ready examples for inspiration