Attended confirmation

kovra confirm exposes kovra’s approval broker as a standalone primitive. It asks a human to bioProve a described action and exits 0 if approved, non-zero if denied or timed out — so any trusted app or script can gate its own action behind a real human, the same way a secret reveal is gated.

It is secret-independent: it needs no vault and no master key. It just opens the broker, shows your description as the authoritative prompt, and reports the verdict through its exit code.

zsh

~ % kovra confirm "Promote build 1.2.3 to staging"
Approval required: Promote build 1.2.3 to staging
Approve at the system prompt (Touch ID, or your login password). Waiting…
Approved.

On a Mac — the platform kovra 0.12.1 ships for — the approval is read and approved in kovra’s review window, with the Touch ID sensor inside it (see Every other approval below). The macOS dialog opens only when you click the fingerprint, or, when the Mac has no Touch ID (or it isn’t set up), after the window shows a short code. Over SSH, or anywhere without a graphical session, the window can’t be shown: with a paired phone, kovra confirm asks in kovra’s approval app on it (kovra Mobile, coming soon); with no paired phone, it denies and exits non-zero: run it from the Mac’s desktop. There is no fallback an agent or script could answer for itself. (kovra approve is for development builds and platforms 0.12.1 doesn’t ship, and it refuses inside a Claude Code session.)

Gate your own action

Because the verdict is an exit code, wiring it into a script is one line:

if kovra confirm "Deploy to production"; then
  ./deploy.sh
else
  echo "Denied — not deploying."
fi

--ttl <seconds> bounds how long it waits before failing safe to a denial (default 120s, at most 300s: a larger value is a usage error).

The description is trusted text

The description is treated as trusted caller text — it’s what the human is approving. Never feed it untrusted or LLM-generated input, or you’d let a caller write the very words used to mislead the approver. To keep it from passing for one of kovra’s own approvals, kovra introduces it as the calling program’s — A program — not kovra — asks you to approve — and shows it escaped, in a frame that says it isn’t kovra’s, so it can’t add lines that read as kovra’s own.

Runs with production secrets

A kovra run that delivers a high or prod value is approved in kovra’s own review window instead, with the Touch ID sensor inside it. The window shows the command and the file that runs, the folder, which variable gets which secret (⚠ PROD marks production) and who asks. Read it and touch the sensor to approve; press Esc or ✕ to deny. Esc and ✕ do nothing for the first 1.5 seconds, so a key you were typing elsewhere can’t deny by accident, and the ✕ fills up as the time runs out.

• The sensor listens only while you can be reading the window: it has the focus, nothing of another app is above it anywhere on screen or beside it without the dimming kovra lays over the rest of the screen, and it stays put and whole on one screen for a moment. The line under the command says what the sensor is doing.
• If the window loses the focus, doesn’t get it in its first half second, or another app’s window comes above it, Touch ID waits for you to click the window (Click this window to enable Touch ID), and the sensor’s place shows a dimmed Touch ID symbol struck through, as if disabled. Only a click from your mouse or trackpad counts: a click posted by another program doesn’t.
• Click the fingerprint to answer in the macOS dialog instead, with the run’s full text; it takes Touch ID or your login password. While the window waits for your click, a click on the struck-through symbol made by an assistive tool or another program opens that dialog too, so you can approve with Switch Control, Voice Control, the Accessibility Keyboard or remote control. A click from your own mouse or trackpad there never opens the dialog: it enables Touch ID (if the window didn’t have the focus yet, the first click only gives it the focus). If another app’s window comes over the review window or the macOS dialog, kovra cancels the dialog and the window waits for your click again.
• Without Touch ID at that moment (no sensor, no finger enrolled, locked out), or if the sensor in the window fails, the window shows a short code and an Approve with Touch ID button, and the macOS dialog that follows repeats the code.

Only one review window is up at a time: a second request waits until the first one closes, and that wait counts against its time.

Every other approval

On a Mac every other approval — revealing a value or a one-time code, deleting, replacing, creating a prod secret, signing (the ssh-agent too), opening the dashboard and kovra confirm — is read and approved in the same window, by the same rules: the sensor inside it, or the code and the macOS dialog without Touch ID. The window shows the same facts the dialog would, each one whole however long: what you approve, the environment (⚠ PROD for production), the project, the secret and who asks. Text a caller wrote is shown last, in a frame that says it isn’t kovra’s. For a reveal the window also says where the value goes, and never shows it: kovra prints it only after the window has closed. For kovra confirm the window’s title is always A program — not kovra — asks you to approve, with the program’s text in a frame of its own. Clicking the fingerprint opens the macOS dialog with the full text, or a short one that points to the window when the text is too long for it; for a reveal that dialog takes only Touch ID.

A sound when kovra asks

An agent may ask for your approval while you’re looking at something else. So on a Mac, every request kovra opens plays a very quiet double click once, when it appears. It follows your Mac’s volume (a muted Mac stays silent) and never plays twice for the same request.

To turn it off, clear Sound for Approvals in the kovra menu-bar menu; select it again to turn it back on. The sound is only a notice: with it on or off, every approval is the same.

Approve from your iPhone

kovra Mobile is coming soon (it is not published yet). With the app paired, each approval can also be answered on the phone with Face ID, and over SSH the phone is the only place to approve. See Approve from your iPhone. To know beforehand whether something will ask you, see Preflight.