Quickstart

You are currently viewing the React version of this page. Use the dropdown to the right to customize this page for your client framework.

This quickstart guide will help you build your first Pipecat voice AI bot with a React front-end and run it locally. You’ll create a simple conversational agent that you connect and talk to in real-time via your browser.

The CLI generates React and vanilla JavaScript projects. For React Native, iOS, Android, or C++, see Building a Voice UI to get started without the CLI.

Prerequisites

Python 3.11+ and uv
Node.js 18+

Step 1: Scaffold your project

# Install the Pipecat CLI
uv tool install "pipecat-ai[cli]"

# Start your project
pipecat init

When init asks how you want to build, choose Scaffold a runnable bot now. The wizard will guide you through the setup. Choose the following options:

This quickstart uses the interactive pipecat init wizard so you end up with the same project this guide walks through below. When you’re ready to build your own bot, we recommend driving development with a coding agent — see Build Your Next Bot.

Project name: my-voice-app
Bot type: Web/Mobile
Client framework: React
React dev server: Vite
Transport: SmallWebRTC

The rest is up to you! The CLI generates a complete project with two main directories:

bot/ — a Python Pipecat bot
client/ — a React front-end built on the Voice UI Kit

Step 2: Start the bot

cd my-voice-app/bot
cp .env.example .env       # add your API keys
uv sync
uv run bot.py

The bot starts at http://localhost:7860.

Step 3: Start the client

cd ../client
npm install
npm run dev

Open http://localhost:5173, click Connect, allow microphone access, and start talking.

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.

Understanding the Quickstart Client

The React app is built on the Voice UI Kit — Pipecat’s library of pre-built voice UI components. Here’s what each file does:src/config.ts — transport configuration. By default it uses SmallWebRTC for local development. To switch to Daily for production, add your Daily credentials and update AVAILABLE_TRANSPORTS.

const botStartUrl =
  import.meta.env.VITE_BOT_START_URL || "http://localhost:7860/start";

export const DEFAULT_TRANSPORT: TransportType = "smallwebrtc";

src/main.tsx — entry point. PipecatAppBase handles transport creation, connection lifecycle, loading states, and errors, passing a ready client down to your app via a render prop.

<PipecatAppBase connectParams={connectParams} transportType={transportType}>
  {({ client, handleConnect, handleDisconnect, error }) =>
    !client ? <SpinLoader /> :
    error ? <ErrorCard>{error}</ErrorCard> :
    <App client={client} handleConnect={handleConnect} ... />
  }
</PipecatAppBase>

src/components/App.tsx — the UI. Built entirely from Voice UI Kit components:

Component	What it does
`ConnectButton`	Connect/disconnect button with built-in loading and error states
`UserAudioControl`	Mic mute/unmute toggle
`ConversationPanel`	Live transcript of the conversation
`EventsPanel`	Real-time stream of RTVI events — useful during development

Deploying to production

The .env.example file shows the production configuration. Point VITE_BOT_START_URL at your deployed bot’s start endpoint:

# Pipecat Cloud
VITE_BOT_START_URL="https://api.pipecat.daily.co/v1/public/{agentName}/start"
VITE_BOT_START_PUBLIC_API_KEY="your-public-api-key"

The client app is a static site — build it with npm run build and deploy to any static hosting provider (Vercel, Netlify, S3, etc.).

Next steps

Voice UI Kit

Customize themes, swap components, and extend the generated UI

Building a Voice UI

Build a React voice app from scratch — understand the SDK without abstractions

Core Concepts

Understand transports, sessions, events, and media

Deploy your bot

Deploy to Pipecat Cloud for production

Get Started

Core Concepts

Guides

Voice UI Kit

Prerequisites

Step 1: Scaffold your project

Step 2: Start the bot

Step 3: Start the client

Understanding the Quickstart Client

Deploying to production

Next steps

Voice UI Kit

Building a Voice UI

Core Concepts

Deploy your bot

​Prerequisites

​Step 1: Scaffold your project

​Step 2: Start the bot

​Step 3: Start the client

​Understanding the Quickstart Client

​Deploying to production

​Next steps

Voice UI Kit

Building a Voice UI

Core Concepts

Deploy your bot

Prerequisites

Step 1: Scaffold your project

Step 2: Start the bot

Step 3: Start the client

Understanding the Quickstart Client

Deploying to production

Next steps