# Pipecat Quickstart

Run your first Pipecat bot in under 5 minutes. This example creates a voice AI bot that you can talk to in your browser.

## Prerequisites

### Environment

- Python 3.10 or later
- [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager installed

### AI Service API keys

Pipecat orchestrates different AI services in a pipeline, ensuring low latency communication. In this quickstart example, we'll use:

- [Deepgram](https://console.deepgram.com/signup) for Speech-to-Text transcriptions
- [OpenAI](https://auth.openai.com/create-account) for LLM inference
- [Cartesia](https://play.cartesia.ai/sign-up) for Text-to-Speech audio generation

Have your API keys ready. We'll add them to your `.env` shortly.

## Setup

### Set up your environment and dependencies

From `examples/quickstart`, run:

```bash
uv sync --extra webrtc \
    --extra daily \
    --extra silero \
    --extra deepgram \
    --extra openai \
    --extra cartesia \
    --extra runner
```

### Configure environment variables

Create a `.env` file:

```bash
cp env.example .env
```

Then, add your API keys:

```ini
DEEPGRAM_API_KEY=your_deepgram_api_key
OPENAI_API_KEY=your_openai_api_key
CARTESIA_API_KEY=your_cartesia_api_key
```

## Run your bot locally

```bash
uv run bot.py
```

**Open http://localhost:7860 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.

## Deploy to Pipecat Cloud (Optional)

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

[Sign up](https://pipecat.daily.co/sign-up) for a Pipecat Cloud account and deploy your bot in minutes.

### Setup

#### Install `pipecatcloud`

The `pipecatcloud` CLI manages your Pipecat deployments, secrets, and organization. Install in your virtual enviroment:

```bash
uv add pipecatcloud
```

> 💡 Tip: You can run the `pipecatcloud` CLI using the `pcc` alias.

#### Docker

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

1. Install [Docker](https://www.docker.com/) on your system.
2. Create a container registry account. We'll use [Docker Hub](https://hub.docker.com/) in this example.

### Configure pcc-deploy.toml

The `pcc-deploy.toml` file is the spec for your Pipecat Cloud deployment.

```ini
agent_name = "quickstart"
image = "your_username/quickstart:0.1"
secret_set = "quickstart-secrets"

[scaling]
	min_agents = 1
```

Details:

- `agent_name`: the name of your Pipecat Cloud agent
- `image`: your Docker Hub username and image tag (image_name:version) to run
- `secret_set`: environment variable secrets that you can use in your bot file
- `min_agents`: the number of reserve instances you'll run. We'll start with 1 to ensure you get an instant start

> 💡 Tip: [Set up `image_credentials`](https://docs.pipecat.ai/deployment/pipecat-cloud/fundamentals/secrets#image-pull-secrets) in your TOML file for authenticated image pulls

### Configure secrets

Store your secrets in Pipecat Cloud and use the environment variable keys in your bot file. To create secrets, run:

```bash
uv run pcc secrets set quickstart-secrets --file .env
```

This command creates a new secret set called `quickstart-secrets`. This value must match the `secret_set` in your TOML file. The `--file` arg points your `.env` file. This will add all environment variables from the file to the secret set.

## Build and push your Docker image

Pipecat Cloud expects a built Docker image that includes the agent code and all dependencies. You can build, tag, and push your Docker image using the included `build.sh` shell script:

1. Login to Docker Hub:

   ```bash
   docker login
   ```

2. Update the `VERSION`, `DOCKER_USERNAME`, and `AGENT_NAME` to match your TOML file.
3. Run the script:

   ```bash
   ./build.sh
   ```

## Deploy your agent

You're ready to deploy your agent. Use the following command to deploy your agent according to the spec in your `pcc-deploy.toml` file:

```bash
uv run pcc deploy
```

## Connect to your agent

The Pipecat Cloud dashboard has a Sandbox which makes it easy to talk to your agent. In your [Pipecat Cloud dashboard](https://pipecat.daily.co/), select your `quickstart` agent > Sandbox.

- Accept the browser prompt for device access.
- Click `Connect` to start your agent.

## 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

- **Read the docs**: Check out [Pipecat's docs](https://docs.pipecat.ai/) for guides and reference information.
- **Join Discord**: Join [Pipecat's Discord server](https://discord.gg/pipecat) to get help and learn about what others are building.