Reverse Proxy

TLS termination and reverse proxy choice are environment-owned. onprest-gateway works directly exposed or behind any compatible reverse proxy or load balancer.

Onprest does not require Caddy, nginx, Envoy, ALB, or any specific proxy.

Required Routes

Route these paths to the gateway process.

The /ws/agent route must support WebSocket upgrade.

/healthz returns HTTP 200 while gateway is healthy and includes agent_connected. See Healthz.

Source IP Detection

By default, gateway uses the TCP connection source address, RemoteAddr, as the client IP.

If GATEWAY_TRUSTED_PROXY_CIDRS is configured and the direct peer is inside those CIDRs, gateway uses X-Forwarded-For first and falls back to X-Real-IP:

• X-Forwarded-For
• X-Real-IP

Forwarded headers from untrusted peers are ignored because they are spoofable.

The trusted proxy must remove caller-supplied values and overwrite both headers from its authenticated connection metadata. Do not append to an inbound X-Forwarded-For: gateway intentionally selects its first valid address, so preserving a caller-controlled first value would turn proxy trust into an allow-list/rate-limit bypass.

IP Allow List

GATEWAY_IP_ALLOW_LIST applies after source IP detection to REST, MCP, OpenAPI, /healthz, and the agent WebSocket route. Per-source rate limiting applies to the same routes. /healthz is API-key-free, not exempt from these network controls.

GATEWAY_IP_ALLOW_LIST=203.0.113.0/24,198.51.100.10
GATEWAY_TRUSTED_PROXY_CIDRS=172.16.0.0/12

Single IP values are accepted and treated as host routes.

Direct Exposure

If no reverse proxy is used, leave GATEWAY_TRUSTED_PROXY_CIDRS empty. In that mode, forwarded headers are ignored and RemoteAddr is authoritative.

Proxy Exposure

When running behind a proxy, include only the proxy or load balancer source CIDRs in GATEWAY_TRUSTED_PROXY_CIDRS. Do not include broad public ranges unless those ranges are truly controlled proxy peers.