The guard - dynamo-guard
Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.
Your agent cannot spend past a dollar cap you set - in one command, with one variable (GUARD_CAP_USD, default 5). This is the spend-control front door: no payment setup, no money - Control Mode end to end. The guard runs on your machine: a local LiteLLM proxy with the litellm-dynamo plugin, behind a capped stream. Prompts and completions pass only between your tool, the proxy and your model provider (or the built-in mock); the engine receives only metering facts (stream ids, unit counts).
There are two editions, and neither is published:
- The repository guard (
quickstart/dynamo-guard, guard 4.2.0) runs its
own local engine. It works today from a clone; make guard starts it.
- The hosted-core guard (
packages/sdk-open/artifact/guard, guard 3.2.0)
points at your Dynamo instance. It is packaged to publish as @dynamoprotocol/guard, so npx @dynamoprotocol/guard up works only once it is published. It installs litellm-dynamo 1.3.0 from the package index, where that is not published either; set GUARD_PLUGIN_WHEEL to a locally built wheel to run it from a clone.
Try it
These are the commands from the repository guard's README. You need Node 22.12 or later, pnpm, curl and Python 3.10 to 3.13; on an Intel Mac, Docker Desktop too (LiteLLM 1.104.0 has no Intel macOS wheels, so the proxy runs in the pinned LiteLLM image). Set DYNAMO_REPO to your clone. With no provider key, requests go to a built-in mock upstream.
cd "$(mktemp -d)"
pwd
export GUARD_CAP_USD=5
"$DYNAMO_REPO/quickstart/dynamo-guard/dynamo-guard" up
KEY="$("$DYNAMO_REPO/quickstart/dynamo-guard/dynamo-guard" key)"
curl -sf "http://127.0.0.1:${GUARD_PORT:-4000}/v1/chat/completions" \
-H "Authorization: Bearer $KEY" -H "content-type: application/json" \
-d '{"model":"dynamo-guard","messages":[{"role":"user","content":"hello"}]}'
echo
"$DYNAMO_REPO/quickstart/dynamo-guard/dynamo-guard" status
up prints a base URL and a key:
dynamo-guard 4.2.0 is UP — hard dollar cap, zero payment setup (Control Mode).
Base URL http://127.0.0.1:4000/v1
Model dynamo-guard
API key eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJkeW5hbW8t… (allowance credential)
Cap $5.00 — priced per model, enforced before each request
Stream stm_…
Upstream offline mock upstream
Point Cursor, Cline, Aider, a LangGraph or CrewAI graph - anything that speaks the OpenAI API - at that base URL with that key. Your provider key stays local (the guard reads it from your environment and never writes it to a file). dynamo-guard status shows the dollars available now (the proxy's local ledger, then the engine's figure); dynamo-guard down stops the guard.
The hosted-core guard takes DYNAMO_CORE_URL, OWNER_API_TOKEN and PLUGIN_WIRE_TOKEN for your instance (or reads them from a .env file in the working directory), and refuses to start if your instance has no guard protections configured for the guard node: the operator sets CORE_NODE_PROTECTIONS and restarts the instance.
How the dollar cap holds
- Priced per model. The guard ships a price table with one row per
provider-default model, each carrying its source URL and date (GUARD_PRICE_TABLE points at your own). If the model the guard routes to has no row, the guard refuses to start; a request for any other model without a row gets HTTP 402. There is no fallback price.
- Reserved before forwarding. Each request's worst case - a
conservative prompt bound plus max_tokens (default 4096 is injected when a request sets none) - is reserved against the remaining cap in-process. If it does not fit, the tool gets HTTP 402 and the provider is never called. Actual usage replaces the reservation; a failed call costs nothing.
- Bounded residue. Two sources can still overshoot: several proxies
sharing one stream between syncs, and a provider that bills beyond max_tokens. The engine's cap halts the stream at the next sync in both cases.
- Paced before forwarding.
GUARD_RATE_UNITS_PER_SEC(default 100000
micro-USD per second) and GUARD_RATE_BURST_SECONDS (default 60) bound how fast the cap can be spent; a request that arrives too early gets HTTP 429 with Retry-After, and the provider is never called.
Restarts keep your session
up after down, a reboot or a crash resumes the same budget, stream and key; the remaining cap is unchanged except for work that was metered. Starting with a different GUARD_CAP_USD refuses and tells you how to proceed. reset ends the session on purpose - it revokes the stream, closes the budget, prints the final reconciliation line - and starts a fresh one:
cd my-project
pwd
GUARD_CAP_USD=10 "$DYNAMO_REPO/quickstart/dynamo-guard/dynamo-guard" reset
Since 3.2.0 each delivered request is journaled in the session directory before it is billed. After a crash, up bills every journaled request exactly once before serving, reset refuses while any are unbilled, and a damaged journal makes up refuse by name. In the hosted-core guard 3.2.0 a crash in the roughly one millisecond between the response reaching your client and the proxy's success callback can still lose that request's bill (a known limit); since 3.3.0 the repository guard journals every response before your client has all of it.
3.0.0 removed GUARD_CAP_UNITS (the old token cap); setting it refuses to start with a pointer to GUARD_CAP_USD.
What it is
Packaging, not a new component: a local LiteLLM proxy + the litellm-dynamo plugin, provisioned with a capped stream. The "API key" it prints is a real allowance credential - the same offline-verifiable JWS every gateway plugin checks. The guard always opens a Control Mode budget; it has no option for a funded one.
Why start here
- The cap is enforcement, not observation. The 402 arrives before the
spend, not in a report after it. The credential check is in-process and offline; metering is async - a remote instance adds no latency to your requests (request-path purity).
- Revocation is fast. Revoke the stream and the proxy denies the key
within one sync window.
- No money moves through Dynamo. The budget is always Control Mode.
Your provider still bills you for the requests the guard forwards, within the cap and the bounded residue above.
The operator path shows the same pattern scaled to a multi-user storefront.