From bc1c168d4941a91ff2d169d63c6ddb998450fdbb Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Tue, 28 Jul 2026 17:28:33 -0500 Subject: [PATCH] docs(desktop): explain macOS TCC permission persistence and the keychain identity opt-in --- website/docs/user-guide/desktop.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md index 34ccf2a810bd..bb85133c780b 100644 --- a/website/docs/user-guide/desktop.md +++ b/website/docs/user-guide/desktop.md @@ -318,6 +318,32 @@ npm run pack # unpacked app under release/ (no installer) macOS/Windows signing and notarization run automatically when the relevant credentials are present in the environment (`CSC_LINK` / `CSC_KEY_PASSWORD` / `APPLE_*` for macOS, `WIN_CSC_*` for Windows). +### macOS permissions and local rebuilds (TCC) + +macOS remembers permission grants (Full Disk Access, Desktop/Downloads/Documents, +Accessibility, Automation, microphone) against the app's *code-signing identity*, +not its path. Locally built and self-updated apps are signed with a stable +identifier-pinned ad-hoc signature, so grants persist across updates out of the +box. + +For the strongest guarantee — a certificate-anchored identity, the same +mechanism yabai/skhd users rely on — create a self-signed code-signing +certificate once and tell Hermes to use it: + +1. Keychain Access → Certificate Assistant → **Create a Certificate…** +2. Name: `Hermes Local Signing`, Identity Type: *Self-Signed Root*, + Certificate Type: **Code Signing**. +3. `hermes config set desktop.macos_signing_identity "Hermes Local Signing"` + +The next update re-signs the rebuilt app with that certificate; every TCC grant +survives. No Apple Developer account is required. Notarized release builds are +detected and never re-signed. + +One-time note: changing the signing identity (including the first update after +this fix) changes the app's identity once, so macOS will re-prompt one final +time. Grants are stable from then on. If a permission gets stuck, reset it with +`tccutil reset All com.nousresearch.hermes` and re-grant. + ## See also - [CLI Guide](./cli.md) — the terminal interface