Overview
Secrets are secure variables that can store sensitive information like API keys, database credentials, and authentication tokens. LiveKit Cloud encrypts, stores, and securely injects these values into your agent containers at runtime, as environment variables.
Use a .env.local file to store secrets for your local development environment, and a tool such as python-dotenv to load them as environment variables.
Add .env and .env.* files to your .gitignore, and ensure that all sensitive values are loaded from environment variables rather than included in source code.
The starter projects for Python and Node.js both implement these best practices by default.
Managing secrets
Initial secrets are set when the create command is run. You can update secrets at any time with update-secrets. Updating secrets triggers a rolling restart of the agent, to ensure new sessions start with the updated secrets.
Secrets file
If you don't pass any arguments, the LiveKit CLI looks for an environment, and prompts you to load the secrets from that file to your agent.
The CLI looks for the following environment files:
.env.env.local.env.production
You can explicitly specify a secrets file with the --secrets-file option. The file must contain one secret per line, in KEY=value format.
lk agent create --secrets-file=path/to/secrets.env
The CLI copies all values form the file, except for LiveKit Cloud credentials.
Using the secrets flag
You can provide each secret individually with the CLI using the --secrets flag. Pass the secret in KEY=value format. To pass multiple secrets, use multiple --secrets flags.
lk agent update-secrets --secrets "SECRET_A=foo" --secrets "SECRET_B=bar"
Overwriting all secrets
By default, the CLI adds or updates the provided secrets, while leaving other existing secrets as-is. To delete all existing secrets and replace them with the provided secrets, use the --overwrite flag.
lk agent update-secrets --secrets-file=new-secrets.env --overwrite
Listing secrets
To list all secrets for an agent, use lk agent secrets. You can see the names, creation date, and last updated date for each secret. The secret values, however, aren't displayed and can't be retrieved from the CLI.
Limitations
The following limitations apply to all secrets.
Secret names
Secret names have the following restrictions:
- Must contain only letters, numbers, and underscores.
- Must not exceed 70 characters in length.
- Are case sensitive.
LiveKit recommends that you use only uppercase letters and underscores for secret names, but this is not required.
Secret values
Secret values have a maximum size of 16KB. They are stored in encrypted form, and can't be retrieved from the CLI or dashboard. The values are provided at runtime to your agent as plain environment variables.
LiveKit secrets
LiveKit Cloud provides the following environment variables automatically, to ensure your agent connects to its associated LiveKit Cloud project:
LIVEKIT_URL- Your LiveKit Cloud server URLLIVEKIT_API_KEY- An API key for your projectLIVEKIT_API_SECRET- An API secret for your project
These values are auto-generated by LiveKit Cloud and can't be set or modified as secrets.
Additional resources
The following guides cover additional topics for managing secrets in LiveKit Cloud.