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.

​
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 used to authenticate with private Docker registries when deploying agents. They can be passed as part of the deploy command. 
pipecat cloud secrets image-pull-secret my-image-pull-secret https://index.docker.io/v1/
Running this command will prompt you for account credentials. You can optionally encode your credentials in base64 with the --base64encode flag.
Unlike secret sets, image pull secrets can not be updated. You must delete and recreate the secret if you need to change the credentials.

​
Using Private Docker Hub Images with Pipecat Cloud

If you want to use private Docker Hub images with your Pipecat Cloud deployment, follow these steps: Step 1: Create a Docker Hub Access Token
  1. Log in to Docker Hub
  2. Go to Account Settings → Personal access tokens
  3. Click “Generate new token”
  4. Name it (e.g., “pcc-images”) and set permissions (e.g. “Read & Write”)
  5. Copy and save the generated token securely
Step 2: Make Your Docker Hub Image Private
  1. Go to your repository on Docker Hub
  2. Click “Settings”
  3. Under “Visibility,” change from “Public” to “Private”
  4. Save changes
Step 3: Set Up Image Pull Secret in Pipecat Cloud 
# Create image pull secret
pipecat cloud secrets image-pull-secret my-image-pull-secret https://index.docker.io/v1/
# Enter your Docker Hub username when prompted
# Enter your access token (not password) when prompted
dockerhub-access is the name of your image pull secret, so name it whatever you’d like.
Step 4: Deploy Your Agent with the Image Pull Secret Update your pcc-deploy.toml file: 
agent_name = "my-first-agent"
image = "your-docker-repository/my-first-agent:0.1"
image_credentials = "my-image-pull-secret"
secret_set = "my-secrets"

[scaling]
	min_agents = 0
	max_agents = 5
Finally, deploy your agent with the pcc-deploy.toml configuration: 
pipecat cloud deploy

​
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 my-first-agent your-docker-repository/my-first-agent:0.1 --secrets my-secrets
  1. Specify a secret_set key in your pcc-deploy.toml file:
agent_name = "my-first-agent"
image = "your-docker-repository/my-first-agent:0.1"
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.