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

# Cloud Builds

> Build and deploy agents without managing a container registry

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](/pipecat-cloud/fundamentals/accounts-and-organizations) with an active organization
* The [Pipecat CLI](/api-reference/cli/overview) 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:

```toml theme={null}
agent_name = "my-agent"
secret_set = "my-secrets"
```

2. Deploy your agent:

```shell theme={null}
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, use `pipecat init` to scaffold a new project with a Dockerfile included.

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

```toml theme={null}
[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:

```shell theme={null}
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

```yaml theme={null}
- name: Deploy to Pipecat Cloud
  run: pipecat cloud deploy --yes
  env:
    PIPECAT_CLOUD_API_KEY: ${{ secrets.PIPECAT_CLOUD_API_KEY }}
```

<Note>
  For more comprehensive CI/CD setup including image tagging and monorepo support, see the [CI with GitHub Actions](/pipecat-cloud/guides/ci-with-github-actions) guide.
</Note>

## Build management

Monitor and manage your builds using the [`pipecat cloud build`](/api-reference/cli/cloud/build) commands:

```shell theme={null}
# 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:

```shell theme={null}
pipecat cloud deploy --build-id <build-id>
```

You can also set this in `pcc-deploy.toml`:

```toml theme={null}
agent_name = "my-agent"
build_id = "abc12345-6789-0abc-def0-123456789abc"
```

## Configuration reference

All cloud build settings in `pcc-deploy.toml`:

```toml theme={null}
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](/api-reference/cli/cloud/deploy#configuration-file-pcc-deploytoml) for the full list of configuration options.

## Next steps

<CardGroup cols={2}>
  <Card title="Agent Images" icon="docker" href="/pipecat-cloud/fundamentals/agent-images">
    Learn about base images, project structure, and custom Dockerfiles.
  </Card>

  <Card title="CI with GitHub Actions" icon="github" href="/pipecat-cloud/guides/ci-with-github-actions">
    Set up automated deployments with GitHub Actions.
  </Card>

  <Card title="Container Registries" icon="warehouse" href="/pipecat-cloud/guides/container-registries/overview">
    Use your own container registry for advanced image management.
  </Card>

  <Card title="Build CLI Reference" icon="terminal" href="/api-reference/cli/cloud/build">
    Full reference for build management commands.
  </Card>
</CardGroup>