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.

An agent requesting a secret (intake)

When an agent needs a secret that isn’t in the vault yet, it doesn’t ask you to paste one into the chat. It files a request — the coordinate only, never a value — and you fulfil it out-of-band (the menu-bar app, the Dashboard, or kovra intake). The value goes from your keystrokes straight into the vault; the agent only learns the secret now exists. See Agent-initiated intake.

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.

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 (Dashboard)

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.