LiveKit docs › Agent deployment › Secrets management --- # Secrets management > Manage secrets for your LiveKit Cloud agent deployments. ## Overview Secrets are secure variables and files 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. Most secrets are injected as environment variables, but you can also [mount files as secrets](#file-mounted-secrets) if needed. > ℹ️ **Keep secrets out of version control** > > Use a `.env.local` file to store secrets for your local development environment, and a tool such as [python-dotenv](https://github.com/theskumar/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](https://github.com/livekit-examples/agent-starter-python) and [Node.js](https://github.com/livekit-examples/agent-starter-node) both implement these best practices by default. ## Managing secrets Initial secrets are set when the [`create`](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent.md#create) command is run. You can update secrets at any time with [`update-secrets`](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent.md#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. ```shell lk agent create --secrets-file=path/to/secrets.env ``` The CLI copies all values from the file, [except for LiveKit Cloud credentials](#livekit-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. ```shell 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. ```shell 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 URL - `LIVEKIT_API_KEY` - An API key for your project - `LIVEKIT_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. ## File-mounted secrets In certain cases, you might need to load an entire file as a secret, and make it available in your agent's environment as a local file. For example, providers such as Google use JSON files for authentication credentials. Use `--secret-mount ./path/to/filename` to mount a local file as a secret when creating or updating secrets. The file is mounted in the agent container at `/etc/secrets/`, preserving its original filename. For example, the following command adds a secret file at `/etc/secrets/google-application-credentials.json` in the agent container: ```shell lk agent update-secrets --secret-mount ./google-application-credentials.json ``` ## Additional resources The following guides cover additional topics for managing secrets in LiveKit Cloud. - **[Agent CLI reference](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent.md)**: Reference for the agent deployment commands in the LiveKit CLI. --- This document was rendered at 2026-06-07T11:32:56.904Z. For the latest version of this document, see [https://docs.livekit.io/deploy/agents/secrets.md](https://docs.livekit.io/deploy/agents/secrets.md). To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).