# 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.