Skip to main content
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 .

​
Creating a secret set and adding secrets

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. 
pipecat cloud secrets set my-secrets SECRET_NAME_3 secret-value-3
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.

​
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:
StatusMeaning
pendingThe secret has been accepted but is not yet provisioned in the target region.
readyThe secret is fully provisioned and safe to bind to a deployment.
failedProvisioning could not complete. Re-create the secret or contact support if the problem persists.
Readiness is included in GET /v1/secrets (list) and GET /v1/secrets/{setName} (single) responses on the REST API. 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.
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.

​
Regions

Secret sets are created in a specific region. By default, secrets are created in us-west if no region is specified. 
pipecat cloud secrets set my-secrets SECRET_NAME secret-value --region us-east
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).

​
Special characters

There are several ways to specify key-value pairs:
  1. Simple values (no spaces or special characters): 
    pipecat cloud secrets set my-secrets KEY1=simple KEY2=value
  2. Values with spaces: 
    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: 
    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: 
    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: 
    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. 
pipecat cloud secrets list
You can pass an optional secret set name to view the secret keys within that set. Values are not displayed. 
pipecat cloud secrets list my-secrets

​
Removing a secret

To remove a secret from a set, use the unset command. 
pipecat cloud secrets unset my-secrets SECRET_NAME
To remove a secret-set entirely, use the delete command: 
pipecat cloud secrets delete my-secrets

​
Image pull secrets

Image pull secrets are only needed when deploying from your own container registry. If you’re using cloud builds, you can skip this section.
Image pull secrets are used to authenticate with private container registries when deploying agents. Create one with the CLI: 
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: 
pipecat cloud secrets image-pull-secret <secret-name> <registry-url> --region us-east
Then reference the secret in your pcc-deploy.toml: 
agent_name = "my-agent"
image = "<registry-url>/my-agent:0.1"
image_credentials = "<secret-name>"
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.
For registry-specific setup instructions, see our Container Registry guides.

​
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: 
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:
pipecat cloud deploy --secrets my-secrets
  1. Specify a secret_set key in your pcc-deploy.toml file:
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: 
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.