Approvals

Every request that uses a secret waits for you, and you approve this use — not the agent in general. The prompt starts with what matters most and then shows everything that decides where the value goes:

run_with_secrets	http_request
use pg-staging → /opt/homebrew/bin/psql	send github → https://api.github.com
arguments, stdin text, environment variables, temp-file contents, working directory	method and URL, every header, the start of the body

Placeholders appear as {{secret:NAME}} — the value itself is never in the prompt. Newlines, terminal escapes, bidi overrides and zero-width characters are shown escaped, so the text cannot be disguised. A request too long to show in full (more than 700 characters) is refused before any prompt appears, rather than shown truncated.

Strong and weak methods

	Strong — authenticates you	Weak — only confirms intent
macOS	Touch ID, or your login password	approve from a terminal
Windows	Windows Hello (PIN, fingerprint, face)	Yes/No message box, terminal
Linux	polkit, asking for your password (the details appear in a notification just before it)	zenity / kdialog question, terminal

With the default method = "auto", keymitt always tries the strong method first. It falls back to a weak one only when the strong method is unavailable — no graphical session over SSH, Windows Hello not set up, the polkit action not installed — and only if allow_weak = true.

Cancel means no

If you cancel an authenticating prompt, the request is denied. keymitt never retries with a weaker method after you said no, and the agent is told not to repeat the same request.

To forbid weak methods entirely, set allow_weak = false or method = "native".

Timing

Each decision records how long it took, in elapsed_ms, in the audit log. A person needs a second or more to read a prompt and authenticate; an approval that took a few milliseconds on a prompting method deserves a closer look.

Remembering approvals

ttl_secs remembers an approval for a while — but only for a byte-identical request: the same command, stdin template, environment, files and working directory, or the same method, URL, headers and body. A different request always asks again. The default, 0, asks every time.

Headless machines

On a server without a graphical session, use terminal approvals:

[approval]
method = "cli"

When an agent makes a request, keymitt records it as pending and waits. From another terminal, list the waiting requests:

keymitt pending

then approve one — keymitt shows the request and asks you to type yes — or deny it:

keymitt approve 3f9c2a1b
keymitt deny 3f9c2a1b

approve and deny must be run in an interactive terminal. Terminal approval is still a weak method: any process running as you could write the decision file. Prefer a strong method wherever one is available.

What always needs strong approval

keymitt backup exports every secret value, and keymitt restore can change your policy, so both refuse weak methods regardless of your settings. See Backup and restore.