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

# pipecat cloud deploy

> pipecat cloud deploy creates or updates a Pipecat Cloud agent deployment, building a deployment manifest from your options.

The `deploy` command creates a new agent deployment or updates an existing one. It builds a deployment manifest with the provided parameters and monitors the deployment status until the agent is ready.

When no image is specified, the CLI will offer to build your agent using [Pipecat Cloud Build](https://docs.pipecat.ai/pipecat-cloud/guides/cloud-builds.md). This handles building and deploying without requiring you to manage a container registry. A `Dockerfile` must be present in your build context directory.

If the agent name already exists, you'll be prompted to confirm the update. Use `--force` to skip this prompt and also force a new deployment even if the configuration hasn't changed (replacing all running pods).

This command will wait for the active deployment / revision to enter a ready state before returning. If the deployment fails, the command will exit with an [error](https://docs.pipecat.ai/pipecat-cloud/fundamentals/error-codes.md) with more information.

## Usage

```shell theme={null}
pipecat cloud deploy [ARGS] [OPTIONS]
```

**Arguments:**

**agent-name** `string`

Unique string identifier for the agent deployment. Must not contain spaces.
Defaults to `agent_name` in `pcc-deploy.toml`; the deploy exits 1 when neither
is set.

**image** `string`

URL of the Docker image to deploy. Must be a valid Docker image URL. For
example: `docker.io/my-repo/my-image:latest`. Not required when using [cloud
builds](https://docs.pipecat.ai/pipecat-cloud/guides/cloud-builds.md) or `--build-id`.

**Options:**

**--config-file** `string`

Path to an alternate deploy config file. Defaults to `pcc-deploy.toml` in the
current directory. Can also be set via the `PIPECAT_DEPLOY_CONFIG_PATH`
environment variable, with the flag taking precedence.

**--credentials / -c** `string`

Name of the image pull secret to use for accessing private repositories. The
secret must be previously created using the `pipecat cloud secrets
    image-pull-secret` command, and must be in the
[`ready`](https://docs.pipecat.ai/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
state at deploy time.

**--organization / -o** `string`

Organization to deploy the agent to. If not provided, uses the current
organization from your configuration.

**--secrets / -s** `string`

Name of the secret set to use for the deployment. The secret set must exist in
the specified organization and must be in the
[`ready`](https://docs.pipecat.ai/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
state — deploys that bind a `pending` or `failed` set are rejected.

**--min-agents / -min** `number` (default: 0)

Minimum number of agent instances to keep warm at all times. Default is 0,
which means the agent will scale down to zero when not in use. Setting this to
1 or higher avoids cold starts.

**--max-agents / -max** `number`

Maximum number of allowed agent instances, at least 1. Omitted, the value
isn't sent, so an existing agent keeps its current maximum. The default cap is
50; if you need more agents, please contact us at [help@daily.co](mailto:help@daily.co) or via
[Discord](https://discord.gg/dailyco).

**--krisp-viva-audio-filter** `string`

Enable Krisp VIVA noise cancellation with the specified audio filter model.
Valid values are:

* `tel`: Telephony model (up to 16kHz)
* `pro`: WebRTC model (up to 32kHz)

In addition to this flag, you also need to enable the `KrispVivaFilter()` for your transport. See the [Krisp VIVA](https://docs.pipecat.ai/api-reference/server/services/audio-filters/krisp-viva-filter.md) documentation for more information.

**--max-session-duration** `number` (default: 7200)

Maximum session duration in seconds. When a session reaches this limit, the
session is stopped: the bot is cancelled, with no opportunity for it to say
goodbye first. Valid range: `60` to `14400` (4 hours). Defaults to `7200` (2 hours) when unset.

See [Session duration limits](https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions.md#session-duration-limits)
for more information.

**--profile / -p** `string`

The agent profile to use for resource allocation: a platform profile
(`agent-1x`, `agent-2x`, `agent-3x`) or, in a self-hosted region, one your
organization defined with [`agent profiles
    create`](https://docs.pipecat.ai/api-reference/cli/cloud/project.md#profiles-create). Omitted, the CLI
sends no profile, so a new agent gets the platform default, `agent-1x`.

See [Agent Profiles](https://docs.pipecat.ai/pipecat-cloud/fundamentals/deploy.md#agent-profiles) for more information.

**--resources** `string`

Explicit sizing for agents in [self-hosted
regions](https://docs.pipecat.ai/pipecat-cloud/enterprise/sizing.md), as
`cpu=<quantity>,memory=<quantity>` (e.g. `cpu=2,memory=4Gi`). Mutually
exclusive with `--profile`: passing one clears the other from
`pcc-deploy.toml`. Requires `pipecatcloud` 1.2.0 or later.

**--architecture** `string`

CPU architecture the agent image requires: `amd64` or `arm64`. Omitted, the
region's default applies. When a region is set by flag or in
`pcc-deploy.toml`, the choice is validated against that region's supported
architectures (see [`regions list`](https://docs.pipecat.ai/api-reference/cli/cloud/regions#list))
before anything is uploaded. Must match how the image was built. Requires
`pipecatcloud` 1.2.0 or later.

**--region / -r** `string`

Region where the agent will be deployed. If not specified, uses your
organization's default region (typically `us-west`). Choose a region close to
your users for optimal latency. Must be a region of the organization in use.

**--force / -f** `boolean` (default: false)

Force a new deployment even if the configuration hasn't changed, replacing all
running pods. Useful for picking up updated container images when using
mutable tags like `latest`, or for refreshing modified secret values.

**--yes / -y** `boolean` (default: false)

Skip all confirmation prompts, including cloud build prompts. Useful for CI/CD
pipelines. When used without an image, automatically triggers a cloud build.

**--build-id / -b** `string`

Deploy using an existing cloud build ID instead of building a new image. Takes
precedence over `image`. You can find build IDs using `pipecat cloud build
    list`.

**--no-credentials / -nc** `boolean` (default: false)

Deploy without an image pull secret. Without `--yes` or `--force`, an image
deploy that names neither `--credentials` nor an `image_credentials` in the
config file is refused, since a private image would fail to pull. Pass this
when the image is public.

**--build-dir / -d** `string`

Build context directory for cloud builds. Defaults to the current directory.

**--dockerfile** `string`

Path to Dockerfile for cloud builds. Defaults to `Dockerfile` in the build
context directory.

### GitHub source

Create an agent that builds from a GitHub repository instead of an image. The
organization must be [connected to GitHub](https://docs.pipecat.ai/api-reference/cli/cloud/github.md#connect)
first.

**--repo** `string`

Repository as `owner/repo`. Skips the image build and push entirely — Pipecat
Cloud builds from the repository.

**--branch** `string`

Branch to build and deploy from.

**--dockerfile-path** `string` (default: Dockerfile)

Path to the Dockerfile within the repository. Distinct from `--dockerfile`,
which applies to cloud builds from a local context.

**--subdirectory** `string`

Build context subdirectory within the repository.

> [!WARNING]
>
> `--repo` only applies when **creating** an agent. If the agent already exists,
> the deploy exits 1 and points you at [`agent
>     link`](https://docs.pipecat.ai/api-reference/cli/cloud/project.md#link), which re-points an existing
> agent.

A GitHub source can't be combined with an `image`, `--build-id`, or
`--resources` / `[resources]`: a deploy is built from a repository or from an
image, not both, and a GitHub-sourced agent is sized with `--profile`. The
first deploy is followed through its build, so the command reports whether it
succeeded rather than returning as soon as it's queued.

## Examples

**Deploy a new agent:**

```shell theme={null}
pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --credentials dockerhub-creds
```

**Update an existing agent with a new image:**

```shell theme={null}
pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.2 --credentials dockerhub-creds
```

**Deploy with a specific secret set:**

```shell theme={null}
pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --credentials dockerhub-creds --secrets my-secret-set
```

**Deploy a public image without an image pull secret:**

```shell theme={null}
pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --no-credentials
```

**Keep one instance always warm to avoid cold starts:**

```shell theme={null}
pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --credentials dockerhub-creds --min-agents 1
```

**Limit the maximum number of agent instances:**

```shell theme={null}
pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --credentials dockerhub-creds --max-agents 5
```

**Deploy to a specific region:**

```shell theme={null}
pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --credentials dockerhub-creds --region eu-central
```

**Deploy with Krisp VIVA noise cancellation:**

```shell theme={null}
pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --credentials dockerhub-creds --krisp-viva-audio-filter tel
```

**Cap session duration (useful as a safety net for short-interaction agents):**

```shell theme={null}
pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --credentials dockerhub-creds --max-session-duration 300
```

**Deploy using cloud build (interactive):**

```shell theme={null}
pipecat cloud deploy
```

**Deploy using cloud build in CI/CD (no prompts):**

```shell theme={null}
pipecat cloud deploy --yes
```

**Deploy using an existing build:**

```shell theme={null}
pipecat cloud deploy --build-id abc12345-6789-0abc-def0-123456789abc
```

**Create an agent that builds from a GitHub repository:**

```shell theme={null}
pipecat cloud deploy my-agent --repo my-org/my-bot --branch main
```

**Deploy using an alternate config file:**

```shell theme={null}
pipecat cloud deploy --config-file pcc-deploy.staging.toml
```

## Configuration File (pcc-deploy.toml)

The `deploy` command supports a configuration file for repeatable deployments. Create a `pcc-deploy.toml` file in your project root to define deployment settings that can be shared across your team and version controlled.

### File Location

Place `pcc-deploy.toml` in the same directory where you run the `pipecat cloud deploy` command. The CLI will automatically detect and use this file.

To use an alternate config file (e.g. for different environments), pass `--config-file`:

```shell theme={null}
pipecat cloud deploy --config-file pcc-deploy.staging.toml
```

You can also set the `PIPECAT_DEPLOY_CONFIG_PATH` environment variable, with the `--config-file` flag taking precedence.

### Precedence

Values are applied with the following order of precedence:

1. CLI arguments (highest priority)
2. `pcc-deploy.toml` values
3. Default values (lowest priority)

This allows you to define defaults in the config file while still overriding specific values via CLI flags when needed.

### Configuration Options

#### Required Fields

**agent\_name** `string` *required*

Name of the agent to deploy. Must start with a lowercase letter or number, can
include hyphens, and must end with a lowercase letter or number. Maximum 54 characters.

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

**image** `string`

Docker image URL with tag. Required when not using cloud builds or `build_id`.

```toml theme={null}
image = "your-dockername/my-agent:0.1"
```

> [!NOTE]
>
> You must specify either `image` or `build_id`, or omit both to trigger a cloud
> build at deploy time.

#### Optional Fields

**build\_id** `string`

An existing cloud build ID to deploy. Cannot be used together with `image`.

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

**region** `string`

Region where the agent will be deployed. If not specified, uses your
organization's default region (typically `us-west`).

```toml theme={null}
region = "us-east"
```

**secret\_set** `string`

Name of the secret set to use for environment variables. The secret set must
exist in the same region as the agent and must be in the
[`ready`](https://docs.pipecat.ai/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
state — deploys that bind a `pending` or `failed` set are rejected.

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

**image\_credentials** `string`

Name of the image pull secret for private registries. The image pull secret must exist in the same region as the agent and must be in the [`ready`](https://docs.pipecat.ai/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness) state.

```toml theme={null}
image_credentials = "dockerhub-credentials"
```

**agent\_profile** `string`

Agent profile for resource allocation. Takes the same values as `--profile`.

```toml theme={null}
agent_profile = "agent-2x"
```

**architecture** `string`

CPU architecture the agent image requires: `amd64` or `arm64`. Omitted, the region's default applies. See [Pipecat Enterprise Agent Sizing](https://docs.pipecat.ai/pipecat-cloud/enterprise/sizing.md#architecture).

```toml theme={null}
architecture = "arm64"
```

**\[resources]** `table`

Explicit sizing for agents in [self-hosted regions](https://docs.pipecat.ai/pipecat-cloud/enterprise/sizing.md), using Kubernetes quantities. Mutually exclusive with `agent_profile`.

```toml theme={null}
[resources]
cpu = "1"
memory = "2Gi"
```

**max\_session\_duration** `number` (default: 7200)

Maximum session duration in seconds. When a session reaches this limit, the
session is stopped: the bot is cancelled, with no opportunity for it to say
goodbye first. Valid range: `60` to `14400` (4 hours). See
[Session duration limits](https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions.md#session-duration-limits)
for more information.

```toml theme={null}
max_session_duration = 300
```

**websocket\_auth** `string` (default: none)

Authentication required on the agent's WebSocket endpoint. `none` for no
authentication, or `token` to require an HMAC session token from `/start`. See
[WebSocket authentication](https://docs.pipecat.ai/pipecat-cloud/guides/websocket-authentication.md).

```toml theme={null}
websocket_auth = "token"
```

#### Scaling Configuration

Define auto-scaling behavior in a `[scaling]` section:

**scaling.min\_agents** `number` (default: 0)

Minimum number of agent instances to keep warm. Setting to 0 allows scaling to zero but may result in cold starts.

```toml theme={null}
[scaling]
min_agents = 1
```

**scaling.max\_agents** `number`

Maximum number of agent instances allowed, at least 1. Omitted, an existing agent keeps its current maximum.

```toml theme={null}
[scaling]
max_agents = 20
```

#### Krisp VIVA Configuration

Configure Krisp VIVA noise cancellation in a `[krisp_viva]` section:

**krisp\_viva.audio\_filter** `string`

Krisp VIVA audio filter model. Valid values: `tel` (telephony, up to 16kHz) or `pro` (WebRTC, up to 32kHz). Omit or set to `null` to disable.

```toml theme={null}
[krisp_viva]
audio_filter = "tel"
```

#### Cloud Build Configuration

Configure cloud build behavior in a `[build]` section:

**build.context\_dir** `string` (default: .)

Directory to use as the build context. Defaults to the current directory.

```toml theme={null}
[build]
context_dir = "."
```

**build.dockerfile** `string` (default: Dockerfile)

Path to the Dockerfile within the build context.

```toml theme={null}
[build]
dockerfile = "Dockerfile"
```

**build.exclude.patterns** `string[]`

Additional file patterns to exclude from the build context. Common patterns like `.git`, `.env`, `__pycache__`, and `.venv` are excluded automatically.

```toml theme={null}
[build.exclude]
patterns = ["*.md", "tests/", "docs/"]
```

#### GitHub Source Configuration

Build from a repository instead of an image, in a `[git]` section. Command-line
flags take precedence over these values.

**git.repo** `string`

Repository as `owner/repo`.

```toml theme={null}
[git]
repo = "my-org/my-bot"
```

**git.branch** `string`

Branch to build and deploy from.

```toml theme={null}
[git]
branch = "main"
```

**git.dockerfile\_path** `string` (default: Dockerfile)

Path to the Dockerfile within the repository.

```toml theme={null}
[git]
dockerfile_path = "docker/Dockerfile"
```

**git.subdirectory** `string`

Build context subdirectory within the repository.

```toml theme={null}
[git]
subdirectory = "bot"
```

> [!NOTE]
>
> Like `--repo`, a `[git]` section only applies when the agent is created. Once
> the agent exists, a `pipecat cloud deploy` with a `[git]` section exits 1, so
> remove the section after the first deploy and ship later commits with [`agent
>     deploy --github`](https://docs.pipecat.ai/api-reference/cli/cloud/project.md#deploy).

### Complete Example

> [tab] With cloud build
>
> ```toml theme={null}
> # Basic agent configuration
> agent_name = "my-voice-agent"
> region = "us-west"
>
> # Secrets
> secret_set = "my-agent-secrets"
>
> # Resource allocation
> agent_profile = "agent-1x"
>
> # Auto-scaling configuration
> [scaling]
> min_agents = 1
> max_agents = 20
>
> # Cloud build configuration (optional, shown with defaults)
> [build]
> context_dir = "."
> dockerfile = "Dockerfile"
>
> [build.exclude]
> patterns = ["*.md", "tests/"]
> ```

> [tab] With custom image
>
> ```toml theme={null}
> # Basic agent configuration
> agent_name = "my-voice-agent"
> image = "your-dockername/my-voice-agent:0.1"
> region = "us-west"
>
> # Secrets and credentials
> secret_set = "my-agent-secrets"
> image_credentials = "dockerhub-credentials"
>
> # Resource allocation
> agent_profile = "agent-1x"
>
> # Auto-scaling configuration
> [scaling]
> min_agents = 1
> max_agents = 20
>
> # Krisp VIVA noise cancellation
> [krisp_viva]
> audio_filter = "tel"
> ```

> [tab] Self-hosted region
>
> ```toml theme={null}
> # Basic agent configuration
> agent_name = "my-voice-agent"
> image = "your-dockername/my-voice-agent:0.1"
> region = "pce-acme-us-east"
> architecture = "arm64"
>
> # Referenced secrets (Kubernetes Secrets in your cluster)
> secret_set = "my-agent-secrets"
> image_credentials = "my-registry-creds"
>
> # Explicit sizing instead of an agent profile
> [resources]
> cpu = "1"
> memory = "2Gi"
>
> # Auto-scaling configuration
> [scaling]
> min_agents = 1
> max_agents = 50
> ```

### Using the Configuration File

Once you have a `pcc-deploy.toml` file, simply run:

```shell theme={null}
pipecat cloud deploy
```

The CLI will automatically load your configuration. You can still override any value using CLI flags:

```shell theme={null}
# Use config file but override the region
pipecat cloud deploy --region eu-central

# Use config file but force update without confirmation
pipecat cloud deploy --force
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.