sherlock/docs/gssh-integration.md

gssh integration

gssh-mcp is a client to the existing Gssh gateway. Sherlock does not open SSH connections, mint certificates, enforce host policy, or duplicate Gssh audit behavior.

Gssh owns JWT validation, host allow-lists, ephemeral SSH certificate handling, and command execution. Sherlock obtains the operator's OAuth token and passes it to gssh-mcp, which calls Gssh over HTTP and WebSocket.

Current contract used by sherlock:

Endpoint	Purpose
GET /api/v1/session/hosts	Host allow-list.
POST /api/v1/session/initialize	Ensure a Gssh session/certificate exists.
GET /api/v1/users/me	Probe/debug identity.
WS /api/v1/exec/{host}	Single-command execution stream.

If that contract changes, cmd/gssh-mcp/ is the only sherlock area that should follow.