Skip to main content

Connected Gateway Relay

Connected gateways can run on machines behind NAT, firewalls, VPNs, or corporate networks. The built-in reverse tunnel lets a registered gateway receive requests for its Keeptrusts publication without opening an inbound port.

How the relay works​

When a connected gateway has an API URL, API token, and runtime registration ID, it derives a relay hostname from KEEPTRUSTS_API_URL and opens a persistent outbound WebSocket connection:

KEEPTRUSTS_API_URL=https://api.eu.keeptrusts.com
                          ↓ automatic derivation
Gateway ──WSS──▶ wss://relay.eu.keeptrusts.com/v1/gateway/relay

The relay hostname is region-aware: the api. prefix in the API URL is replaced with relay. automatically. For example:

API URLDerived relay URL
https://api.eu.keeptrusts.comwss://relay.eu.keeptrusts.com/v1/gateway/relay
https://api.us.keeptrusts.comwss://relay.us.keeptrusts.com/v1/gateway/relay

You do not need to configure the relay URL — it is derived automatically from the API URL.

  1. The gateway authenticates using its machine token (KEEPTRUSTS_API_TOKEN).
  2. It sends a registration message containing its runtime_registration_id.
  3. The control plane acknowledges and begins dispatching inbound API requests through the WebSocket.
  4. The relay client forwards each request to the local gateway HTTP server and sends the response back.
  5. Streaming responses (including SSE for LLM completions) are forwarded through the same channel.

If an established connection drops, the next retry starts after one second. A connection that repeatedly fails before registration uses exponential backoff, capped at 30 seconds.

Configuration​

There is no separate customer relay-enable flag. The relay task starts only when connected mode resolves all three required values below:

VariablePurpose
KEEPTRUSTS_API_URLControl-plane URL — the relay hostname is derived from this automatically
KEEPTRUSTS_API_TOKENMachine token used to authenticate the WebSocket
KEEPTRUSTS_RUNTIME_REGISTRATION_IDOptional explicit registration ID; a connected gateway normally registers or restores one during startup

The local gateway HTTP server listens on port 41002 by default. The relay client forwards dispatched requests to http://127.0.0.1:<gateway-port> with a 30-second per-request timeout.

Monitoring​

Console​

The gateway detail surface shows control-plane heartbeat and telemetry freshness. It does not currently expose the relay client's WebSocket state as a separate status field.

CLI​

kt gateway status --name production

This command reports local supervisor or service-manager state. Use the console gateway detail page for control-plane heartbeat freshness and published-hostname status.

Relay heartbeats​

The relay client sends a WebSocket ping every 20 seconds, responds to server pings, and reconnects if it receives no WebSocket message for 45 seconds. Control-plane gateway freshness is reported separately through runtime telemetry.

Troubleshooting​

"relay connection failed"​

  • Verify KEEPTRUSTS_API_URL is set and the host is reachable.
  • Confirm the firewall allows outbound HTTPS and WSS traffic on port 443.
  • Check DNS resolution for both the API host and the derived relay host (e.g. relay.eu.keeptrusts.com).

"authentication failed"​

  • The runtime token may be expired, revoked, or missing the gateway permissions required by the relay endpoint. Replace it through the governed token workflow used for that gateway.
  • Verify KEEPTRUSTS_API_TOKEN matches the token assigned to this gateway.

High latency through the relay​

Measure request timing from the API consumer, gateway, and upstream provider before assigning the delay to the relay. Place the gateway near its upstream provider and inspect gateway metrics and request traces for the slow segment.

Gateway reconnects frequently​

  • Unstable network connections cause repeated backoff cycles. Check the host's network stability.
  • If the gateway logs show the backoff reaching 30 seconds, the control plane may be temporarily unavailable — the gateway will recover automatically.

Next steps​