feat(agent-proxy): add a websocket substitution surface

[saifsmailbox98]

Context

Adds websocket as a proxied-service substitution surface, for real-time services that expect the credential in the first message after the connection opens rather than in the handshake. Handshake credentials are already covered by the existing header / path / query surfaces, since an upgrade request is an ordinary HTTP request.

No migration: substitutionSurfaces is a plain text array with no DB-level enum, so the Zod nativeEnum is the only gate. Telemetry picks the value up for free through the existing substitutionSurfaces property on Proxied Service Created.

Frontend: added to the surface picker as "WebSocket Message". SURFACE_LABELS is exhaustive over the enum, so this was required rather than optional.

Docs: a WebSockets section on Proxied Services covering where a credential can sit, that the proxy swaps a reflected credential back to the placeholder, and what is forwarded unchanged (binary, split, oversized). Also notes that compression is declined on connections using this surface, and recommends wss:// for anything carrying a credential. Standalone Proxy and Local Proxy previously implied WebSockets were unsupported and now point at it.

Companion CLI PR: Infisical/cli#356

Screenshots

Steps to verify the change

Type

• Fix
• Feature
• Improvement
• Breaking
• Docs
• Chore

Checklist

• Title follows the conventional commit format: type(scope): short description (scope is optional, e.g., fix: prevent crash on sync or fix(api): handle null response).
• Tested locally
• Updated docs (if needed)
• Updated CLAUDE.md files (if needed)
• Read the contributing guide

[linear]

AGE2-52

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
infisical	🟢 Ready	View Preview	Aug 7, 2026, 10:37 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[infisical-review-police]

💬 Discussion in Slack: #pr-review-infisical-7581-feat-agent-proxy-add-a-websocket-substitution-surface

Posted by Review Police — reviews, comments, new commits, and CI failures will stream into this channel.

[greptile-apps]

Greptile Summary

The PR adds websocket as a proxied-service substitution surface across the backend and frontend, then documents message substitution and WebSocket transport behavior.

• Extends backend and frontend substitution-surface enums.
• Adds “WebSocket Message” to the surface picker.
• Updates API descriptions and Agent Proxy documentation with WebSocket behavior and limitations.

Confidence Score: 4/5

The PR appears safe to merge after considering two non-blocking documentation improvements, most importantly an explicit warning against sending brokered credentials over ws://.

The enum and UI changes follow the existing validation and persistence path; the remaining accepted concerns are public-documentation clarity and cleartext WebSocket guidance rather than demonstrated runtime breakage.

Files Needing Attention: docs/documentation/platform/agent-proxy/proxied-services.mdx; docs/documentation/platform/agent-proxy/standalone-agent-proxy.mdx

Security Review

The new documentation permits brokered credentials over ws:// without distinguishing its cleartext transport from wss://; add an explicit warning or recommend wss:// for credential-bearing connections.

Important Files Changed

Filename	Overview
backend/src/ee/services/proxied-service/proxied-service-enums.ts	Adds the websocket enum value accepted by the existing native-enum validation and text-array persistence path.
frontend/src/hooks/api/proxiedServices/enums.ts	Mirrors the backend websocket substitution-surface value for frontend API types.
frontend/src/components/proxied-services/forms/SurfaceSelect.tsx	Adds an exhaustive, title-cased label for selecting WebSocket message substitution.
docs/documentation/platform/agent-proxy/proxied-services.mdx	Documents outbound WebSocket substitution and limits, but includes avoidable proxy implementation details.
docs/documentation/platform/agent-proxy/standalone-agent-proxy.mdx	Advertises ws:// credential brokering without warning that credentials are transmitted over cleartext.
docs/documentation/platform/agent-proxy/local-agent-proxy.mdx	Adds a concise cross-reference to the WebSocket documentation.
backend/src/lib/api-docs/constants.ts	Adds websocket to the documented substitution-surface values and clarifies that it applies after upgrade.

_{Reviews (1): Last reviewed commit: "feat(agent-proxy): add a websocket subst..." | Re-trigger Greptile}