docs: position the development runner as not for production use#995
Conversation
The development runner (pipecat.runner.run) is a local-dev tool: its session-start and transport-webhook endpoints are unauthenticated, unsigned, and unthrottled, and a single request can create paid resources. Rather than harden it toward production parity, make the docs state the boundary clearly. - self-hosting: pull the runner out of the numbered options; lead with a boundary warning; the real options are now "build your own dispatcher" and "use a managed runtime". Add a prototyping-only section covering the minimum reverse-proxy smarts to put in front of the runner and where that stops being enough. - overview: drop "the runner directly" from the list of production session-start servers. - running-bots-locally: replace the "genuinely a fine production target" closing note with a clear dev-tool-not-a-production-server boundary.
|
🔍 Mintlify preview for this branch: https://daily-ms-improve-self-hosting-docs.mintlify.site |
| For production-grade images, Pipecat Cloud's [base image](https://github.com/daily-co/pipecat-cloud-images) (`dailyco/pipecat-base`) is what most of the [examples](https://github.com/pipecat-ai/pipecat-examples) build from. It's also a reasonable starting point for self-hosted deployments — it provides a sensible runtime environment for a bot file, and you can use it without using PCC. | ||
|
|
||
| ## When the development runner isn't enough | ||
| ## The runner is a development tool, not a production server |
There was a problem hiding this comment.
I wonder if we should add a callout for this right at the beginning of this page and link to this section.
What do you think ?
markbackman
left a comment
markbackman
left a comment
There was a problem hiding this comment.
Nice! Thanks for the update.
kompfner
left a comment
kompfner
left a comment
There was a problem hiding this comment.
A few suggestions, but overall this is a nice clarification of our recommendations!
|
Going through all the review notes, I'll commit some updates in a bit. |
- Rename "Self-hosting in production" -> "Running bots in production" (only
one of the two options is literally self-hosting); rename the nav group to
"Production hosting patterns" and update card/link labels. Slug unchanged.
- Move the containerizing content off "Running bots locally" onto the
production page, reframed as building a per-session bot image (dispatcher
injects room/token; process runs one conversation and exits) rather than
running the dev runner as a server. Drops the misleading
`CMD python bot.py --host 0.0.0.0` production entrypoint.
- Scope the security claims accurately: POST /start and the Daily dial-in
webhook are unauthenticated, but the runner does sign WS tokens and verify
WhatsApp webhooks, so "no request signing" was overbroad.
- Soften the prototyping guidance ("we recommend"), reword the "does not
solve" list to avoid implying a checklist to production-readiness, and
explain the localhost/--host 0.0.0.0 nuance in context.
- Add a callout at the top of "Running bots locally" linking to the boundary
section.
|
All review feedback should now be addressed. @markbackman you might want to take a second look as well as I renamed a couple of pages. |
| ## What plays the runner's role | ||
|
|
||
| A practical upper bound per host is "however many concurrent bot subprocesses one host can sustain", which depends heavily on what your pipeline does. CPU-light pipelines that mostly proxy between transport and third-party services can pack many sessions per host; pipelines with local STT/TTS, custom models, or significant VAD work will saturate sooner. | ||
| The two options below can roughly be summarized as "run everything yourself" and "let a managed runtime do it for you". The first is self-hosting in the literal sense; the second is an alternative to it. Both options are presented together here because the decision is the same one ("what serves session-start and runs the bot?"), and most teams evaluating self-hosting are also weighing whether they want to be in that business at all. |
There was a problem hiding this comment.
Nit: now that this page isn't titled "self-hosting", we don't need to sort of apologize for one of the options not technically being self-hosting.
| The two options below can roughly be summarized as "run everything yourself" and "let a managed runtime do it for you". The first is self-hosting in the literal sense; the second is an alternative to it. Both options are presented together here because the decision is the same one ("what serves session-start and runs the bot?"), and most teams evaluating self-hosting are also weighing whether they want to be in that business at all. | |
| The two options below can roughly be summarized as "run everything yourself" and "let a managed runtime do it for you". |
There was a problem hiding this comment.
This suggestion still stands.
There was a problem hiding this comment.
It was applied, I think the file rename might be skewing your view.
|
So sorry, @mattshep, just noticed that we still have a bunch of language in the "running in production" guide that really only made sense when the guide was focused on self-hosting and only presented the managed option as a bonus. Now that the guide is broadly focused on how to run bots in production, all the stale language should be expunged or updated accordingly. Should've noticed this on my first pass through! |
- "choosing one of the options below" instead of "putting one in front of your bots" (the managed-runtime option isn't something you put in front). - Drop the "self-hosting in the literal sense" aside now that the page isn't titled self-hosting. - Remove the Option 1-vs-2 chooser paragraph (holdover from the three-option structure). - Reframe "What you'll need to address either way" -> "Self-hosting considerations": these are Option 1's to own; a managed runtime handles most.
Match the file/slug to the retitled page. Renames self-hosting.mdx -> running-bots-in-production.mdx, updates the nav path and all internal links, and adds redirects so existing URLs keep working: - /pipecat/deployment/self-hosting -> /pipecat/deployment/running-bots-in-production (current live slug) - /deployment/self-hosting -> /pipecat/deployment/running-bots-in-production (legacy top-level, repointed to avoid a redirect chain)
|
Thanks @kompfner — the latest two pushes close out this round:
One correction worth surfacing from the earlier security wording: I scoped the "unauthenticated" claim to |
kompfner
left a comment
kompfner
left a comment
There was a problem hiding this comment.
This looks great! Thanks for the tweaks. I've resolved all my feedback comments except for 1, which I believe still applies. Going ahead and putting my stamp of approval on it. No need to circle back.
markbackman
left a comment
markbackman
left a comment
There was a problem hiding this comment.
Nice improvements! Thanks for the help @mattshep 🙌
4 participants
What & why
We've been receiving security advisories for the development runner (
pipecat.runner.run) — most recently an unauthenticated dial-in-webhook endpoint that lets a remote caller spawn a bot and create a paid Daily room at the operator's expense. Internally we've decided not to harden the dev runner toward production parity; it exists to streamline local development. Our answer for production is a proper dispatcher, a managed runtime, or Pipecat Cloud.This updates the deployment docs to state that boundary clearly, rather than presenting the runner as a viable production target (as PR #824 did). It aligns with the maintainer position on the advisory: "this is a dev runner; NOT meant for production use."
Changes
self-hosting.mdx— Pull the runner out of the numbered options. Lead with a<Warning>stating it's not built or supported for production (unauthenticated/unsigned/unthrottled endpoints; a single request can create paid resources; SPOF). The two real options become Build your own dispatcher and Use a managed runtime. Add a new "Exposing the runner for prototyping" section — the minimum reverse-proxy smarts (auth on/start, rate limiting, TLS), explicitly capped at prototyping/alpha, plus the two things it doesn't solve (transport webhooks have a different caller than/start; lifecycle/capacity/isolation untouched).overview.mdx— Drop "the runner directly" from the list of things that can serve production session-start traffic.running-bots-locally.mdx— Replace the "genuinely a fine production target" closing note with a clear dev-tool-not-a-production-server boundary. Local-dev happy path is otherwise untouched.Deliberately no links to specific security advisories or CVE IDs — citing them invites a "just patch these and it's fine" read, which reintroduces the "sort-of production-ready" framing we're trying to kill.
Follow-ups (not in this PR)
--host 0.0.0.0containerizing example inrunning-bots-locally.mdxstill binds the runner to all interfaces; left as-is to keep scope tight, but it's the one remaining spot that soft-contradicts the new posture.