Skip to content

feat: litellm-master-key #378

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yxtay merged 2 commits into from
Jul 29, 2026
Merged

feat: litellm-master-key #378

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a5f84d5
feat: litellm-master-key
yxtay Jul 29, 2026
c9f3783
Update config.yaml
yxtay Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion agent/.env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,6 @@ SEARXNG_URL=
TAVILY_API_KEY=

LITELLM_DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/litellm
LITELLM_MASTER_KEY=sk-litellm-master-key
# generate using `openssl rand -hex 32`
LITELLM_MASTER_KEY=
LITELLM_SALT_KEY=
Comment on lines +19 to +21

@coderabbitai coderabbitai Bot Jul 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== candidate files =="
git ls-files | rg '(^|/)(\.env\.example|compose\.ya?ml)$' || true

echo
echo "== agent/.env.example =="
if [ -f agent/.env.example ]; then
  nl -ba agent/.env.example | sed -n '1,80p'
fi

echo
echo "== agent compose references =="
if [ -f agent/compose.yaml ]; then
  nl -ba agent/compose.yaml | sed -n '1,220p'
elif [ -f agent/docker-compose.yml ]; then
  nl -ba agent/docker-compose.yml | sed -n '1,220p'
elif [ -f agent/docker-compose.yaml ]; then
  nl -ba agent/docker-compose.yaml | sed -n '1,220p'
else
  fd -i 'compose.*ya?ml' agent -x sh -c 'echo "--- $1"; nl -ba "$1" | sed -n "1,220p"' sh {}
fi

echo
echo "== LITELLM_MASTER_KEY / LITELLM_SALT_KEY usages =="
rg -n -H 'LITELLM_(MASTER_|SALT_)KEY|master_key|salt' . --glob '!node_modules' --glob '!dist' --glob '!build' | sed -n '1,200p'

Repository: yxtay/docker-stacks

Length of output: 847

🌐 Web query:

LiteLLM master_key setting documentation

💡 Result:

The master_key in LiteLLM is the proxy's administrative credential [1][2][3]. It is used to authenticate admin API calls, serve as the password for the Admin UI, and manage virtual keys [4][2][5][3]. Configuration You can set the master key using either an environment variable or the configuration file [4][2]: 1. Environment Variable: Set the LITELLM_MASTER_KEY variable (must start with sk-) [4][5][3]. 2. Config File: Specify it under general_settings: master_key in your config.yaml [4][6]. If both are set, the value in the config file takes precedence [2]. Important Considerations - Security: The master key bypasses standard model-level checks and gives access to every model on the proxy [1]. It should be treated as a highly sensitive operator credential [1]. - Encryption: In some deployments, if a separate LITELLM_SALT_KEY is not configured, the master key is also used to encrypt sensitive data (such as API keys and credentials) at rest in the database [2]. If the master key is used for this purpose, rotating it requires a specific re-encryption process to prevent losing access to stored credentials [2]. - Best Practices: It is recommended to keep the key in a secure secret manager and follow the official master key rotation documentation when updating it [2][3].

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '1,120p' agent/.env.example
echo
sed -n '1,220p' agent/compose.yaml
echo
printf '\nLITELLM usages in agent:\n'
rg -n -H 'LITELLM_(MASTER_|SALT_)KEY|master_key|salt' agent --glob '!node_modules' --glob '!dist' --glob '!build' || true

Repository: yxtay/docker-stacks

Length of output: 6002

🌐 Web query:

LiteLLM v1.94.0 environment variables LITELLM_MASTER_KEY configured

💡 Result:

In LiteLLM, the LITELLM_MASTER_KEY environment variable serves as the primary administrative key for the LiteLLM Proxy [1][2][3]. It grants full admin access, allowing you to perform operations such as creating, blocking, or unblocking virtual keys [1][3][4]. Key details regarding the LITELLM_MASTER_KEY: Configuration and Precedence - Environment Variable: You can set the master key directly via the environment variable LITELLM_MASTER_KEY (e.g., export LITELLM_MASTER_KEY="sk-...") [2][3]. - Configuration File: You can also specify the master key in your config.yaml file under the general_settings section using master_key: <key> or master_key: os.environ/LITELLM_MASTER_KEY [1][3]. - Precedence: If both are configured, the value defined in general_settings.master_key in the config.yaml file generally takes precedence over the environment variable [5]. Operational Usage - Authentication: The master key is used to authenticate requests to administrative endpoints, such as the key management APIs (/key/generate, /key/block, /key/unblock) [1][4]. It is passed in the Authorization header as a Bearer token: Authorization: Bearer LITELLM_MASTER_KEY [1]. - Admin UI: The master key acts as the password for the Admin UI when accessing the proxy [6]. - Security Best Practices: It is highly recommended to use a strong, unique key starting with sk- [1][3]. Always avoid hardcoding the key in configuration files; use environment variables or secret management systems (e.g., AWS Secret Manager) instead [3][7]. - Versioning Note: LiteLLM v1.94.0 includes updates to proxy behavior, including fixes related to master key routing and startup initialization, ensuring that the master key configuration is preserved correctly during the proxy's lifecycle [8][9].

Citations:

Do not commit the default LiteLLM master key.

agent/compose.yaml loads .env into the LiteLLM service, and LITELLM_MASTER_KEY is the admin/proxy credential. Copying this example unchanged can deploy the shared placeholder sk-litellm-master-key; leave it empty or a non-credential placeholder and require generated per-deployment values.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@agent/.env.example` around lines 19 - 21, Update the LITELLM_MASTER_KEY
example in the environment template to be empty or a clearly non-credential
placeholder, and document that each deployment must provide its own generated
value. Keep the existing LITELLM_SALT_KEY guidance unchanged.

6 changes: 3 additions & 3 deletions agent/litellm/config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ router_settings:
role: system
default_fallbacks: [complex, medium, simple]
fallbacks:
- reasoning: complex
- complex: medium
- medium: simple
- reasoning: [complex, medium, simple]
- complex: [medium, simple]
- medium: [simple]

model_list:
- model_name: auto
Expand Down