On macOS, a properly tuned gpg-agent setup keeps SSH keys and OpenPGP decryption responsive and secure. This example gpg-agent config for Mac balances practical launchd integration with clear security boundaries for everyday command line workflows.
Use the table below to quickly compare common gpg-agent behaviors and configuration options relevant to macOS users.
| Option | Default | macOS Notes | Security Impact |
|---|---|---|---|
| default-cache-ttl | 600 | Often increased for smoother CLI use in workflows | Lower values reduce exposure if keys are left accessible |
| max-cache-ttl | 21600 | Set to match local policy or organizational sessions | Upper bound prevents indefinite caching |
| enable-ssh-support | no | Turn on to use gpg-agent as an SSH auth agent on macOS | Broadens trust boundary; requires tight socket controls |
| pinentry-program | pinentry-curses | macOS users typically switch to pinentry-mac or GUI options | Choose audited frontends and disable unused protocols |
| allow-loopback-pinentry | not set | Required for certain SSH and cron workflows on macOS | PIN through loopback reduces exposure compared to external prompts |
Setting Up the Example Gpg-Agent Config on Mac
Start with a minimal ~/.gnupg/gpg-agent.conf that focuses on macOS specifics. Define socket behavior, cache timings, and the correct pinentry helper for GUI or terminal prompts. Avoid overloading the config with experimental options until the baseline is stable.
Core Options for macOS
Set default-cache-ttl and max-cache-ttl to values that match how long sessions typically remain local. On macOS, choose a pinentry-mac binary for native keychain integration and set allow-loopback-pinentry so SSH and unattended scripts can still prompt securely. Disable any protocols you do not use to shrink the attack surface.
Files and Permissions
Ensure ~/.gnupg and all files inside it are readable and writable only by your user. On macOS, restrictive permissions prevent other local users or processes from hijacking your gpg-agent socket. Restrict write access to the control socket and avoid world-readable settings.
Launchd Integration and Startup
macOS launchd is the preferred mechanism to start gpg-agent per user. Create a property list that exports GPG_TTY and initializes the agent before shells start. This keeps environment variables consistent for both terminal and GUI-launched tools. Use standard LaunchAgents directories and avoid relying on global launchd daemons for personal keys.
Environment Variables and Shell Integration
Configure shell startup files to read GPG_TTY from launchd and export GPG_AGENT_INFO when necessary. Modern GnuPG versions may rely more on systemd or macOS launchd sockets, but explicitly setting these variables avoids 'gpg: no running gpg-agent' errors. Keep your shell config focused on detection rather than hardcoded paths.
Troubleshooting Common macOS Issues
When the macOS GUI pinentry does not appear, check whether launchd environment blocks are preventing communication. If SSH keys fail to load, verify that enable-ssh-support is set and the allowed-valid-for-ssh option is present. Use gpg-connect-agent to list sockets and confirm that the agent is reachable and not stuck in a loopback retry state.
Maintenance and Security Best Practices
Treat your gpg-agent configuration as part of ongoing macOS system hygiene. Rotate keys periodically, revoke unused subkeys quickly, and keep GnuPG updated to benefit from macOS-specific fixes. Combine sensible cache settings with strict file permissions to maintain both usability and confidentiality.
- Define cache timeouts that match your typical session length without being excessively long.
- Prefer pinentry-mac or approved GUI pinentry programs for native macOS keychain integration.
- Restrict file and socket permissions under ~/.gnupg to your user only.
- Enable SSH support only when necessary and confirm socket paths in use.
- Monitor launchd logs for irregularities after macOS or GnuPG updates.
FAQ
Reader questions
Why does my gpg-agent not show the macOS GUI pinentry when I run gpg commands?
Check that ~/.gnupg/gpg-agent.conf sets pinentry-program to pinentry-mac and that allow-loopback-pinentry is enabled. Also verify that GPG_TTY is exported correctly and that no other agent is already bound to the default socket.
Is it safe to enable-ssh-support on my Mac for daily development work?
Yes, it is safe if you restrict socket permissions and do not bind the agent to overly broad network interfaces. Treat SSH support as an extension of your local key management rather than a remote exposure mechanism.
How can I avoid entering my PIN repeatedly when using scripts on macOS?
Use default-cache-ttl and max-cache-ttl values that align with your interactive session length. Combine this with allow-loopback-pinentry so scripts running under your user can cache within the defined time bounds without external prompts.
What should I do if gpg-agent keeps restarting on macOS after updates?
Review launchd logs for permission denials on ~/.gnupg or socket files. Ensure your config syntax is valid by running gpg-connect_agent 'help' /bye and fix any deprecated options. Reinstall GnuPG through a trusted package manager if persistent startup errors appear.