Skip to content

Document when a deploy does not replace running agents #1080

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jamsea wants to merge 2 commits into
base: main
Choose a base branch
from
+33 −3
Open

Document when a deploy does not replace running agents #1080

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a4a7b96
Document when a deploy does not replace running agents
jamsea Aug 11, 2026
74c19d6
Tighten the no-op deploy docs
jamsea Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion pipecat-cloud/fundamentals/agent-images.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,12 @@ The base image supports multiple Python versions. The default Python version is
- `dailyco/pipecat-base:0.1.0-py3.13` (Python 3.13)
- `dailyco/pipecat-base:0.1.0-py3.14` (Python 3.14)

<Tip>For production use, we recommend pinning to specific versions.</Tip>
<Tip>
For production use, we recommend pinning to specific versions. A `:latest` tag
can change without your project changing, so a deploy can leave your warm
instances on the old image
([why](/pipecat-cloud/fundamentals/deploy#when-a-deploy-does-not-replace-running-agents)).
</Tip>

## Using a custom image

Expand Down
20 changes: 20 additions & 0 deletions pipecat-cloud/fundamentals/deploy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,26 @@ Idle agent instances in your agent pool will be replaced with the new configurat
New agent requests may, therefore, start with prior deployment configuration if updates are not fully propagated. This ensures on-demand availability
remains consistent and avoids potential cold starts.

### When a deploy does not replace running agents

@markbackman markbackman Aug 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jamsea can we consolidate this point to 1 simple paragraph?


A deploy only replaces your running agent instances when it creates a new version of your agent. If the configuration you send matches what the agent already has, Pipecat Cloud keeps the current version and leaves your instances alone, so a routine deploy can't cut off a session that is already in progress.

Watch for this if you keep warm instances (`min-agents` set to 1 or higher): they can keep serving your old code, your deploy will report success, and the output won't look wrong.

These changes do **not** create a new version:

- **Scaling only.** `min-agents` and `max-agents` apply to the running pool in place.
- **An image tag you already deployed.** Pipecat Cloud stores the tag you gave it, not the image behind it, so pushing new content to a tag like `:latest` and deploying that same tag looks like no change. [Cloud builds](/pipecat-cloud/guides/cloud-builds) behave the same way when your project files haven't changed, because the tag comes from your file contents.
- **A secret's value.** Your deployment records which secret sets it uses, not the values inside them.

To pick up any of these, force a new version:

```bash
pipecat cloud deploy --force
```

Pinning your base image to an exact version instead of `:latest` avoids the second case entirely. See [Agent images](/pipecat-cloud/fundamentals/agent-images) for the available tags, and the [`--force` flag](/api-reference/cli/cloud/deploy) in the CLI reference.

### Failed deployments

If a deployment fails (i.e. fails to enter a `ready` state), requests will be routed to any prior deployments in a ready state.
Expand Down
2 changes: 2 additions & 0 deletions pipecat-cloud/fundamentals/scaling.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,6 +241,8 @@ pipecat cloud deploy [agent-name] [image] --min-agents 1 --max-agents 5
Please note that changing your scaling parameters will not disrupt any active sessions.
If you reduce your max instance count below the number of currently active sessions, you will still be billed for the duration of those sessions.

A scaling-only change also doesn't create a new version or restart your instances, so it won't pick up new code, a new image, or a new secret value ([why](/pipecat-cloud/fundamentals/deploy#when-a-deploy-does-not-replace-running-agents)).

@markbackman markbackman Aug 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Has this been a point of confusion? New code and images are only used when they're pushed. This seems obvious, so I want to make sure this has been confusing.


## Capacity Planning

Effective capacity planning is crucial for production deployments to ensure your agents respond immediately.
Expand Down
7 changes: 5 additions & 2 deletions pipecat-cloud/fundamentals/secrets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,11 @@ pipecat cloud secrets set my-secrets SECRET_NAME_3 secret-value-3
```

<Info>
Whenever a secret is added or updated in an existing set, any deployments
using that set will need to be redeployed to access the new values.
Whenever a secret is added or updated in an existing set, any deployments using
that set will need to be redeployed to access the new values. A plain
`pipecat cloud deploy` looks like no change here, so use
`pipecat cloud deploy --force`
([why](/pipecat-cloud/fundamentals/deploy#when-a-deploy-does-not-replace-running-agents)).
</Info>

#### Provisioning and readiness
Expand Down
Loading