> ## Documentation Index
> Fetch the complete documentation index at: https://daily-ms-pcc-self-hosted.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

export const hostedName = "Daily-hosted regions";

export const productNameSingular = "self-hosted region";

export const productName = "self-hosted regions";

In {productName}, 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](/pipecat-cloud/fundamentals/secrets) in {hostedName}.

## Referencing a secret

<Steps>
  <Step title="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:

    ```bash theme={null}
    kubectl -n pipecat-agents create secret generic my-agent-secrets \
      --from-literal=OPENAI_API_KEY=... \
      --from-literal=DEEPGRAM_API_KEY=...
    ```
  </Step>

  <Step title="Reference it">
    ```bash theme={null}
    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 {productNameSingular}.
  </Step>

  <Step title="Use it in a deployment">
    Attach the set by name, as with any secret set:

    ```bash theme={null}
    pipecat cloud deploy --region acme-us-east --secrets my-agent-secrets
    ```

    or in `pcc-deploy.toml`:

    ```toml theme={null}
    region = "acme-us-east"
    secret_set = "my-agent-secrets"
    ```
  </Step>
</Steps>

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:

```bash theme={null}
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](/pipecat-cloud/fundamentals/deploy#when-a-deploy-does-not-replace-running-agents)).
* **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 {productName}.** `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`.

<Note>
  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 {hostedName}.
</Note>

## 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.