Flows

kovra moves a secret in a few distinct ways. Each flow below is one scenario, with a diagram showing the path the value takes — and, just as importantly, where it is not allowed to go. They all run through the same underlying check; see the decision process for how that check works.

Process injection

The everyday flow. You wire variable names to coordinates in .env.refs, run your tool through kovra, and the resolved values go straight into the process — never to disk, argv, or your screen. The value is used, not seen.

The value enters the process directly — never disk, argv, or screen.

An agent using a secret (MCP)

The flagship flow. An AI agent works under a scope: it reads metadata and can have kovra inject secrets into the commands it runs, so they work — but the sensitive plaintext never enters the model’s context, the one place a prompt-injection attack could exfiltrate it.

Revealing a secret to a human

Sometimes you need the value yourself. A reveal is judged by sensitivity: an ordinary secret is shown; a high one is shown only after a bioProve; the most protected (inject-only) is never shown — it can only be injected. An agent can never trigger this for you.

Sharing a secret set (sealed package)

To hand secrets to someone else, kovra seals a non-production set to the recipient’s public key. Only that recipient can open it — with their own identity — and a separate one-time access token travels a different channel to authorize the most sensitive entries. Production secrets are refused outright.

Production secrets are refused — never packaged.

Bootstrapping a new machine (USB exchange)

The full offline handoff to a machine that has no kovra yet. The USB stick makes two trips — out with the tooling, back with the destination’s identity, out again with the sealed package — and the access token travels separately. Every destructive or sensitive step is gated by a bioProve, and production is excluded.

Authenticating with a custodied key (ssh-agent)

kovra can act as a governed ssh-agent: an SSH or git client sends a challenge, kovra signs it in memory with a custodied key, and returns the signature. The private key never leaves kovra and never touches disk; high/prod keys require a confirmation on every signature.

Signed in memory — the private key never leaves kovra; high/prod confirm each time.

Administering from the browser (Web UI)

An on-demand admin UI, launched behind a confirmation and bound to loopback only. It shows ordinary values but never renders the plaintext of high or inject-only secrets — those appear masked, with a fingerprint, and reveal only through the CLI.

Loopback only — never exposed to the network.