Example

Take a team with $500 a week. Its Q&A route falls back to a smaller model at 90%, and its code review route has no fallback.

LiteLLM already reserves each request's cost, counts team spend across replicas and refuses requests past the budget. Brownout adds five things.

• Warnings at any percentage: each team and route sets its own tiers, logged once per budget window across replicas. LiteLLM's own budget alerts fire at 85% and 95%.
• Downgrades on the team's total: a route switches to its fallback at the percentage you set. LiteLLM's budget fallbacks switch only when a key exhausts a per-model budget.
• Coding agents included: chat, text completion, Anthropic's /v1/messages, OpenAI's /v1/responses and Google's generateContent all downgrade, so a Claude Code or Codex session carries on with the fallback mid-task.
• Checked fallbacks: brownout switches only to a fallback the gateway serves and prices, and that the caller's key and team may call.
• Disclosure: x-brownout-* headers and the spend logs name the model that answered and why.

How it works

One manifest, brownout.yaml, holds every team's budget, tiers and fallbacks. It lives in your repo next to the gateway config, so a policy change goes through code review, and brownout check runs it in CI. LiteLLM keeps enforcing the budget, and brownout picks the model that serves each request.

Requirements

Brownout governs every model call on the gateway, so the gateway needs a few things in place. init checks each one and prints the fix.

• Every key that calls a model belongs to a team, and that team is in the manifest.
• Budgets sit on teams, never on keys.
• Clients use LiteLLM's unified routes. Provider pass-through routes, realtime, batches, fine-tuning and search tools are refused.
• fail_closed_budget_enforcement is on, and coordination_redis points at a Redis.
• LiteLLM is 1.101.6 to 1.106, pinned by image tag.

A gateway without Redis needs one that shares its REDIS_PASSWORD, such as this service.

services:
  redis:
    image: redis:7
    command: ["sh", "-c", "exec redis-server --requirepass \"$$REDIS_PASSWORD\" --appendonly yes --maxmemory-policy noeviction"]
    env_file:
      - .env

Get started

1. Run init against your gateway. Paste the master key on the first line.

read -rs LITELLM_MASTER_KEY && typeset +x LITELLM_MASTER_KEY
BROWNOUT_INIT_KEY=$(curl -sSf http://localhost:4000/user/new \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H "Content-Type: application/json" \
  -d '{"user_id": "brownout-init", "user_role": "proxy_admin_viewer"}' | jq -er .key) \
  && export BROWNOUT_INIT_KEY
uvx --from litellm-brownout brownout init --gateway http://localhost:4000 --gateway-config config.yaml

2. Fix what it lists, rerun it with --write, then check the files.

uvx --from litellm-brownout brownout check --gateway-config brownout.config.yaml --manifest brownout.yaml
curl -sSf http://localhost:4000/user/delete \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H "Content-Type: application/json" \
  -d '{"user_ids": ["brownout-init"]}'

3. Build the gateway image with brownout and run it on the new files.

FROM docker.litellm.ai/berriai/litellm:v1.106.1
RUN python -m ensurepip --upgrade && python -m pip install --no-deps litellm-brownout==0.1.0

services:
  litellm:
    build: .
    command: ["--config", "/app/brownout.config.yaml", "--port", "4000"]
    environment:
      BROWNOUT_MANIFEST: /app/brownout.yaml
    volumes:
      - ./brownout.config.yaml:/app/brownout.config.yaml:ro
      - ./brownout.yaml:/app/brownout.yaml:ro

4. Send one request with a team's key.

curl -s -i http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer {team key}" -H "Content-Type: application/json" \
  -d '{"model": "{model}", "messages": [{"role": "user", "content": "hi"}], "max_tokens": 20}' \
  | grep -io '^x-brownout-[a-z-]*: [^[:cntrl:]]*\|"reason": *"[a-z_]*"'

What happened:

• init read the gateway as a read-only brownout-init user and listed every request brownout would refuse, with the fix for each. OpenRouter models need a price, which one command prints.
• --write created brownout.yaml, the manifest, and brownout.config.yaml, your config with brownout's settings. check validated both, and the brownout-init user was deleted.
• The response names the model that answered in x-brownout-route-served. A refused request prints its reason instead. The master key belongs to no team, so brownout refuses it.

Your first fallback

Add a route under your team in brownout.yaml. Fill in each {placeholder}.

teams:
  "{team}":
    routes:
      "{route}":
        fallback: "{fallback}"
        degrade_at: 90

Add {fallback} to the team's model list in LiteLLM, run brownout check again and restart the gateway. For models added in the admin UI, check reads the gateway with a viewer key.

BROWNOUT_INIT_KEY=$(curl -sSf http://localhost:4000/user/new \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H "Content-Type: application/json" \
  -d '{"user_id": "brownout-init", "user_role": "proxy_admin_viewer"}' | jq -er .key) \
  && export BROWNOUT_INIT_KEY
uvx --from litellm-brownout brownout check --gateway http://localhost:4000 --gateway-config brownout.config.yaml --manifest brownout.yaml
curl -sSf http://localhost:4000/user/delete \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H "Content-Type: application/json" \
  -d '{"user_ids": ["brownout-init"]}'

Once the team's spend passes 90%, every {route} response carries these headers.

x-brownout-route-served: {fallback}
x-brownout-budget-tier: 90
x-brownout-degraded-from: {route}
x-brownout-degradation-reason: degrade_tier_reached

The fallback receives everything the route sends, tools and images included, so try it on the route's real requests first. To point Claude Code or Codex at a route, follow their setup. The lab drains a budget without spending anything.

Limits

• Only text generation downgrades: embeddings, images, audio and Codex's /v1/responses/compact keep their model at any spend.
• Requests name a model group: a router alias, a wildcard group such as openai/* or a list of models gets a 503.
• No router fallbacks: a provider error on the chosen model reaches the caller. Failover between deployments of one model group still works.
• The reservation comes first: LiteLLM reserves each request's worst case on the model the caller asked for. Set max_tokens, or a large request near the ceiling gets LiteLLM's 429 before the downgrade.
• Redis is on the request path: while LiteLLM cannot reach Redis it refuses every budgeted request.

The full list covers the rest. If you run brownout on a real workload, open an issue with the model pair, budget window, threshold and LiteLLM version, and say whether the fallback stayed useful.

Documentation

• Configuration: settings, manifest keys, rules and init options.
• Enforcement: refusals, headers and events.
• Limits: every known limit.
• Claude Code and Codex: pointing both tools at a route.
• Design: how the modules fit together.
• Security: what brownout reads and writes, and how to verify a release.
• Contributing: the tests, the supported LiteLLM releases and releasing.

License

MIT