Document when a deploy does not replace running agents - #1080
Open
jamsea wants to merge 2 commits into
Open
Conversation
A deploy only replaces running agent instances when it creates a new version. If the config you send matches what the agent already has, Pipecat Cloud keeps the current version and leaves warm instances running, so they can keep serving old code with no sign of a problem. Nothing customer-facing covered this. A customer with min-agents >= 1 served a stale image for two months, building from a mutable :latest base tag. Adds a section to the Deployments page covering which changes create a new version and which do not, that --force is how you force one, and why to pin the base image instead of using :latest. Cross-links it from Secrets, Agent images, and Scaling.
Contributor
|
🔍 Mintlify preview for this branch: https://daily-docs-deploy-no-op-warm-pods-t3002.mintlify.site |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves Pipecat Cloud documentation by explaining a customer-visible deploy behavior: successful deploys don’t necessarily replace already-running (warm) agent instances unless the deploy results in a new agent version (or is forced). It adds a dedicated section to the Deployments doc and cross-links it from related fundamentals pages to help users diagnose “deploy succeeded but nothing changed” scenarios.
Changes:
- Added a new “When a deploy does not replace running agents” section to clarify which actions do/don’t create a new version and how to force one.
- Updated Secrets, Agent images, and Scaling fundamentals pages to cross-link to the new section and highlight relevant gotchas (secrets updates,
:latesttags, scaling-only deploys).
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| pipecat-cloud/fundamentals/deploy.mdx | Adds the new section explaining version creation vs no-op deploys, plus --force guidance and an image pinning tip. |
| pipecat-cloud/fundamentals/secrets.mdx | Clarifies that secret value updates require a forced redeploy to be picked up, and links to the new deploy section. |
| pipecat-cloud/fundamentals/agent-images.mdx | Expands the pinning recommendation to explain why mutable tags can result in no-op deploys; links to the new deploy section. |
| pipecat-cloud/fundamentals/scaling.mdx | Adds a cross-link note explaining scaling-only deploys don’t create a new version or restart instances. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Cut repetition. The :latest warning was explained in full in four places, and each exception carried a paragraph of rationale where a clause does the job. - Drop the closing tip in deploy.mdx: it repeated the image-tag bullet above it and the tip in agent-images.mdx, which already links here. - Drop the list of changes that DO create a new version. That is what readers already expect, and --force has its own paragraph. - Drop the symptom list: two of its three lines restated the bullets below it. - One line per exception, and fold cloud builds into the image-tag bullet since it is the same mechanism (the tag did not change). - Trim the three cross-links to one sentence each.
markbackman
reviewed
Aug 11, 2026
| 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)). |
Contributor
There was a problem hiding this comment.
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.
markbackman
reviewed
Aug 11, 2026
| 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 |
Contributor
There was a problem hiding this comment.
@jamsea can we consolidate this point to 1 simple paragraph?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Nothing customer-facing documented the fact that a Pipecat Cloud deploy does not always replace running pods. A customer with warm instances (
min-agents >= 1) can keep serving an older version of their agent with no sign that anything is wrong. One customer ran a broken Krisp setup for two months, building from the mutabledailyco/pipecat-base:latesttag.The behavior is intentional (a no-op deploy used to roll pods and drop in-flight sessions), but it was only intuitive if you already knew the internals. This documents the customer-facing shape of it.