Beginner path
If you only have a raw provider key, start with the environment-based example config and learn the broker shape first.
What this adds
Change runtime visibility, not just secret storage.
The broker binds to 127.0.0.1, allows only specific API
paths, can require a separate caller token, and attaches the bearer
token itself. The agent or tool host can call the broker, but it does
not need the raw provider key in its own environment.
This does not magically make a weak machine secure. It is a teaching example of the more general pattern: a secret-holding component can expose a narrower capability than "here is the key."
Mature secret-store path
If your key already lives in 1Password or Azure Key Vault, keep it there and switch the broker to a command-based secret source.
Starter configs: broker_config.1password.example.json and
broker_config.azure-keyvault.example.json.
Best production path
A real backend or managed identity is usually stronger than a localhost broker. The broker is most useful for local tooling and for teaching the trust-boundary pattern clearly.
How it works
The broker is intentionally narrow.
| Piece | In this lab | Why it matters |
|---|---|---|
| Bind address | 127.0.0.1 only |
Keeps the example local by default instead of exposing it on the network. |
| Allowed paths | Explicit allowlist such as /v1/chat/completions |
Limits which upstream capabilities the caller can invoke. |
| Secret source | Env or external command | Lets the same broker pattern work with raw keys, 1Password, or Azure Key Vault. |
| Caller token | Optional X-Broker-Token from client_token_env |
Stops casual or browser-triggered localhost callers from getting the capability for free. |
| Dry-run mode | No secret required | Makes the flow teachable and smoke-testable without real credentials. |
| Event log | events.jsonl |
Shows the request trail without logging the secret itself. |
Threat model
Loopback helps, but localhost is not a magic trust boundary.
Browser or app on the same machine
A web page or local app may still be able to send requests to
127.0.0.1. That is why the stronger real config adds a
caller token instead of relying on loopback alone.
Same-user automation
If hostile code can run as the same local user and read the same token source, the localhost split is no longer enough. Move to a backend or a stronger OS-level boundary.
What the token is for
The broker token protects the capability interface. It is separate from the provider API key, so you can rotate or narrow the caller path without changing the upstream secret.
Use this with
Pair this lab with API key security and the bootstrap step.
Real-world analog
This is the local teaching version of an internal proxy or backend gateway that hides infrastructure secrets behind a narrow interface.
Safer real config: set BROKER_CLIENT_TOKEN, require
X-Broker-Token, and keep the raw provider secret behind
the broker.