Secrets

The Secrets page is the Desktop view of the local secrets vault behind ak secrets. After this page you will know how to add and reveal values, answer requests agents leave waiting, react to a release, and read the audit log. For how grants, backends, and limits work, see the Secrets vault guide.

Manage stored values

The page lists every name stored on this machine with Added by, Created, Rotated, and Grants, and marks a value past its rotation window with Rotation due. Tiles count Secrets, Grants, and Unused names that no agent has been granted yet.

• Add secret stores a new value; Rotate replaces one and Delete removes it. Pasting into a value field clears the clipboard where the app is allowed to.
• Import .env adds names from a dotenv file. By default it only adds names the vault does not already have. With Replace names that already exist on, you must preview the import first, and the preview lists what it would overwrite.
• Reveal asks for a reason, records it in the audit ledger, and then shows the value. If you copied the value, the clipboard is cleared when the dialog closes, however it closes.
• Export does not export from the window. It shows the ak secrets export commands to run in a terminal, where a values export is written only to an age-encrypted file.

The vault uses the OS keychain by default. With the file backend, the page asks for the vault passphrase to unlock it; Desktop keeps the passphrase only for this run of the app, and Lock locks the vault again.

The Grants panel lists which agent binary may read which name. Grant and revoke from a terminal with ak secrets grant and ak secrets revoke.

Answer waiting requests

When an agent asks for a secret that no grant covers, the request waits in the Waiting for you panel. Open one to see which agent asks, for which secret, project, and purpose, then choose one of four answers:

Deny has focus when the dialog opens, and the single-key shortcuts (D, O, S, A) work only after the dialog has been on screen briefly. Decide later or Escape closes the dialog and leaves the request waiting. An answer writes the same grant rows as ak secrets approve, whose own default window is 24 hours.

If an agent started this Desktop process, Desktop refuses the answer, records it as a denial, and tells you to answer from a Desktop app or terminal you opened yourself. This stops an agent from approving its own request in the obvious way; it is not a hard boundary.

Watch secret releases

While Desktop is open, each release to an agent or a terminal shows an in-app notice naming the secret, the agent, and the project. Revoke this agent's grants removes every grant that agent binary holds, the same as ak secrets revoke --agent sha256:<hash> --all; Dismiss hides the notice. Your own reveals are not announced back to you.

While the window is not focused or not visible, each release also raises one OS notification titled Secret released. Its body names the secret, who it was released to, and the project, never the value or the purpose. When one check finds more than four new releases, the rest are folded into a single summary notification. OS notifications are best effort: on macOS they need the app's notification permission, which you can grant later in System Settings if you declined it. The in-app notice and the audit log stay complete either way.

Revoking stops future reads only. Rotate a secret an agent should no longer hold.

Read the audit log

Audit log opens Secrets audit, newest first: every resolve, block, and operator answer, never a value. Filter by secret name, by decision (Allowed, Blocked, Denied), or by source (Agent, Terminal, Desktop). Each row shows when, the secret, the agent, the purpose, the source, the decision, and the reason. The same ledger is available in a terminal with ak secrets audit.