Security proxy for agent and LLM traffic: isolates keys, filters what leaves, keeps access reliable
Reiki sits between a client (an agent such as opencode or Claude Code, or an application) and the providers it calls, isolating each side from what the other should not hold. It does not make either side trustworthy: a client that can read a secret on its own machine can still send it elsewhere, so masking backs up keeping secrets out of reach and does not replace it.
| Reiki keeps | From | Through |
|---|---|---|
| Upstream API keys | The client | Key files read only by Reiki; credential headers replaced per request |
| Credentials and listed terms in prompts | The provider | The placeholders plugin (placeholders) swaps them for placeholders before the request leaves and restores them in the response |
| Arbitrary destinations | The client | Config-only upstreams and the tunnel allowlist |
| A record of what was sent | Nobody; it is for you | The requestlog plugin (requestlog), with credentials masked |
[redacted]; a key base64-encoded inside a larger value, other encodings and compressed bodies are not. In a successful body the replacement has the same length, so a content length stays correct. Plugins see the response after this step. A key, or any of those forms, split across two chunks is caught. A configured key shorter than 8 bytes is refused at load: an echoed key that short would never be scrubbed. Reiki removes the client’s credential headers (authorization, x-api-key, x-goog-api-key) and any key query parameter, then sets the upstream’s header from the key file; a passthrough upstream receives the client’s own credentials and query string unchanged.[upstream.X.forward] socket or runs as its command, only in the normal credential header, with no second copy. A command gets an environment cleared except PATH, HOME, LANG, LC_ALL and the names in pass_env. Keep the socket in a directory only the Reiki user and listener can enter, and set expect_uid, which makes Reiki compare the uid of the process that accepted the connection (peer credentials, not the socket file’s owner) and refuse a mismatch. It is optional, so without it whoever binds the path receives the keys; to bound that, a socket whose parent directory is group- or other-writable and lacks the sticky bit is refused at load when expect_uid is unset (sticky directories such as /tmp stay allowed). A failed link to the forwarder answers 502 and never cools the key.reiki hash-token refuses a token shorter than 16 characters. A token_sha256 is verified only as 64 hex characters; a hash does not reveal the token’s length, so a token set another way is not checked. Use at least 16 random characters.Retry-After until the window passes, and a good login clears its count. Up to 4096 addresses are tracked; when full, the weakest entry makes room. The throttle covers the client listener; a refused CONNECT is logged but not counted.reiki keys --check reports a key file the group or others can read. Create them mode 0600.Reiki listens on listen, default 127.0.0.1:4097, serves plain HTTP and has no TLS. Keep it on loopback, or put a TLS-terminating proxy in front before exposing it. Upstream URLs must be https, except loopback addresses used in tests.
Reiki forwards every request header except hop-by-hop headers (connection, keep-alive, proxy-*, te, trailer, transfer-encoding, upgrade), host, content-length and the client credential headers. accept-encoding is replaced with identity so error bodies can be classified, unless the upstream sets forward_accept_encoding and the client sent one. Redirects from the upstream are not followed.
[tunnel.intercept] lets Reiki read the traffic of the hosts it lists, so treat the CA as a secret and the clients that trust it as covered by it.
reiki ca-init is name-constrained to the hosts you give it. A client that trusts it still rejects a certificate for any other name, so a stolen CA key cannot impersonate other sites.ca.pem in clients.leaf_ttl_hours (default 24). Wildcards and addresses are refused.Host header matches the tunnel destination and its path lies under the upstream’s base path; anything else is refused. This keeps one tunnel from reaching other hosts or other parts of the API.requestlog bodies there only when you intend to record them.Key values and stream tokens are not logged. Request and response bodies are not logged, except the first 160 characters of upstream error bodies at debug level, and whatever the requestlog plugin is configured to record, which masks credentials in paths, query parameters, credential headers and JSON keys and values.
Plugins are compiled into the binary and run inside the Reiki process, so a plugin is as trusted as Reiki. A plugin sees request headers (including the client token) and bodies but never an upstream key, which is attached after the hooks run. Only compile in plugins you have read. Plugins covers the hooks and panic handling.
rate_limit_per_minute, when set, caps that stream’s upstream attempts. Every selected-key attempt counts, including retries and a fallback upstream, so a failover cannot spend more calls than the limit allows. A rejected attempt does not reach the upstream or change key health.[admin]) is a second socket guarded by its own bearer token, compared by hash in constant time. Keep it on loopback. It exposes key names, upstream names and stream routing, but never key values, token hashes or file paths.[peers] with enabled and publish) is a third socket that serves only GET /v1/health and its event stream GET /v1/health/stream behind a read-only peer token, which must differ from the admin and every stream token. It must be on loopback, since it is plain HTTP. It publishes key counts and the soonest cooldown per upstream, which shows a token holder which accounts are under pressure and when they recover; it never carries key values, token hashes, file paths or stream names. See peers.Key health. A stream-token holder can influence key health. A 401, or a 403 or 400 the upstream attributes to the key, takes that key out of rotation for every stream that lists it until it is rotated and Reiki receives SIGHUP. To bound the damage, one request disables at most one key: a second key that refuses the same request is tried but not disabled. With hold_unauthorized = true on the upstream, the disable waits until a later key serves the same request, so a request that every key refuses disables none. The invalid-key marker in a 400 body counts only as a real JSON field ("reason": "API_KEY_INVALID"), not as text an upstream echoed back.
openai-organization, openai-project, anthropic-organization-id, set-cookie, set-cookie2) are not relayed.max_decoded_bytes (default 64 MiB). A decoded response that is not text/event-stream is buffered before its head is sent, so an over-limit body becomes a 502 instead of a truncated 200. SSE still streams and ends with an error if it passes the cap.response_idle_timeout_secs (default 300) abandons a body that produces no chunk, and optional response_timeout_secs bounds the whole body after its head. A buffered decoded body that runs out of time answers 504; a streamed body ends with an error, so a stalled upstream cannot hold a client connection forever.placeholders plugin keeps credential placeholders masked inside tool-call arguments unless restore_tool_args is set.Retry-After alone, and the read error is logged without the body.[server]: 1024 and 256 on the client listener, 64 and 16 on the admin one, by default; loopback is exempt from the per-address caps because every local process shares 127.0.0.1; the dropped-connection warning is rate-limited). A proxied request body must arrive within the 120-second request timeout (408).passthrough is reserved./status, /reload or the log.