WebSocket Gateway
The gateway exposes two WebSocket upgrade routes:
| Client route | Upstream route |
|---|---|
GET /v1/chat/completions/ws | /v1/chat/completions over ws:// or wss:// |
GET /v1/responses/ws | /v1/responses over ws:// or wss:// |
The client uses the /ws suffix only when connecting to Keeptrusts. The
gateway removes that suffix when it connects to the selected upstream.
Connect
Send an application API token, Access Key, or Gateway Key in the WebSocket upgrade request. Do not use the connected gateway's runtime service token as the client credential.
For example, with a WebSocket client that supports custom headers:
export KEEPTRUSTS_REQUEST_TOKEN="kt_..."
websocat \
-H="Authorization: Bearer ${KEEPTRUSTS_REQUEST_TOKEN}" \
ws://127.0.0.1:41002/v1/responses/ws
Use wss://<published-hostname>/v1/responses/ws for a published TLS endpoint.
Publication and token policy are checked during the handshake.
Provider routing
The gateway selects an HTTP-capable provider target and resolves that provider's upstream authentication before upgrading. Pin a configured target when needed:
X-Keeptrusts-Provider: provider-target-id
An unknown pin fails the handshake with a structured 400 response. A target implemented only as an execution target cannot serve WebSocket traffic.
Frame behavior and policy boundary
After both upgrades succeed, the gateway forwards text, binary, ping, pong, and close messages in both directions. It replaces the client Authorization header with the resolved upstream provider credential.
The WebSocket proxy does not decode application frames or run the HTTP chat/Responses request and response policy-chain evaluation on their contents. Authentication, publication checks, agent binding, and provider selection run at the handshake, but frame-level governance is not currently implemented. Use the HTTP/SSE routes when you require those policy guarantees.
There are no public transport: websocket, ping_interval_secs, or
idle_timeout_secs declarative config keys for this proxy.