Security proxy for agent and LLM traffic: isolates keys, filters what leaves, keeps access reliable
reiki runs the proxy when given no subcommand. The other subcommands check config, read a running instance, or do one job and exit.
reiki [--config PATH] [--listen ADDR] [COMMAND [ARGS]]
reiki COMMAND --help prints the flags for each command. reiki --version prints the build version.
| Option | Default | Meaning |
|---|---|---|
--config PATH |
/etc/reiki/reiki.toml |
Config file. Read by check, server mode, keys, failures, reload, peers and top. hash-token, ca-init and scan do not read it. |
--listen ADDR |
from listen in the config |
Client listen address. Used by server mode and check. Other commands ignore it. |
| Variable | Used by | Meaning |
|---|---|---|
REIKI_LISTEN |
server mode, check |
Client listen address. Overridden by --listen; overrides listen in the config. |
REIKI_ADMIN_TOKEN |
reload, keys, failures, top |
Admin token, when --token-file is not given. top uses it only to read the local instance’s full failure rows. |
RUST_LOG |
server mode | Log filter. Overrides [log] level at startup. |
--listen and REIKI_LISTEN accept an IP:port address or a host:port name.
The argument parser exits 2 on a usage error: an unknown flag, or two flags that conflict. Beyond that, each command lists its own exit codes in its section. Codes are not the same across commands. For example, a config that does not parse exits 1 for check and 2 for keys.
reiki --config /etc/reiki/reiki.toml
Starts the client listener, and the admin, peer and tunnel listeners when configured. Logs go to stderr and to [log] file when set. Runs until SIGTERM or SIGINT. SIGHUP reloads the config.
| Exit | Meaning |
|---|---|
0 |
Stopped cleanly after a signal. |
1 |
Startup failed: config, key files, plugin build or a listener could not be bound. |
Send SIGTERM for a clean stop. Requests in flight get [service] shutdown_timeout_secs. A second signal exits at once. See service.
Reads a token from stdin and prints its SHA-256 in hex, for token_sha256 in [admin] or [streams.NAME].
reiki hash-token
| Behaviour | Detail |
|---|---|
| Input | All of stdin. Leading and trailing whitespace is removed. |
| Length | At least 16 characters. A shorter token is refused. |
| Output | 64 lowercase hex characters and a newline. |
Exit codes: 0 on success; 1 when the token is too short or stdin cannot be read.
Example, with a token generated for one client:
openssl rand -hex 24 > client.token
reiki hash-token < client.token
<64 hex characters>
Keep client.token for the client. Put only the hash in the config.
Loads the config the way the service does, then exits. It does not contact the upstream, an admin listener or a peer.
reiki --config /etc/reiki/reiki.toml check
| Step | Checked |
|---|---|
| Config | Parse and validate every table. See validation. |
| Keys | Each key file exists, is readable, is not empty and holds at least 8 bytes. |
| Plugins | Each [plugins.NAME] builds in dry-run mode. |
| Intercept CA | Key matches, not expired, covers every intercepted host. Prints days left. |
| Peer certificate | tls_cert and tls_key load. Prints days left. |
| Forwarder socket | Warnings are printed as warning: .... |
Output, for a config with one upstream, one key, one stream and peers off:
caps: client 1024 (256 per address), admin 64 (16 per address); loopback exempt from the per-address caps
peers: disabled
ok: 1 upstream(s), 1 key(s), 1 stream(s), listening on 127.0.0.1:4097, admin on 127.0.0.1:4098
Exit codes: 0 when every step passes; 1 on any failure, including a config that does not parse.
Runs the detection plugins over files or stdin. It reports where each identifier is. It never prints the matched text, so its output is safe to share. Use it to tune kinds before you switch a plugin from report to block.
reiki scan [--plugin NAME]... [--kinds K1,K2 | --all] [--json] [FILE]...
| Flag | Default | Meaning |
|---|---|---|
--plugin NAME |
every compiled-in plugin | Run only this plugin. Repeat for several. Names: phi, finance, controlled. The old name gov also works. |
--kinds K1,K2 |
each plugin’s default set | Kinds to look for, comma separated. A kind is matched only by the selected plugins that know it. Conflicts with --all. |
--all |
off | Look for every kind, including the ones that are off by default. |
--json |
off | One JSON object per finding. |
FILE... |
stdin | Files to scan. - means stdin. |
Kinds per plugin:
| Plugin | Default | With --all adds |
|---|---|---|
phi |
ssn, card, routing, account, dob, medical_id, npi, icd10, column |
field, email, phone |
finance |
iban, swift, crypto, cusip, isin, pan_sad |
account, sedol |
controlled |
cui, classification, dissemination |
ein, itin, cage, uei, edipi, eccn |
Text output, one line per finding:
FILE:LINE:COL PLUGIN KIND
JSON output, one object per line:
{"file":"FILE","line":1,"col":6,"plugin":"phi","kind":"card"}
A summary goes to stderr:
scanned 1 input(s): 2 finding(s): phi card x1, phi ssn x1
Example:
reiki scan --plugin phi --kinds ssn,card notes.txt
Exit codes:
| Code | Meaning |
|---|---|
0 |
No findings. |
1 |
At least one finding. |
2 |
Unknown plugin or kind, a file cannot be read, or a usage error. |
A named kind that the selected plugin does not know exits 2. For example, --plugin finance --kinds ssn fails.
Asks the running instance to reload its config over the admin listener. Posts to /reload. Use --dry-run to see what a reload would change without applying it. See troubleshooting.
reiki reload [--dry-run] [--url URL] [--token-file PATH]
| Flag | Default | Meaning |
|---|---|---|
--dry-run |
off | Report the changes only. Apply nothing. |
--url URL |
http:// plus [admin] listen from the config |
Admin address. An unspecified address such as 0.0.0.0 is sent as 127.0.0.1. |
--token-file PATH |
REIKI_ADMIN_TOKEN |
File that holds the admin token. Leading and trailing whitespace is removed. |
Output is the JSON answer from /reload, printed to stdout for both success and refusal:
{"ok":true,"dry_run":false,"generation":1,"keys":1,"streams":1,"changed":[],"restart_needed":[]}
Fields: ok, dry_run, generation (successful reloads since startup), keys and streams (counts after the reload), changed (what differs, such as plugins phi), restart_needed (settings that apply only after a restart).
A failed reload answers {"ok":false,"error":"..."} and exits 1.
Example:
reiki reload --dry-run --url http://127.0.0.1:4098 --token-file /etc/reiki/admin.token
Exit codes:
| Code | Meaning |
|---|---|
0 |
The reload or the preview succeeded. |
1 |
The admin listener refused the request, or the reload failed. |
2 |
No admin token, no admin address, config unreadable (when --url is not given), or the listener could not be reached. |
Shows each key’s health from the running instance, or checks key files offline. The three forms are mutually exclusive.
reiki keys [--json] [--url URL] [--token-file PATH]
reiki keys --enable NAME [--url URL] [--token-file PATH]
reiki keys --check
| Flag | Default | Meaning |
|---|---|---|
--json |
off | Print JSON instead of a table. Conflicts with --check and --enable. |
--url URL |
[admin] listen from the config |
Admin address. |
--token-file PATH |
REIKI_ADMIN_TOKEN |
Admin token file. |
--enable NAME |
none | Re-enable a key that is out of rotation. Posts to /v1/keys/enable. |
--check |
off | Check the key files in the config without contacting an instance. Conflicts with the other flags. |
Reads /status on the admin listener:
KEY UPSTREAM STATE COOLDOWN LAST STREAMS
zen-a zen ok - - client
| Column | Meaning |
|---|---|
KEY |
Key name from [keys.NAME]. |
UPSTREAM |
Upstream the key authenticates to. |
STATE |
ok, cooling (for the COOLDOWN time) or disabled (out of rotation until --enable). |
COOLDOWN |
Seconds left on a cooling key, or -. |
LAST |
Last upstream status code, or -. |
STREAMS |
Streams whose chain holds the key. |
{"keys":[{"name":"zen-a","upstream":"zen","state":"ok","cooldown_seconds":null,"last_status_code":null,"streams":["client"]}]}
cooldown_class and scopes appear when the instance reports them. scopes lists cooling route and model pairs, soonest first.
--enablePrints the admin answer, such as {"ok":true,"key":"zen-a"}. A name that does not exist gets 404 and exit 1.
--checkReads each key file named in the config. It prints one line per key:
zen-a: ok
loose: warning: /path/to/key is group or world readable (mode 0644)
gone: error: /path/to/key does not exist
A warning also exits 1. Problems are listed for every key, not only the first.
Exit codes:
| Mode | 0 |
1 |
2 |
|---|---|---|---|
| Health table or JSON | Answer received and parsed. | Admin listener answered with an error status, or the answer is not valid /status JSON. |
No admin token, no admin address, the listener could not be reached, or the answer could not be read. |
--enable |
Key re-enabled. | Refused, such as an unknown key (404). |
As above. |
--check |
Every key OK. | Any error or warning. | Config unreadable or does not parse. |
Shows the running instance’s last key failures, from the same in-memory ring as GET /v1/failures.
reiki failures [--limit N] [--key NAME] [--json] [--url URL] [--token-file PATH]
| Flag | Default | Meaning |
|---|---|---|
--limit N |
20 |
Records to show, newest first; 1 to 64. |
--key NAME |
all keys | Only failures for this key name. |
--json |
off | Print the same JSON array as the endpoint. |
--url URL |
[admin] listen from the config |
Admin address. |
--token-file PATH |
REIKI_ADMIN_TOKEN |
Admin token file. |
The table:
TIME STREAM KEY STATUS CLASS COOLED NOTE
2026-11-17 12:00:00 client zen-a 429 rate_limited 42s {"error":"rate limited"}
| Column | Meaning |
|---|---|
TIME |
Failure time in UTC. |
STREAM |
Stream that made the attempt. |
KEY |
Key name from [keys.NAME]. |
STATUS |
Upstream status code, or - for a transport failure. |
CLASS |
rate_limited, quota_exhausted, access_disabled, unauthorized or transient. |
COOLED |
Seconds left on the cooldown this failure started, or -. |
NOTE |
Scrubbed, printable body snippet, cut to the terminal width (COLUMNS, default 120). |
Lines are cut to COLUMNS, so a narrow terminal keeps the columns aligned. Nothing in the ring is written to disk; a restart starts it empty. --json prints an array whether or not --limit was given.
Exit codes: 0 on success; 1 when the admin listener refuses the token or answer; 2 when it cannot be reached or no admin token or address is available.
Reads /v1/health on each [peers.NAME] and prints what it reports. Each peer’s token comes from its token_file in the config. See peers.
reiki peers [--json] [--watch]
| Flag | Default | Meaning |
|---|---|---|
--json |
off | Print JSON. |
--watch |
off | Follow each peer’s /v1/health/stream and print the table on each change. A peer whose stream is down is polled. Runs until interrupted. |
Table output:
PEER INSTANCE UPSTREAM STATE HEALTHY COOLING DISABLED WAIT AGE
edge-1 edge-pub zen ok 1 0 0 - 0s
| Column | Meaning |
|---|---|
PEER |
Name from [peers.NAME]. |
INSTANCE |
Name the peer publishes, from its instance setting. |
UPSTREAM |
One row per upstream the peer reports. |
STATE |
Per upstream: ok, cooling, disabled or no_keys. Per peer: unknown when the data is missing or older than three poll intervals, and no_upstreams when the peer has none. |
HEALTHY, COOLING, DISABLED |
Key counts for the upstream. |
WAIT |
Shortest remaining cooldown, or -. |
AGE |
Seconds since the peer’s data was taken. |
A peer that cannot be reached prints an error line to stderr, for example reiki: peer edge-1: cannot connect: ..., and shows as unknown.
JSON output has a peers array with each peer’s name, instance, state (fresh or unknown), error, age_seconds and upstreams.
Exit codes:
| Code | Meaning |
|---|---|
0 |
At least one peer gave fresh data. |
1 |
No peer gave fresh data. |
2 |
Config unreadable or invalid, no [peers] table, [peers] not enabled, or no peers listed. |
A live terminal view of every peer’s key health. The screen is a peers-by-providers matrix, with the selected peer’s detail below it. See top for the screens and columns. This page lists the keys.
reiki top [--once] [--interval SECS] [--full] [--provider NAME]
Needs the top build feature. The feature is not in the default build. Release binaries include it.
| Flag | Default | Meaning |
|---|---|---|
--once |
off | Poll each peer once, print plain text and exit. |
--interval SECS |
1 |
Seconds between redraws. Values below 1 count as 1. Live mode only. |
--full |
off | Start in the per-peer text view instead of the matrix. |
--provider NAME |
all providers | Show only this provider’s column. An unknown name prints unknown provider: NAME to stderr and shows everything. |
One-shot output:
Fleet 1/1 fresh zen 1/1 [req 1h]
zen Ver load disk sess
edge-1 ■ ······ 0.10.3 - - -
Exit codes:
| Mode | 0 |
1 |
2 |
|---|---|---|---|
--once |
At least one peer answered. | No peer answered. | Config problem, as for peers. |
| Live | Quit with q, Esc or Ctrl-C. |
Terminal could not be set up or read. | Config problem, or stdout is not a terminal. Use --once in scripts. |
Some keys act only in matrix mode, which is the default view. Ctrl-C quits from any screen, including the key list.
| Key | Action |
|---|---|
q, Esc, Ctrl-C |
Quit. |
j, Down |
Matrix: select the next peer. Full view: scroll down. |
k, Up |
Matrix: select the previous peer. Full view: scroll up. |
PageUp, PageDown |
Scroll one screen in the full view. |
g, Home |
Scroll to the top. |
G, End |
Scroll to the bottom. |
Tab, Shift-Tab |
Select the next or previous peer. |
Enter, e |
Matrix: open or close the selected peer’s detail. |
v, E |
Switch between the matrix and the full text view. |
f |
Matrix: cycle the provider filter, through each provider and back to all. |
c |
Clear the provider and peer filter. |
p |
Pause or resume the screen. The age of the frozen data is shown. |
u |
Matrix: switch the gauge between requests and tokens. |
w |
Matrix: switch the gauge window between the last hour and the last five minutes. |
m |
Matrix: cycle the chart metric. The chart row appears at 28 rows or more. |
? |
Show the key list. The next key press closes it and does nothing else. |
x |
No action. |
The footer hint line reads j/k peer, which is the matrix behaviour above.
Source: crates/reiki-top/src/ui.rs and src/top.rs.
Creates a certificate authority for [tunnel.intercept]. The CA is name-constrained to the hosts you list, so a stolen key cannot sign for anything else.
reiki ca-init --dir DIR --host HOST [--host HOST]... [--days N] [--replace]
| Flag | Default | Meaning |
|---|---|---|
--dir DIR |
required | Directory that receives ca.pem and ca.key. Created if missing. |
--host HOST |
required, repeatable | A host the CA may sign for. Lowercase DNS name with at least two labels. |
--days N |
365 |
Validity in days. Range 1 to 3650. |
--replace |
off | Overwrite an existing CA in --dir. Clients then need the new ca.pem. |
Example:
reiki ca-init --dir /etc/reiki/intercept --host api.example.net --days 365
wrote /etc/reiki/intercept/ca.pem and /etc/reiki/intercept/ca.key; give ca.pem to clients, keep ca.key private
ca.key is created with mode 0600. Give clients only ca.pem.
Exit codes: 0 on success; 1 on a bad host, a bad --days value, or an existing CA without --replace.
Then point the config at the files:
[tunnel.intercept]
ca_cert = "/etc/reiki/intercept/ca.pem"
ca_key = "/etc/reiki/intercept/ca.key"
See tunnel.