Gateway Configuration

The gateway reads its configuration from environment variables at startup. It does not read a file itself, so load gateway.env into the environment (or set the variables in your service manager) before starting it. Restart the gateway after any change.

Run one gateway per customer, with its own variables, agent public key, and API keys.

# Required
GATEWAY_AGENT_PUBLIC_KEY=base64url-ed25519-public-key
GATEWAY_API_KEYS_JSON='[{"name":"partner-a","key_hash":"$2a$10$xxxxx","capabilities":["get_customer","get_orders"]}]'

# Common optional settings
GATEWAY_PUBLIC_URL=https://gateway.example.com
ONPREST_PUBLIC_BASE_URL=https://gateway.example.com
GATEWAY_TRUSTED_PROXY_CIDRS=172.16.0.0/12

The full list with defaults is in Environment Variables. An empty value means the same as leaving the variable out. An invalid value stops the gateway at startup instead of falling back to a default.

Required settings

GATEWAY_AGENT_PUBLIC_KEY is the public half of the key pair from onprest-gateway create-agent-secret. The private half goes into the agent’s gateway section.

GATEWAY_API_KEYS_JSON lists the API keys as a JSON array of name, bcrypt key_hash, and capabilities; see API Keys. Bcrypt hashes contain $, so wrap the whole value in single quotes when a shell loads the file. Otherwise the shell expands $2a and $10 and corrupts the hash.

Public URLs

GATEWAY_PUBLIC_URL is the address clients use, written into the OpenAPI servers list. Without it, the gateway derives one from GATEWAY_ADDR, such as http://localhost:8080. Set it whenever a proxy or load balancer sits in front.

File reference origin

ONPREST_PUBLIC_BASE_URL is the origin used in download links for returned files, for example https://gateway.example.com. It must be an origin only (no path) and use HTTPS, terminated in front of the gateway, except http://localhost or a loopback address for local testing. The gateway builds every link from this value and never from request headers.

Set it whenever any capability uses reference delivery, the default for returned files. Until it is set, the gateway publishes none of the agent’s capabilities: /openapi.json and MCP tools/list report AGENT_OFFLINE, and every capability call returns DEPENDENCY_UNAVAILABLE, while /healthz still reports the agent as connected. A configuration where every capability returns only JSON, or files with delivery.rest: direct and delivery.mcp: inline, does not need it. If a proxy is in front, route /api/v1/files/ to the gateway as well.

Request size limits

Requests over a size limit get HTTP 413; when all readers are busy, new requests get HTTP 503 BUSY before their body is read. The gateway’s memory use grows with the JSON limit times the number of readers, so raise them together with care. Capability-level limits are separate; see Policy and limits.

Listen address

The gateway listens on :8080. Set GATEWAY_ADDR, such as 127.0.0.1:8080, to bind to one interface or another port.

CORS

Set GATEWAY_CORS_ALLOWED_ORIGINS to a comma-separated list of origins when browser-based clients, such as a Swagger UI on another host, call the gateway directly. Only those origins get CORS headers. MCP requests from any other browser origin are rejected.

Network controls

GATEWAY_IP_ALLOW_LIST restricts every route, including /healthz and the agent connection, to the listed CIDRs or IPs. GATEWAY_RATE_LIMIT_REQUESTS_PER_SECOND and GATEWAY_RATE_LIMIT_BURST (defaults 10 and 20) limit requests per source IP. Behind a proxy, set GATEWAY_TRUSTED_PROXY_CIDRS so these controls see the real client address; see Reverse Proxy.