Skip to main content
Pipecat Cloud Build lets you deploy agents directly from your source code. Instead of building Docker images locally and pushing them to a registry, just run pipecat cloud deploy and the CLI handles everything.

​
Prerequisites

  • A Pipecat Cloud account with an active organization
  • The Pipecat CLI installed and authenticated (pipecat cloud auth login)
  • A Python project using uv, pip, or poetry

​
Quick start

  1. Create a pcc-deploy.toml in your project root:
agent_name = "my-agent"
secret_set = "my-secrets"
  1. Deploy your agent:
pipecat cloud deploy
The CLI will:
  • Create a build context from your project files
  • Upload and build your agent image in the cloud
  • Deploy the resulting image

​
Dockerfile requirement

Your project must include a Dockerfile. If you don’t have one, see the pipecat-quickstart project for a reference, or use pipecat cloud init to scaffold a new project.

​
How it works

When you deploy without specifying an image, the CLI runs the following flow:
  1. Dockerfile check — Verifies a Dockerfile exists in your build context directory.
  2. Build context — Creates a deterministic tarball of your project files, excluding common non-essential files (.git, .env, __pycache__, .venv, etc.). If a .dockerignore file exists, it is used for exclusions instead.
  3. Cache check — Computes a content hash of your build context and checks if an identical build already exists. If so, the existing build is reused instantly.
  4. Upload & build — Uploads the context to cloud storage and triggers a build.
  5. Deploy — Once the build succeeds, deploys using the resulting image.

​
Build caching

Cloud builds use deterministic content hashing to enable caching. When you deploy, the CLI:
  1. Collects all files in your build context (respecting exclusions)
  2. Creates a tarball with deterministic ordering and metadata
  3. Computes a hash of the tarball contents
If a successful build with the same hash already exists, the CLI skips the upload and build entirely and reuses the cached build. This means repeated deployments of unchanged code are nearly instant.

​
Exclusion patterns

The following patterns are excluded from the build context by default:
  • Version control: .git, .gitignore, .gitattributes
  • Python: __pycache__, .venv, venv, *.pyc, *.pyo, *.pyd, *.so, *.egg-info
  • Environment and secrets: .env, .env.*, *.pem, *.key
  • Testing: .pytest_cache, .coverage, htmlcov, .tox, .nox
  • Type checking / linting: .mypy_cache, .ruff_cache
  • IDE: .vscode, .idea, *.swp, *.swo
  • OS: .DS_Store, Thumbs.db
  • Build artifacts: node_modules, dist, build
  • Misc: *.log
You can add custom exclusion patterns in your pcc-deploy.toml: 
[build.exclude]
patterns = ["*.md", "tests/", "docs/", "data/"]

​
CI/CD usage

Use the --yes flag to skip all confirmation prompts, making cloud builds suitable for automated pipelines: 
pipecat cloud deploy --yes
In CI/CD mode, the CLI will:
  • Automatically trigger a cloud build if no image is specified
  • Fail with an error if no Dockerfile is found in the build context

​
GitHub Actions example

- name: Deploy to Pipecat Cloud
  run: pipecat cloud deploy --yes
  env:
    PIPECAT_CLOUD_API_KEY: ${{ secrets.PIPECAT_CLOUD_API_KEY }}
For more comprehensive CI/CD setup including image tagging and monorepo support, see the CI with GitHub Actions guide.

​
Build management

Monitor and manage your builds using the pipecat cloud build commands: 
# List recent builds
pipecat cloud build list

# Check build status
pipecat cloud build status <build-id>

# View build logs
pipecat cloud build logs <build-id>

​
Redeploying a previous build

If you need to redeploy a previously built image, use --build-id to skip the build step: 
pipecat cloud deploy --build-id <build-id>
You can also set this in pcc-deploy.toml: 
agent_name = "my-agent"
build_id = "abc12345-6789-0abc-def0-123456789abc"

​
Configuration reference

All cloud build settings in pcc-deploy.toml: 
agent_name = "my-agent"
secret_set = "my-secrets"

[build]
context_dir = "."           # Build context directory (default: ".")
dockerfile = "Dockerfile"   # Dockerfile path (default: "Dockerfile")

[build.exclude]
patterns = ["*.md", "tests/"]  # Additional exclusion patterns
See the deploy command reference for the full list of configuration options.

​
Next steps

Agent Images

Learn about base images, project structure, and custom Dockerfiles.

CI with GitHub Actions

Set up automated deployments with GitHub Actions.

Container Registries

Use your own container registry for advanced image management.

Build CLI Reference

Full reference for build management commands.