Secrets in Self-Hosted Regions

Reference Kubernetes Secrets in your cluster as Pipecat Cloud secret sets: env and image-pull secrets, readiness states, and what is recorded.

In , secret values never leave your cluster. Instead of uploading values to Pipecat Cloud, you create a Kubernetes Secret in your workloads namespace and reference it. The platform records only the secret’s name, region, type, and readiness — never its keys or values — and your agents use it by set name exactly as they use managed secret sets in .

Referencing a secret

1. Create the Secret in your workloads namespace

   Use whatever tooling you normally use — kubectl, a secrets operator, or your GitOps pipeline. Each key becomes an environment variable in your agent:

   kubectl -n pipecat-agents create secret generic my-agent-secrets \
     --from-literal=OPENAI_API_KEY=... \
     --from-literal=DEEPGRAM_API_KEY=...
   
2. Reference it

   pipecat cloud secrets reference my-agent-secrets --region acme-us-east
   

   The Secret’s name becomes the secret set name. Pipecat Cloud verifies, live, that the Secret exists in your region before recording the reference; referencing a Secret that does not exist fails immediately with a clear message — create first, then reference.

   In the dashboard, open Secrets and choose Reference Secret, which is available once your organization has a .

3. Use it in a deployment

   Attach the set by name, as with any secret set:

   pipecat cloud deploy --region acme-us-east --secrets my-agent-secrets
   

   or in pcc-deploy.toml:

   region = "acme-us-east"
   secret_set = "my-agent-secrets"
   

Referenced sets appear in pipecat cloud secrets list and the dashboard alongside managed sets, marked as referenced. Listing a referenced set shows no keys — Pipecat Cloud does not know them.

Image pull secrets

The same flow covers private-registry credentials. Create a docker-registry Secret and reference it; the platform detects the Secret’s type and registers it as an image pull secret:

kubectl -n pipecat-agents create secret docker-registry my-registry-creds \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=... --docker-password=...

pipecat cloud secrets reference my-registry-creds --region acme-us-east

Then use it as image_credentials in pcc-deploy.toml or --credentials on deploy, exactly as for a managed image pull secret.

Readiness

Every secret set reports a readiness state, and deploys are gated on it — a deploy that binds a set which is not ready is rejected with 409 Conflict rather than failing later when the agent starts.

Status	Meaning for a referenced set
ready	The Secret exists in your workloads namespace.
pending	The Secret does not currently exist in your cluster — it was deleted, or the cluster was rebuilt. Re-create it; the reference recovers on its own.
unknown	Pipecat Cloud could not verify the Secret because your region was unreachable. Deploys are blocked until the region reconnects; retry shortly.
failed	Not used for referenced sets.

Readiness is re-checked against your cluster whenever the set is listed or bound to a deploy. Deleting the Secret out from under a reference is safe: the set turns pending, deploys that use it are refused, and re-creating the Secret returns it to ready without re-registering.

Managing values

Because the Secret is yours, so is its lifecycle:

• Rotate a value by updating the Secret in your cluster. Running agents keep the values they started with; redeploy to pick up the change. A deploy with no other changes looks like a no-op, so use pipecat cloud deploy --force (why).
• Remove the reference with pipecat cloud secrets delete <name>. This removes only Pipecat Cloud’s record; the Secret in your cluster is untouched.
• Managed secret sets are not available in . pipecat cloud secrets set … --region <self-hosted region> is rejected with a message pointing at the reference flow, and a referenced set cannot be modified with secrets set or secrets unset.

Secret set names are unique across your organization, across both managed and referenced sets. Choose Secret names that do not collide with managed sets you use in .

After rebuilding a cluster

Referenced Secrets live only in your cluster. If you rebuild it and re-enroll the same region, Pipecat Cloud still lists every referenced set from before — but each one is now pending until you re-create the Secret in the new cluster. Re-create your Secrets before the first deploy; no re-registration is needed.