Reverse Proxy
The gateway serves plain HTTP. When agents on other hosts connect over wss:// or download links use https, terminate TLS in front of the gateway with a reverse proxy, load balancer, or your platform; any product that supports WebSocket works.
Routes
Forward these paths to the gateway:
| Path | Used for |
|---|---|
/ws/agent | The agent’s WebSocket connection. Must allow WebSocket upgrade |
/ws/agent/challenge, /ws/agent/verify | Agent authentication and onprest-agent doctor (plain HTTP POST) |
/api/v1/capabilities/* | REST calls |
/api/v1/files/* | File downloads |
/mcp | MCP |
/openapi.json | OpenAPI |
/healthz | Health checks |
Set GATEWAY_PUBLIC_URL and, if capabilities return files, ONPREST_PUBLIC_BASE_URL to the public address; see Gateway configuration. Allow request bodies and timeouts large enough for uploads; see Deployment.
Client IP detection
The IP allow list and per-IP rate limit use the client’s address. Without a proxy, the gateway uses the TCP peer address, and you should leave GATEWAY_TRUSTED_PROXY_CIDRS empty.
Behind a proxy, set GATEWAY_TRUSTED_PROXY_CIDRS to the proxy’s own addresses only. For requests from those addresses, the gateway takes the client IP from the first entry of X-Forwarded-For, or from X-Real-IP. Configure the proxy to replace both headers with the address it saw, never to append to a value the client sent; otherwise a client could choose its own IP and bypass the allow list and rate limit.
GATEWAY_TRUSTED_PROXY_CIDRS=172.16.0.0/12
GATEWAY_IP_ALLOW_LIST=203.0.113.0/24,198.51.100.10The allow list and rate limit apply to every route, including /healthz and the agent routes.