Reiki

Security proxy for agent and LLM traffic: isolates keys, filters what leaves, keeps access reliable

View the Project on GitHub ddproxy/reiki

Peers

Reiki instances can share a coarse, read-only summary of their own key health, so an operator or a monitoring tool can see which instance has a usable key for an upstream. No request is routed by it: the proxy never reads or acts on peer data.

Everything here is off by default. Without a [peers] table, or with enabled = false, Reiki opens no extra listener, makes no outbound peer connection, and its admin documents (/status, /v1/openapi.json) are unchanged.

Build

Peer support is the peers cargo feature, in the default set like the bundled plugins. It does nothing until the config enables it, and a binary built with --no-default-features (or without peers) refuses a [peers] table, so a table cannot silently do nothing. Release binaries include it; the release workflow runs each runnable binary through reiki check with both disabled configs and requires peers: disabled.

Configure

[peers]
enabled = false                    # master switch; the table can exist and do nothing
publish = false                    # serve GET /v1/health on `listen`
listen = "127.0.0.1:4099"          # required to publish; its own socket; loopback unless TLS is on
# tls_cert = "/etc/reiki/peers/listener.pem"   # serve HTTPS: PEM chain, leaf first
# tls_key = "/etc/reiki/peers/listener.key"    # its PEM key, mode 0600
# tls_key_permissions = "error"    # or "warn" to load a key group or others can access
peer_token_sha256 = "<sha256 of the peer token>"   # a token named `default`; this or [[peers.tokens]] to publish
# instance = "edge-1"                # published name; "reiki" by default
poll_interval_secs = 30            # reader poll period; data older than 3 periods is unknown
expose_key_labels = false          # publish per-key names and states, not only counts
expose_host_stats = false          # publish load, memory, disk use and active sessions
expose_usage = true                # publish per-upstream attempt counts for the last hour
cooldown_bucket_secs = 300         # published cooldowns round up to a multiple of this; 0 is exact
# stream_interval_secs = 5         # period of `host` events on /v1/health/stream
# max_subscribers = 16             # open streams in total
# max_subscribers_per_peer = 4     # open streams per client address, not counted from loopback
# max_subscribers_per_token = 8    # open streams per peer token
# max_connections_per_addr = 4     # open TCP connections per client address

[[peers.tokens]]                   # more peer tokens, one per reader, each with a name
name = "peer-b"
token_sha256 = "<sha256 of the token issued to peer-b>"

[peers.peer-a]                       # one table per instance to read
url = "https://192.0.2.10:4099"    # https, or http on a loopback address
token_file = "/etc/reiki/peers/peer-a.token"   # the token peer-a issued to this instance
ca_file = "/etc/reiki/peers/peer-a-ca.pem"     # required for https; the only CA trusted for peer-a

Validation, at startup, on reload and in reiki check:

instance (optional) sets the published name, with a peer name’s character rules; without it the instance is published as reiki. The host name is never used, so a host, container or node name does not leave the host unless you set it here. A change to listen, or turning publishing on or off, needs a restart and appears in restart_needed as peers.listen. Tokens and the other settings apply on reload, and a reload that turns publishing off makes the listener answer 404 at once.

TLS on the peer listener

With tls_cert and tls_key the peer listener serves HTTPS (rustls, TLS 1.2 and 1.3, HTTP/1.1) and may listen on any address. Any CA may issue the certificate: a private one made for the peers, an internal company CA or a public one. Each reader trusts only the CA in its own ca_file for this peer, so a private CA made for the peers is the tightest choice.

A private CA and a listener certificate with openssl, for a peer reached as 192.0.2.10:

openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes -days 3650 \
  -subj "/CN=reiki peers CA" -keyout peers-ca.key -out peers-ca.pem
openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
  -subj "/CN=peer-a" -keyout listener.key -out listener.csr
openssl x509 -req -in listener.csr -CA peers-ca.pem -CAkey peers-ca.key -CAcreateserial \
  -days 365 -out listener.pem \
  -extfile <(printf 'subjectAltName=IP:192.0.2.10,DNS:peer-a\nextendedKeyUsage=serverAuth')
chmod 600 listener.key peers-ca.key

Give listener.pem and listener.key to the publishing instance, and peers-ca.pem to each reader as its ca_file for that peer. Keep peers-ca.key off the peers.

