Upgrading dynamo-guard and litellm-dynamo
dynamo-guard is the one-command LiteLLM proxy with a hard dollar cap, running in Control Mode (Live, no money). litellm-dynamo is the LiteLLM plugin it runs, which you can also install in your own LiteLLM proxy (Live). The current versions are guard 4.2.0 and litellm-dynamo 1.7.0, on LiteLLM 1.104.0. Neither is published; both run from a clone.
Back to Changelog, versioning, deprecation and migration.
Which versions go together
Each guard version pins one litellm-dynamo version and one LiteLLM version.
| Guard | litellm-dynamo | LiteLLM | What the guard version added |
|---|---|---|---|
| 3.0.0 | 1.1.0 | 1.61.20 | One cap, in dollars (GUARD_CAP_USD); GUARD_CAP_UNITS removed |
| 3.1.0 | 1.2.0 | 1.91.4 | up resumes the same session after down, a reboot or a crash; reset |
| 3.2.0 | 1.3.0 | 1.91.4 | The durable meter journal: a delivered request is billed exactly once after a crash |
| 3.3.0 | 1.4.0 | 1.91.4 | Streamed responses journaled before their last chunk; the scheduler runs in the guard host |
| 4.0.0 | 1.5.0 | 1.104.0 | The LiteLLM move, two runtimes (native and container), a per-session LiteLLM master key |
| 4.1.0 | 1.6.0 | 1.104.0 | GUARD_A2A=1 installs the agent gateway's runtime |
| 4.2.0 | 1.7.0 | 1.104.0 | Serving declared A2A agents (GUARD_A2A_AGENTS); canonical credentials only |
What changed from guard 3.x to 4.2.0
- LiteLLM 1.91.4 → 1.104.0. Installs are hash-locked and use binary wheels only. When the
pinned LiteLLM or plugin version differs from what the guard's environment holds, up rebuilds it.
- Two runtimes.
GUARD_RUNTIMEisauto(default),nativeorcontainer. On Intel macOS,
where LiteLLM 1.104.0 has no wheel set, auto runs the proxy in the LiteLLM image pinned by digest; this needs Docker Desktop. Elsewhere it runs natively. GUARD_RUNTIME=container is for macOS only.
- A LiteLLM master key. LiteLLM 1.104 will not start without one.
upwrites a per-session key
into the session directory and never prints it. Your clients keep sending the guard key that up prints.
- Fewer open routes. Only
/v1/chat/completions,/v1/completionsand/v1/modelsare
served, plus /a2a/{name} and /a2a/{name}/message/send for each agent declared in GUARD_A2A_AGENTS (4.2.0). LiteLLM's management and provider pass-through routes answer 401; under 1.91.4 they were open on the proxy port. The native proxy listens on 127.0.0.1 only.
- Canonical credentials only (4.2.0). litellm-dynamo 1.7.0 refuses a credential whose encoding
is not canonical, so a second string form of one credential never verifies.
- Optional A2A agents (4.1.0, 4.2.0). Nothing changes unless you set
GUARD_A2A=1and
GUARD_A2A_AGENTS.
If you come from guard 2.x: GUARD_CAP_UNITS was removed in 3.0.0 and setting it refuses to start. Unset it and set GUARD_CAP_USD instead.
Steps for guard users
- With your current guard, end the session cleanly.
resetsettles the session and ends it. It
refuses while delivered requests are journaled but not yet billed; then run up first (it replays them) and reset again.
cd "$DYNAMO_REPO/quickstart/dynamo-guard"
pwd
./dynamo-guard reset
./dynamo-guard down
- Update your clone to this release.
- On Intel macOS, start Docker Desktop.
- See what
upwould install, then start the guard. Keep the sameGUARD_CAP_USD: a cap that
differs from a running session's cap refuses.
cd "$DYNAMO_REPO/quickstart/dynamo-guard"
pwd
./dynamo-guard plan
./dynamo-guard up
- Point your client at the base URL and key that
upprints.
Steps for LiteLLM operators
If you run litellm-dynamo in your own LiteLLM proxy:
- Move LiteLLM to 1.104.0 together with litellm-dynamo 1.5.0 or later; the plugin's
litellm
extra pins litellm==1.104.0.
- LiteLLM 1.104 needs a master key. Send the Dynamo credential in the
x-dynamo-allowanceheader
beside a LiteLLM key, or use a custom auth such as the guard's dynamo_auth.py if your clients send the credential as their API key.
- For litellm-dynamo 1.7.0, use Python 3.10 to 3.13. Signing now uses
coincurveinstead of
ecdsa; signatures are byte-identical.
- If you price A2A agents, use the
agentsrows ofprice-table/1.1.0(litellm-dynamo 1.5.0 and
later); a 1.0.0 table is still accepted. If your core requires own hops (the default in money modes from owner-api 1.8.0), give DynamoGuard a hop_signer so child opens carry the signed hop.
Compatibility guarantees
- litellm-dynamo's own API did not change in the LiteLLM move.
- A journal from a crash is replayed with its original request references, so each delivered
request is billed exactly once across an upgrade or restart.
- Every refusal is fail-closed: an unpriced model or agent, an unverifiable credential or an
exhausted cap answers 402 before anything reaches the upstream.