docs(cloud): self-hosted regions - #1145
Draft
mattshep wants to merge 24 commits into
Draft
Conversation
…ta-residency fix - CLI overview: document the global --output rich|plain|json option, PIPECAT_OUTPUT / config resolution order, piped-progress behaviour, and the 1.1.0 exit-code contract (0/1/2, non-TTY prompts fail fast). - REST reference: add architecture (amd64|arm64) to agent create/update, mark nodeType deprecated, and add supported_architectures / default_architecture to the regions listing. - Security page: replace the stale single-region statement with the four Daily-hosted regions and what is stored regionally vs in the US.
Adds a Self-Hosted Regions nav group under the Pipecat Cloud tab with twelve page skeletons (frontmatter, intro, planned sections) and a snippets/self-hosted-vars.mdx that centralizes the offering's name and version floors so a product rename or version bump is a one-line change.
Overview: what stays the same vs what changes against Daily-hosted regions, how a region connects (outbound-only, mutually authenticated), what data leaves the cluster, and how to get started. Requirements: Kubernetes version and cgroup v2, node architectures, the workloads namespace Pod Security label, cert-manager + trust-manager, outbound network destinations, platform component sizing defaults, supporting services, and workstation tooling.
Setup: registry key, region registration, enrollment token, values file, Helm install, and verification — CLI-first with dashboard equivalents. Configuration: the values a production region sets (identity, external broker, log store, WebSocket exposure, replicas, agent pod settings, pull credentials, network policies, diagnostics) and the two rules that keep upgrades version-only.
Secrets: the reference flow for env and image-pull Secrets, readiness states incl. unknown, value lifecycle, and the rebuilt-cluster caveat. Sizing: explicit CPU/memory on deploy, organization agent profiles and their template semantics, architecture declaration and validation, and the absence of the platform replica ceiling.
…bility WebSockets: how sessions reach the region, the three exposure modes (Ingress, Gateway API, bring-your-own) with the idle-timeout warning, registering and changing the public endpoint, per-region token auth, and both telephony dial-in patterns. Logs: the off-by-default log lane and how to enable it, what is captured and the base-image requirement, session metrics and cgroup v2, and platform metrics with the Prometheus Operator toggles.
…closure Operations: version-only upgrades, the two-level certificate lifecycle and expired-CA recovery, HA posture, rebuilding a cluster, retiring a region, and GitOps notes. Diagnostics: region status, the doctor (both forms), the region event feed, the support bundle, common failures, and what to send support. What Pipecat Cloud Can See: always / by default / only-when-enabled / never, with the support bundle's access stated per namespace.
Prose description of Daily's validated EKS layout: VPC and node pools (fixed system group + Karpenter agents pool), managed Valkey and OpenSearch, the ALB/ACM/external-dns WebSocket front door, values posture, monitoring signals, cold-start levers, and sizing presets.
…egistry keys regions: list gains architecture columns; new register, show, enroll-token, and delete. secrets: new reference. deploy: --resources, --architecture, and the architecture / [resources] toml keys, plus a self-hosted example. agent: status rows and the new profiles group. organizations: the registry-keys group. Version notes come from one shared component in snippets/self-hosted-vars.mdx.
…e REST reference Regions guide: Daily-hosted vs self-hosted framing, architecture listing, referenced-secret note. Deploy: pointer to explicit sizing and architecture. Secrets: unknown readiness state and the source field. Logging and scaling: self-hosted notes. Introduction: capability bullet. REST reference: self_hosted on regions, resources on agent create/update, source and unknown on secret sets.
regions delete gains --yes (prompt-skip only); retiring a region notes remote-first agent deletion against an unreachable region and the key release rule for never-enrolled regions.
Configuration: externalBroker.password as the values-injected path alongside passwordSecret (which now fails closed on a cluster-less render), and a new Activation secret section covering the generated, from-a-value, and supplied-by-you modes with the ESO recipe. Operations: replace the GitOps caveat with the supported approach. Package floor 0.1.10.
Contributor
|
🔍 Mintlify preview for this branch: https://daily-ms-pcc-self-hosted.mintlify.site |
omChauhanDev
pushed a commit
to omChauhanDev/docs
that referenced
this pull request
Aug 31, 2026
Four pages assert that Pipecat Cloud requires linux/arm64, phrased as a
platform-wide constraint: "Pipecat Cloud only supports images for the
linux/arm64 platform", "requires all images to be built to target Linux
on ARM", "required for Pipecat Cloud deployments".
pipecatcloud 1.2.0 added `deploy --architecture {amd64,arm64}` and an
`architecture` key in pcc-deploy.toml, validated against what the target
region supports. Architecture is a property of the region now, not of the
platform.
Nothing here is wrong for a reader deploying today — Daily-hosted regions
run arm64 — so this states the rule that is actually true and names arm64
as the value that follows from it, rather than leaving four absolutes to
be contradicted later.
Scoped to the four pages that state it as absolute. The flag itself and
the pcc-deploy.toml key are already documented in pipecat-ai#1145, and the three
container-registry guides say "the correct platform (linux/arm64)" about
`docker build-push`, which does build arm64 and cannot be changed.
Also adds the docker image inspect one-liner to error-codes, since the
first thing a reader hitting PCC_INVALID_IMAGE_PLATFORM needs is a way to
see what they actually built.
# Conflicts: # llms-full.txt # llms.txt # pipecat-cloud/fundamentals/scaling.mdx
Upstream added api-reference/cli/cloud/output.mdx with the full contract; the overview keeps a two-line pointer instead of a duplicate section.
…call goes New Architecture page: control plane vs data plane, what each owns and can see, how management and session traffic flow, and why the control plane exists beyond billing. WebSockets page opens with where a call actually goes (directly to the data plane; the activation service lives in the cluster). The offering is named Pipecat Enterprise via the shared snippet; package floor moves to 0.1.12.
…ateway Documents wsExposure.mode: gateway (0.1.11) alongside ingress and httpRoute, and the envoy-gateway.enabled dependency that replaced the kind-only dev gateway.
Moves the EKS page under a Reference architectures subgroup and adds the Oracle OKE layout (standalone VCN, Karpenter pools, managed OCI stores, Gateway API front door via Envoy Gateway and an OCI NLB) so the section no longer presents a single provider as the reference.
Replaces the ASCII diagrams, which did not render inside <Frame>, with Mermaid flowcharts — the diagram format the rest of the site uses.
Replaces the Mermaid flowchart with an SVG in the style of the existing Pipecat Cloud overview graphic: developer, control plane over data plane, end users in a dashed panel with the transport list kept abstract. The control-plane side of the region connection is the Region gateway throughout.
Nesting the self-hosted region docs inside Pipecat Cloud read as a sub-feature rather than the distinct offering it is sold as. The naming work in 6151ff9 framed self-hosted regions as *part of* Pipecat Enterprise, which makes Enterprise a container that will accumulate more over time — a group inside the Cloud tab cannot grow into that, so it gets a tab. The ~37 shared pages (deploy, sessions, secrets, scaling, CLI, REST, SDK) are NOT duplicated: listing a page under two tabs double-emits it into llms.txt and trips the uniqueness checks, so the new tab carries only what an operator owns and links into the shared docs. - Move pipecat-cloud/self-hosted/ to top-level enterprise/. Done before merge, so no redirects are owed: verified against the CI merge-base. images/self-hosted-architecture.svg keeps its name — "self-hosted region" remains the technical term in prose, the CLI, and the API. - Add a "Pipecat Enterprise" tab between Pipecat Cloud and API Reference, grouped Overview / Set up a region / Operate / Reference architectures. - Revert the Pipecat Cloud tab's name and drop its Enterprise group. The inline mode notes on the shared pages stay: they prevent the opposite error, a Cloud reader assuming their setup behaves like Enterprise. - Fold enterprise-support into the new tab, out of the Overview tab. - Title the hub page "Pipecat Enterprise" and open it by stating that the CLI, REST API, SDK, and image format are identical, with a pointer to where those shared docs live. - Add an Enterprise card to the Overview tab, a /enterprise vanity redirect, and retarget the moved-EKS redirect at the new reference/ path. Claude-Session: https://claude.ai/code/session_01Dp6gXWv8Uz8tQAoY6yPVgQ
A separate tab means an Enterprise reader leaves it for anything about building, deploying, or running agents. Give them a curated jump-off for the six shared pages they actually need rather than making them hunt the Pipecat Cloud sidebar. This is a card grid, not a navigation entry: listing those pages under the Enterprise tab would double-emit them into llms.txt and collide with the title/description uniqueness checks. Blurbs are checked against each target page's own description. Claude-Session: https://claude.ai/code/session_01Dp6gXWv8Uz8tQAoY6yPVgQ
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
2 participants
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.
Documentation for Pipecat Enterprise — Pipecat Cloud with your agents running on infrastructure you own, by registering a self-hosted region. Draft until the CLI 1.2.0-dependent pages are confirmed against the released build.
New: Pipecat Enterprise tab
A top-level tab (between Pipecat Cloud and API Reference) carrying only what an operator owns; the ~37 shared pages (deploy, sessions, secrets, scaling, CLI, REST, SDK) are linked from the hub, not duplicated — a page listed under two tabs double-emits into
llms.txtand trips the uniqueness checks.The offering name, technical noun ("self-hosted region"), and version floors live in
snippets/self-hosted-vars.mdx; pages import them. The architecture diagram is an SVG in the style of the existing Pipecat Cloud overview graphic.Updated
regions(architecture columns onlist; newregister,show,enroll-token,delete),secrets reference,deploy --resources/--architectureand the matchingpcc-deploy.tomlkeys,agent profiles,organizations registry-keys. All shipped inpipecatcloud1.2.0.architectureon agent create/update withnodeTypedeprecated;resources;self_hosted,supported_architectures,default_architectureon regions;sourceand theunknownreadiness state on secret sets./enterprisevanity redirect; the Overview tab gets an Enterprise card.Review notes
docs-meta-lint,mint broken-links --check-anchors --check-redirects, and Prettier;llms.txt/llms-full.txtregenerated in each commit. Merged withmain.