Security proxy for agent and LLM traffic: isolates keys, filters what leaves, keeps access reliable
The [tunnel] section starts a second listener that works as a CONNECT forward proxy. A client that honours HTTPS_PROXY (most runtimes and tools do) asks it to open a TCP connection to host:port. By default Reiki copies bytes in both directions without reading them, so the client’s own TLS session, HTTP version and headers reach the destination exactly as the client made them.
[tunnel]
listen = "127.0.0.1:4099"
allow = ["api.example.com", "*.example.net"]
connect_timeout_secs = 10
HTTPS_PROXY=http://127.0.0.1:4099 NO_PROXY=127.0.0.1,localhost some-client
| Key | Default | Meaning |
|---|---|---|
listen |
required | Address to listen on. Must differ from listen and the admin address. Keep it on loopback or a private interface: the listener has no authentication. |
allow |
required | Destinations a client may open: host, host:port, *.host (subdomains, not the apex) or *. A bare host means port 443. A request for anything else gets 403. |
connect_timeout_secs |
10 | How long to wait for the destination to accept the connection. |
allow_loopback |
false | Lets the tunnel reach loopback addresses. For tests and local development only. |
deny_private |
false | Refuses private-range addresses: RFC 1918, 100.64.0.0/10 and IPv6 unique-local. Turn it on with a broad allowlist such as * so the tunnel reaches the internet and not the local network. |
intercept |
none | Reads the traffic of chosen hosts; see below. |
CONNECT is accepted. Any other request gets 400.10.0.0.0/8 are allowed unless deny_private is set.100.100.100.200, 168.63.129.16 and fd00:ec2::254. The host’s other interface addresses are not filtered, so avoid a broad allowlist such as *.info with the destination host and port, bytes in each direction and the duration. Nothing inside an opaque tunnel is visible, so there is no request log, no placeholders, no key injection and no failover for it.allow, deny_private, allow_loopback and connect_timeout_secs without a restart; open tunnels keep running. A new listen address needs a restart. See reload.An opaque tunnel cannot be logged, masked or given a key. [tunnel.intercept] changes that for the hosts you list: Reiki answers the client’s TLS handshake itself with a certificate signed by a CA the client trusts, reads the HTTP request, and sends it through the same path as a normal route, then re-encrypts it on its own TLS session to the real upstream. Plugins, key selection, failover and rate limits all apply.
[tunnel]
listen = "10.0.0.1:4099"
allow = ["api.example.com"]
[tunnel.intercept]
ca_cert = "/etc/reiki/ca/ca.pem"
ca_key = "/etc/reiki/ca/ca.key"
leaf_ttl_hours = 24
require_auth = true # CONNECT to a stream host must carry the stream token
ca_key_permissions = "error" # refuse a CA key that group or others can access; "warn" only logs
[[tunnel.intercept.hosts]]
host = "api.example.com"
upstream = "example" # an [upstream.*] whose base_url is on this host
stream = "client-a" # the stream whose key chain serves it; omit for a passthrough upstream
Create the CA, name-constrained to the hosts it may sign for, and give only ca.pem to clients:
reiki ca-init --dir /etc/reiki/ca --host api.example.com --days 365
A CA is limited to the hosts it was created with, so adding a host means creating a new one with --replace, giving clients the new ca.pem, and reloading. reiki check prints the days the CA has left, startup logs a warning within 30 days of expiry, and GET /status reports intercept.ca_days_left.
Clients must trust that certificate: add it to the system store, or point the runtime at it with SSL_CERT_FILE or NODE_EXTRA_CA_CERTS, whichever the client reads.
allow on port 443 and map to an upstream on that same host.Host header that differs from the tunnel destination gets 421.. or .. segments (also percent-encoded as %2e), an encoded / (%2f), or a backslash are refused with 400 before any path check.Proxy-Authorization, as a bearer token or as the password of a basic credential, so HTTPS_PROXY=http://user:TOKEN@host:port works. Without it the tunnel answers 407 with Proxy-Authenticate: Basic realm="reiki". Hosts on a passthrough upstream need none, because they spend no key.require_auth = false in [tunnel.intercept] turns this off (default true). Do that only when every client that can reach the tunnel listener is trusted; Reiki logs a warning at startup when it is off.paths = ["/v1", "/other"]. Matching prefixes (whole segments) are sent to the host exactly as the client sent them, and the upstream’s base_url then supplies only the host and the credential format.Accept-Encoding, and Connection: keep-alive, over HTTP/1.1.Host (set to the upstream’s) and Content-Length (recomputed from the body). It removes hop-by-hop headers: every header named in Connection and Keep-Alive, Expect, TE, Trailer, Transfer-Encoding, Upgrade and Proxy-*. The client’s Connection header is replaced by keep-alive or removed.Content-Encoding. An unknown encoding passes through untouched.http2, forward_accept_encoding, title_case_headers, send_keep_alive) apply to the reverse-proxy routes only, not to intercepted traffic.[upstream.X.forward] table. Reiki still terminates the client’s TLS, authenticates the stream and swaps the key; the request then goes to the forwarder instead of Reiki’s own TLS client, so the upstream sees the forwarder’s handshake. Add streaming = true there so event streams are not held until they finish. See providers.hosts stay opaque.require_auth and leaf_ttl_hours.ca_cert or ca_key changes, or when the files are renewed in place. The new CA must have a key that matches its certificate, a DNS name constraint that covers every intercepted host, and no expiry in the past. A CA that fails a check refuses the whole reload, and the running CA keeps serving.ca.pem. Connections already open keep their certificate until they close.[tunnel.intercept] needs a restart. See reload and security for what to protect.A plain CONNECT to a host on the allow list needs no credential: the list is the only gate, and "*" is a legal rule that opens every HTTPS site. Only intercepted hosts check the stream token. Put the tunnel listener on a network that only trusted clients can reach, keep deny_private = true so it cannot be used to reach the local network, and keep allow as short as the clients need. deny_private covers RFC 1918, shared address space, benchmarking and the IETF protocol block, unique-local IPv6, and the IPv4 forms embedded in IPv4-mapped, NAT64, 6to4 and Teredo addresses.