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

# deploy

> Create or modify an agent deployment

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](/pipecat-cloud/guides/cloud-builds). 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](/pipecat-cloud/fundamentals/error-codes) with more information.

## Usage

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

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Unique string identifier for the agent deployment. Must not contain spaces.
</ParamField>

<ParamField path="image" type="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](/pipecat-cloud/guides/cloud-builds) or `--build-id`.
</ParamField>

**Options:**

<ParamField path="--config-file" type="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.
</ParamField>

<ParamField path="--credentials / -c" type="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`](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
  state at deploy time.
</ParamField>

<ParamField path="--organization / -o" type="string">
  Organization to deploy the agent to. If not provided, uses the current
  organization from your configuration.
</ParamField>

<ParamField path="--secrets / -s" type="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`](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
  state — deploys that bind a `pending` or `failed` set are rejected.
</ParamField>

<ParamField path="--min-agents / -min" type="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.
</ParamField>

<ParamField path="--max-agents / -max" type="number" default="50">
  Maximum number of allowed agent instances. Must be between 1 and 50. If you
  need more agents, please contact us at [help@daily.co](mailto:help@daily.co) or via
  [Discord](https://discord.gg/dailyco).
</ParamField>

<ParamField path="--krisp-viva-audio-filter" type="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](/api-reference/server/utilities/audio/krisp-viva-filter) documentation for more information.
</ParamField>

<ParamField path="--max-session-duration" type="number" default="7200">
  Maximum session duration in seconds. When a session reaches this limit, the
  agent's connection is forcibly closed — the session is cut off mid-flight
  with no notice to the bot. Valid range: `60` to `14400` (4 hours). Defaults
  to `7200` (2 hours) when unset.

  See [Session duration limits](/pipecat-cloud/fundamentals/active-sessions#session-duration-limits)
  for more information.
</ParamField>

<ParamField path="--profile / -p" type="string" default="agent-1x">
  The agent profile to use for resource allocation. Valid values are:
  `agent-1x`, `agent-2x`, `agent-3x`.

  See [Agent Profiles](/pipecat-cloud/fundamentals/deploy#agent-profiles) for more information.
</ParamField>

<ParamField path="--region / -r" type="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.
</ParamField>

<ParamField path="--force / -f" type="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.
</ParamField>

<ParamField path="--yes / -y" type="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.
</ParamField>

<ParamField path="--build-id / -b" type="string">
  Deploy using an existing cloud build ID instead of building a new image.
  Cannot be used together with `--image`. You can find build IDs using `pipecat
      cloud build list`.
</ParamField>

<ParamField path="--build-dir / -d" type="string">
  Build context directory for cloud builds. Defaults to the current directory.
</ParamField>

<ParamField path="--dockerfile" type="string">
  Path to Dockerfile for cloud builds. Defaults to `Dockerfile` in the build
  context directory.
</ParamField>

## Examples

**Deploy a new agent:**

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

**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
```

**Deploy with a specific secret set:**

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

**Deploy a private image using image pull credentials:**

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

**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 --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 --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 --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 --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 --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
```

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

<ParamField path="agent_name" type="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"
  ```
</ParamField>

<ParamField path="image" type="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"
  ```
</ParamField>

<Note>
  You must specify either `image` or `build_id`, or omit both to trigger a cloud
  build at deploy time.
</Note>

#### Optional Fields

<ParamField path="build_id" type="string">
  An existing cloud build ID to deploy. Cannot be used together with `image`.

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

<ParamField path="region" type="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"
  ```
</ParamField>

<ParamField path="secret_set" type="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`](/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"
  ```
</ParamField>

<ParamField path="image_credentials" type="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`](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness) state.

  ```toml theme={null}
  image_credentials = "dockerhub-credentials"
  ```
</ParamField>

<ParamField path="agent_profile" type="string" default="agent-1x">
  Agent profile for resource allocation. Valid values: `agent-1x`, `agent-2x`, `agent-3x`.

  ```toml theme={null}
  agent_profile = "agent-2x"
  ```
</ParamField>

<ParamField path="max_session_duration" type="number" default="7200">
  Maximum session duration in seconds. When a session reaches this limit, the
  agent's connection is forcibly closed — the session is cut off mid-flight
  with no notice to the bot. Valid range: `60` to `14400` (4 hours). See
  [Session duration limits](/pipecat-cloud/fundamentals/active-sessions#session-duration-limits)
  for more information.

  ```toml theme={null}
  max_session_duration = 300
  ```
</ParamField>

#### Scaling Configuration

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

<ParamField path="scaling.min_agents" type="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
  ```
</ParamField>

<ParamField path="scaling.max_agents" type="number" default="50">
  Maximum number of agent instances allowed.

  ```toml theme={null}
  [scaling]
  max_agents = 20
  ```
</ParamField>

#### Krisp VIVA Configuration

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

<ParamField path="krisp_viva.audio_filter" type="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"
  ```
</ParamField>

#### Cloud Build Configuration

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

<ParamField path="build.context_dir" type="string" default=".">
  Directory to use as the build context. Defaults to the current directory.

  ```toml theme={null}
  [build]
  context_dir = "."
  ```
</ParamField>

<ParamField path="build.dockerfile" type="string" default="Dockerfile">
  Path to the Dockerfile within the build context.

  ```toml theme={null}
  [build]
  dockerfile = "Dockerfile"
  ```
</ParamField>

<ParamField path="build.exclude.patterns" type="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/"]
  ```
</ParamField>

### Complete Example

<Tabs>
  <Tab title="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>

  <Tab title="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>
</Tabs>

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