Repair macOS Permissions for Hermes Desktop and Computer Use

macOS privacy permissions are managed by Transparency, Consent, and Control, usually called TCC. TCC associates grants with an app's code-signing identity rather than simply with the path where the app sits. A rebuild that changes identity—or launching Hermes through a different host—can therefore leave the active process without the grant you expected.

Computer Use requires Accessibility and Screen Recording. Hermes Desktop may also need microphone, Automation, Full Disk Access, or protected-folder access for the specific feature being used. Repair the failed capability rather than granting every permission preemptively.

Identify the process that needs the grant

First establish how Hermes is running:

If the native Hermes Desktop app launches the backend, grant the Hermes app shown in System Settings.
If a terminal starts Hermes and Computer Use, grant the terminal application that owns the running process.
If the diagnostic reports no bundle identity, repeatedly toggling permissions may not help because macOS cannot attribute the grant correctly.

Hermes' official Computer Use guide explicitly says to allow your terminal or the Hermes app under System Settings → Privacy & Security → Accessibility and Screen Recording. The correct row is the one hosting the active process, not necessarily the row you enabled in an earlier setup.

Check the backend before touching TCC

A missing driver is an installation problem, not a privacy-database problem. Check it first:

hermes computer-use status
hermes computer-use doctor

If cua-driver is absent, install it through the stable Hermes command and check again:

hermes computer-use install
hermes computer-use status

Running hermes tools and enabling Computer Use invokes the same upstream installer. Do not reset permissions merely because the toolset was disabled or the binary was not on PATH.

Read the specialized doctor output

hermes computer-use doctor runs cua-driver's structured health report. On macOS, its matrix includes checks such as:

bundle_identity
tcc_accessibility
tcc_screen_recording
ax_capability
screen_capture_capability

The command exits 0 when the overall result is healthy, 1 when checks are degraded or failed, and 2 when the cua-driver binary cannot be reached. Use --json when you need machine-readable evidence:

hermes computer-use doctor --json

A failed TCC row tells you which System Settings control to repair. A passing TCC row followed by a failed capability points to a different layer. For example, bundle_identity can advise running the binary inside CuaDriver.app so macOS attributes TCC grants correctly. Follow the diagnostic hint rather than guessing at unrelated permissions.

Re-grant Accessibility and Screen Recording

Open System Settings → Privacy & Security and review these controls:

Under Accessibility, enable the terminal or Hermes app that actually hosts the session.
Under Screen Recording, enable that same host.
If macOS asks the app to quit and reopen, complete that handoff before rerunning diagnostics.

The user should make these privacy decisions manually. An agent should not click its own permission dialogs. After changing the toggles, rerun:

hermes computer-use doctor

A healthy result should show both TCC checks and the downstream AX and screen-capture capability checks passing. Then start a fresh Hermes session with the toolset enabled and perform a harmless capture before attempting clicks or typing.

Reset a stuck Hermes Desktop permission

Use tccutil only when the correct Hermes Desktop row remains stuck after a normal re-grant. The documented bundle identifier is com.nousresearch.hermes.

For a microphone prompt that will not recover:

tccutil reset Microphone com.nousresearch.hermes

For a broader Hermes Desktop TCC reset:

tccutil reset All com.nousresearch.hermes

The broad reset revokes existing grants for Hermes Desktop, so it is a last repair step, not routine maintenance. Reopen the app and grant only the capabilities required by the workflow. These commands target the Hermes Desktop bundle; they do not reset the permissions of a separate terminal application.

Stabilize permissions across local rebuilds

Hermes Desktop's local and self-updated builds use a stable, identifier-pinned ad-hoc signature so grants should persist across ordinary updates. Developers who want a certificate-anchored local identity can create a self-signed code-signing certificate in Keychain Access:

Open Certificate Assistant and choose Create a Certificate.
Name it Hermes Local Signing.
Choose Self-Signed Root as the identity type and Code Signing as the certificate type.
Configure Hermes to use it:

hermes config set desktop.macos_signing_identity "Hermes Local Signing"

The next update signs the rebuilt app with that certificate. Changing the signing identity changes the app identity once, so macOS can prompt one final time; grants should then remain stable. Hermes detects notarized release builds and does not re-sign them.

Separate permission faults from UI faults

If the doctor passes but an action still fails, the problem may not be TCC. Re-capture after every state-changing action because element indices can become stale. A hidden modal can block clicks. Some macOS applications with custom drawing expose sparse accessibility trees, so a screenshot may work while AX elements are limited. For web-only work, the browser toolset avoids desktop TCC overhead and may be the better surface.

Pitfalls

Do not grant the wrong host. A green toggle for an unused terminal does not authorize Hermes Desktop, and the reverse is also true.
Do not start with tccutil reset All; it removes good grants along with the broken one.
Do not use the Hermes Desktop bundle identifier to reset an unrelated terminal application's permissions.
Do not interpret a missing cua-driver binary as a Screen Recording failure.
Do not assume an app's filesystem path defines its TCC identity; code signing is the important identity boundary.
Do not let an agent approve its own macOS privacy prompts or type passwords to work around a failed grant.

Verification checklist

Verify hermes computer-use status resolves a cua-driver binary and version.
Verify hermes computer-use doctor exits successfully rather than merely printing some passing rows.
Verify tcc_accessibility and tcc_screen_recording pass for the process that actually hosts Hermes.
Verify ax_capability and screen_capture_capability pass after the TCC repair.
Verify a fresh session can perform a harmless capture before any click or typing test.
Verify microphone access separately when repairing Hermes Desktop voice input.
Verify a local rebuild uses the intended stable signing identity and that any one-time re-prompt was completed.