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

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

pcc secrets set my-secrets SECRET_NAME_3 secret-value-3

​

Special characters

There are several ways to specify key-value pairs:

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

   Copy

   Ask AI

   pcc secrets set my-secrets KEY1=simple KEY2=value
   

2. Values with spaces:

   Copy

   Ask AI

   pcc secrets set my-secrets KEY1="value with spaces"
   # or
   pcc secrets set my-secrets "KEY1=value with spaces"
   

3. Values containing equals signs:

   Copy

   Ask AI

   pcc secrets set my-secrets KEY1="value=with=equals"
   # or
   pcc secrets set my-secrets KEY1==value=with=equals
   

4. Values containing quotes:

   Copy

   Ask AI

   pcc secrets set my-secrets KEY1="value with \"quotes\""
   # or
   pcc secrets set my-secrets 'KEY1=value with "quotes"'
   

5. Values containing backslashes:

   Copy

   Ask AI

   pcc secrets set my-secrets 'KEY1=value with \backslashes'
   # or
   pcc 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.

pcc secrets list

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

pcc secrets list my-secrets

​

Removing a secret

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

pcc secrets unset my-secrets SECRET_NAME

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

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

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

​

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
pcc 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

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:

pcc 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:

pcc deploy my-first-agent your-docker-repository/my-first-agent:0.1 --secrets my-secrets

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

ENV MY_SECRET=secret-value

COPY ./requirements.txt requirements.txt
RUN pip install --no-cache-dir --upgrade -r requirements.txt
COPY ./bot.py bot.py

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