3. How It Works

The whole system in one picture #

The agent talks only to the server. The server holds the kubeconfig, applies static guardrails, writes an audit line and a trace span for every call, and talks to the hub. The hub enforces Kyverno policy and RBAC. A human, on a separate trusted terminal, is the only source of approval tokens.

The read path (free) #

Investigation has no gate. The agent can call any read tool as often as it likes.

Results are summarized, not raw. The agent gets the fields an on-call engineer would look at, not thousand-line objects that burn context.

The write path (gated) #

This is the heart of the design. Four independent checks, in order.

Read the four checks as defense in depth: each fails differently, so a gap in one is covered by the others. Details in Guardrails Deep Dive.

Why approval is a token, not a chat "yes" #

A "yes" in chat approves a conversation. The token approves content. It is an Ed25519 signature over claims that bind the proposal's SHA-256 hash, the operation (apply or rollback), the issuer and audience, a unique id, and an expiry. If the agent changes even one byte of the proposal after approval, the signature no longer verifies, and each token is single-use (its id is recorded as spent, so it cannot be replayed). Approval is asymmetric: the private signing key belongs to the ocm-mcp CLI on a trusted terminal, and the server needs only the public verification key. The "a compromised server cannot mint one" property holds only when that signing key is kept off the server (a separate account or device via OCM_MCP_SIGNER_KEY); co-located under one OCM_MCP_HOME it is a filesystem convention, not a boundary. Tokens expire (default one hour) and are minted only by the CLI, never by any tool the agent can call.

What the human sees #

$ ocm-mcp show 4f1a2b3c
id:       4f1a2b3c
cluster:  cluster2
summary:  Pin payments-v2 to the last known-good image (fixes ImagePullBackOff)
manifests:
  - Deployment shop/payments-v2  image: registry.example.com/payments:1.9.2
$ ocm-mcp approve 4f1a2b3c
About to approve on cluster 'cluster2': Pin payments-v2 to the last good image
Approve? [y/N] y
Approval token (give this to the agent):
4f1a2b3c.1753vwxyz.9a1b...

Ten seconds to review, one keystroke to consent. That is the human's whole job, and it is the job that matters.

Next: Implementation.

Source: wiki/How-It-Works.md — this page is generated from it, so edit the markdown, not the site.