Publish: GET /v1/health

With enabled = true and publish = true, Reiki opens one more listener on [peers] listen. It serves exactly one route, GET /v1/health; every other path and method answers 404 without a body, whatever the credential.

printf '%s' "$PEER_TOKEN" | reiki hash-token     # goes in peer_token_sha256
curl -s -H "Authorization: Bearer $PEER_TOKEN" http://127.0.0.1:4099/v1/health
curl -s --cacert peers-ca.pem -H "Authorization: Bearer $PEER_TOKEN" https://192.0.2.10:4099/v1/health
{"instance":"peer-a","reiki_version":"0.10.3","observed_at":"2026-11-13T09:30:00Z","upstreams":[
  {"name":"zen","healthy_keys":1,"cooling_keys":1,"disabled_keys":0,
   "cooling_combinations":2,
   "soonest_cooldown_seconds":42,"last_status_class":"4xx",
   "requests_1h":120,"limited_1h":3,
   "request_buckets":[0,0,0,0,0,0,0,4,9,18,31,58],
   "tokens_1h":48210,"token_buckets":[0,0,0,0,0,0,0,1900,3600,7200,12400,23110],
   "request_minutes":[3,0,4,2,9,1,0,6,5,7],"token_minutes":[0,0,1900,0,700,300,0,1400,800,2100]}]}

Host stats and sessions

expose_host_stats = true (off by default) adds two objects to the answer:

[peers]
expose_host_stats = true
# session_header = "x-opencode-session"   # client header that names a session
# session_window_secs = 300               # a session is active this long after its last request
"host": {"load_average":[0.52,0.58,0.59],"cores":8,
         "memory":{"total_bytes":16384000000,"available_bytes":8192000000,
                   "swap_total_bytes":2048000000,"swap_free_bytes":2048000000},
         "disks":[{"roles":["config","state"],"total_bytes":107374182400,
                   "available_bytes":53687091200,"used_percent":50.0}]},
"sessions": {"window_seconds":300,"active_sessions":3}

Authentication

What a peer token holder learns

The summary is coarse, but it still tells a reader which upstreams are under rate or quota pressure and when the first key returns; polled over time, that is an activity timeline for the accounts behind this instance. Hand the peer token only to instances and tools inside the operator’s trust boundary, never across one. Nothing on this listener can change state.

The route is listed in the admin GET /v1/openapi.json while publishing, with the peer listener as its servers entry and a separate peerAuth security scheme. Without publishing the document is unchanged.

Push: GET /v1/health/stream

The same listener and token also serve GET /v1/health/stream, a Server-Sent Events stream, so a reader need not poll:

curl -N -H "Authorization: Bearer $PEER_TOKEN" http://127.0.0.1:4099/v1/health/stream
event: snapshot
data: {"instance":"peer-a","observed_at":"...","upstreams":[...]}

event: key
data: {"observed_at":"...","upstream":{"name":"zen","healthy_keys":0,"cooling_keys":2,...}}

: heartbeat

Read: reiki peers

reiki peers fetches /v1/health from every [peers.<name>] in the config and prints one row per peer upstream:

reiki peers                 # table
reiki peers --json          # {"peers":[{"name","state","error","instance","age_seconds","upstreams"}]}
PEER  INSTANCE  UPSTREAM  STATE    HEALTHY  COOLING  DISABLED  WAIT  AGE
peer-a  peer-a      zen       cooling  0        1        0         42s   3s
peer-b  -         -         unknown  -        -        -         -     -

reiki peers --watch follows every peer’s /v1/health/stream instead and prints the table again (or, with --json, one JSON document per line) whenever something changes. Each stream uses the same pinned client and token rules, with a 64 KiB cap per event. When a stream cannot be opened, ends, or sends nothing for 40 s, it polls /v1/health once, waits poll_interval_secs and tries the stream again. AGE is the age the peer last reported plus the time since the last frame from it, heartbeats included, measured on this host’s clock; a peer with nothing for three poll intervals turns unknown. It runs until interrupted.

Check

reiki check prints a peers: line: peers: disabled, or the effective settings, for example peers: enabled, publishing on 127.0.0.1:4099 (key labels hidden), 1 peer(s)[peer-a], poll every 30s. With more than one peer token it names them, as 2 token(s)[default, peer-b], after the listener.