> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Providing your agent with sensitive information

Most agents will require access to sensitive information, such as API keys, passwords, and other secrets.
To keep this information secure, we recommend using Pipecat Cloud's secret management feature.

Secrets are created as "sets" of key-value pairs, and defined at the user / organization level.
This means that secrets can be shared across all agent deployments within the same user workspace or organization.

To access secrets, your deployment must specify the secret set to use.

## Working with secrets

Secrets can be managed via either the CLI or the [Dashboard <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://pipecat.daily.co).

### Creating a secret set and adding secrets

```bash theme={null}
pipecat cloud secrets set my-secrets SECRET_NAME secret-value SECRET_NAME_2 secret-value-2
```

This command will create or modify the secret set with the name `my-secrets`, and add or update the key-value pairs `SECRET_NAME` and `SECRET_NAME_2`.

You can add additional secrets to the set by specifying more key-value pairs.

```bash theme={null}
pipecat cloud secrets set my-secrets SECRET_NAME_3 secret-value-3
```

<Info>
  Whenever a secret is added or updated in an existing set, any deployments
  using that set will need to be redeployed to access the new values.
</Info>

#### Provisioning and readiness

Creating or updating a secret set is **asynchronous**. The CLI/API returns
immediately (HTTP `202 Accepted`) once your values have been stored, but the
set is then provisioned into the target region in the background. Provisioning
typically completes within a few seconds.

Each secret set has one of three readiness states:

| Status    | Meaning                                                                                                                   |
| --------- | ------------------------------------------------------------------------------------------------------------------------- |
| `pending` | The secret has been accepted but is not yet provisioned in the target region.                                             |
| `ready`   | The secret is fully provisioned and safe to bind to a deployment.                                                         |
| `failed`  | Provisioning could not complete. Re-create the secret or [contact support](mailto:help@daily.co) if the problem persists. |

Readiness is included in `GET /v1/secrets` (list) and `GET /v1/secrets/{setName}`
(single) responses on the [REST API](/api-reference/pipecat-cloud/rest-reference/endpoint/secret-list-all).
Deploys, updates, and any other operation that binds a secret set to an agent
are gated on the `ready` state — a request to deploy with a `pending` or
`failed` set is rejected with HTTP `409 Conflict` rather than failing later
when the agent starts.

<Tip>
  In an automated pipeline that creates a secret immediately before deploying
  (e.g., CI), poll `GET /v1/secrets/{setName}` until `status` is `ready` before
  triggering the deploy. The window is usually only a few seconds, but guarding
  the deploy avoids a transient `409`.
</Tip>

#### Regions

Secret sets are created in a specific region. By default, secrets are created in `us-west` if no region is specified.

```bash theme={null}
pipecat cloud secrets set my-secrets SECRET_NAME secret-value --region us-east
```

<Warning>
  Secret set names are globally unique, but each secret set exists in only one
  region. Secrets must be in the same region as the agents that use them. For
  multi-region deployments, create separate secret sets for each region (e.g.,
  `my-secrets-us-west`, `my-secrets-us-east`).
</Warning>

#### Special characters

There are several ways to specify key-value pairs:

1. **Simple values** (no spaces or special characters):

   ```bash theme={null}
   pipecat cloud secrets set my-secrets KEY1=simple KEY2=value
   ```

2. **Values with spaces**:

   ```bash theme={null}
   pipecat cloud secrets set my-secrets KEY1="value with spaces"
   # or
   pipecat cloud secrets set my-secrets "KEY1=value with spaces"
   ```

3. **Values containing equals signs**:

   ```bash theme={null}
   pipecat cloud secrets set my-secrets KEY1="value=with=equals"
   # or
   pipecat cloud secrets set my-secrets KEY1==value=with=equals
   ```

4. **Values containing quotes**:

   ```bash theme={null}
   pipecat cloud secrets set my-secrets KEY1="value with \"quotes\""
   # or
   pipecat cloud secrets set my-secrets 'KEY1=value with "quotes"'
   ```

5. **Values containing backslashes**:
   ```bash theme={null}
   pipecat cloud secrets set my-secrets 'KEY1=value with \backslashes'
   # or
   pipecat cloud secrets set my-secrets "KEY1=value with \\backslashes"
   ```

#### Important Notes

* Keys must contain only alphanumeric characters, underscores, and hyphens (`[a-zA-Z0-9_-]`)
* Keys must not exceed 64 characters in length
* Values are preserved exactly as entered, including any spaces, quotes, or special characters
* If a value contains spaces, you must either:
  * Enclose the value in quotes: `KEY="value with spaces"`
  * Enclose the entire key-value pair in quotes: `"KEY=value with spaces"`
* When using quotes within values, you can either:
  * Use single quotes around the pair containing double quotes: `'KEY=value "quoted" here'`
  * Use escaped double quotes: `KEY="value \"quoted\" here"`

### List secret sets

You can view a list of available secret sets in your currently selected workspace or organization.

```bash theme={null}
pipecat cloud secrets list
```

You can pass an optional secret set name to view the secret keys within that set. Values are not displayed.

```bash theme={null}
pipecat cloud secrets list my-secrets
```

### Removing a secret

To remove a secret from a set, use the `unset` command.

```bash theme={null}
pipecat cloud secrets unset my-secrets SECRET_NAME
```

To remove a secret-set entirely, use the `delete` command:

```bash theme={null}
pipecat cloud secrets delete my-secrets
```

### Image pull secrets

<Note>
  Image pull secrets are only needed when deploying from your own container
  registry. If you're using [cloud builds](/pipecat-cloud/guides/cloud-builds),
  you can skip this section.
</Note>

Image pull secrets are used to authenticate with private container registries when deploying agents. Create one with the CLI:

```bash theme={null}
pipecat cloud secrets image-pull-secret <secret-name> <registry-url>
```

Running this command will prompt you for account credentials.
The CLI accepts credentials as `username:token` and base64-encodes them before
storing the image pull secret. If you create an image pull secret through the
dashboard or API, the auth value must already be base64-encoded.

Like regular secret sets, image pull secrets are region-specific. Specify the region with the `--region` flag:

```bash theme={null}
pipecat cloud secrets image-pull-secret <secret-name> <registry-url> --region us-east
```

Then reference the secret in your `pcc-deploy.toml`:

```toml theme={null}
agent_name = "my-agent"
image = "<registry-url>/my-agent:0.1"
image_credentials = "<secret-name>"
```

<Info>
  To update an image pull secret's credentials, simply re-run the
  `image-pull-secret` command with the same name. Image pull secrets must be in
  the same region as the agents that use them.
</Info>

For registry-specific setup instructions, see our [Container Registry guides](../guides/container-registries/overview).

## Accessing secrets in your agent code

Secrets are mounted as environment variables in your agent process.

For example, if you define a secret with the key MY\_SECRET, you can access it in your agent code like so:

```python theme={null}
import os

secret_value = os.environ.get('MY_SECRET')
```

When deploying, you have two options to specify which secret set to use:

1. Specify a secret set as part of your deploy command:

```bash theme={null}
pipecat cloud deploy --secrets my-secrets
```

2. Specify a `secret_set` key in your `pcc-deploy.toml` file:

```toml theme={null}
agent_name = "my-first-agent"
secret_set = "my-secrets"
```

With either approach, the CLI will automatically inject the secrets from the specified set into your agent deployment as environment variables.

## Other methods

If you prefer to manage secrets outside of Pipecat Cloud, you can use environment variables or other secret management tools.

You could, for example, set environment variables in your Dockerfile:

```dockerfile theme={null}
FROM dailyco/pipecat-base:latest

# Enable bytecode compilation
ENV UV_COMPILE_BYTECODE=1

# Copy from the cache instead of linking since it's a mounted volume
ENV UV_LINK_MODE=copy

# Set the secret as an environment variable
ENV MY_SECRET=secret-value

# Install the project's dependencies using the lockfile and settings
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-dev

# Copy the application code
COPY ./bot.py bot.py
```

We recommend using Pipecat Cloud's built-in management for the most secure and versatile method of managing secrets.