Security proxy for agent and LLM traffic: isolates keys, filters what leaves, keeps access reliable
Security proxy for agent and LLM traffic: isolates keys, filters what leaves, keeps access reliable.
Reiki sits between a client and the LLM providers the client calls. The client can be an agent such as opencode or Claude Code, or an application that would otherwise hold provider API keys. The client holds a stream token. Reiki holds the upstream keys and decides what may leave.
Reiki is one binary. It runs in the foreground, reads one TOML file and logs to stderr. Plugins are compiled in, so Reiki never loads code at runtime.
flowchart TD
client["client<br/>Authorization: Bearer stream token"] --> listener["client listener<br/>listen"]
listener -->|"token picks the stream<br/>path /upstream/... picks the upstream"| stream["stream<br/>[streams.NAME]<br/>plugins run request hooks once"]
stream -->|first usable key| chain["chain<br/>chain = key, key, ..."]
chain --> key["key<br/>[keys.NAME] file = path<br/>credential header set from the key"]
key --> upstream["upstream<br/>[upstream.NAME] base_url = https://..."]
upstream --> provider["provider"]
upstream -.->|"no usable key: fallback upstream, one hop"| fallback["fallback upstream"]
fallback --> provider
Other listeners, each optional and on its own socket:
| Listener | Table | Serves |
|---|---|---|
| admin | [admin] |
GET /status, POST /reload, GET /metrics |
| peers | [peers] |
GET /v1/health with a read-only peer token |
| tunnel | [tunnel] |
CONNECT proxy with a destination allow-list; intercept for chosen hosts |
| hub | [hub] |
parsed and validated only in this release |
passthrough upstream. The path prefix chooses the upstream, so /example/chat/completions goes to the example upstream.sticky keeps one key until it fails. round_robin rotates.Reiki reads /etc/reiki/reiki.toml unless --config names another file. --listen or REIKI_LISTEN overrides listen from the file, and the flag wins over the variable. reiki check validates the file and the key files, and prints the address Reiki will use.
Upstream keys stay out of the client. Keys stay in Reiki’s files, and the client never receives one.
passthrough upstream is the exception. It forwards the client’s own credentials. See providers.Reiki decides what leaves the client’s machine and what reaches the provider.
placeholders plugin swaps credentials and listed terms for stable placeholders before the request leaves, and restores them in the response. See placeholders.phi, finance and controlled plugins block or report identifiers in outbound requests. See phi, finance and controlled.Requests keep working when one key fails, and you can see what happened.
reiki top shows key health across instances, peers publish that health, and /metrics exports it. See top, peers and monitoring.| Term | Meaning |
|---|---|
| stream | One client with its own token ([streams.NAME]) and key chain. |
| key | An upstream credential, read from the file named in [keys.NAME]. It is available, cooling or out of rotation. |
| chain | The ordered keys a stream may use (chain = [...]). |
| upstream | A provider as Reiki sees it: [upstream.NAME] with an https base_url. Clients reach it at /NAME. |
| fallback | [upstream.NAME.fallback]: another upstream that takes a request when no key of NAME is usable. It is one hop. |
| plugin | A compiled-in component, configured under [plugins.NAME], that inspects or changes requests and responses. |
| peer | Another Reiki instance whose key health this one reads ([peers.NAME]). Peers route nothing. |
| intercept | TLS termination on the tunnel for chosen hosts, so plugins and key handling apply ([tunnel.intercept]). |
| cooldown | The time a key, or one route and model on it, is skipped after a failure. Classes: rate_limited, quota_exhausted, transient. |