Configure gpg-agent for Pinentry, SSH and Caching

gpg-agent is the background process that actually holds your GnuPG keys. Get its pinentry or cache setting wrong and passphrase prompts vanish, or reappear at the worst moment. This guide targets the installed GnuPG 2.4.4 package on Linux, covering pinentry, optional SSH key support and cache lifetimes. Allow about 10 minutes if GnuPG and a pinentry program are already installed.

Before you start

Check both before changing configuration:

gpg --version
gpg-agent --version
command -v pinentry || command -v pinentry-basic

On this system the agent reports gpg-agent (GnuPG) 2.4.4. The pinentry path is installation-dependent. If the last command prints nothing, install the pinentry package supplied by your Linux distribution, then repeat the check.

Checkpoint: You should have a GnuPG version, an agent version, and a path such as /usr/bin/pinentry or /usr/bin/pinentry-basic.

1. Give pinentry the current terminal

Add GPG_TTY to the shell startup file that runs for your interactive sessions. The value must be recalculated for each terminal, so use $(tty) rather than copying a one-time device name. Append this line to ~/.bashrc if Bash is your shell:

export GPG_TTY=$(tty)

Open a new terminal, or load the file in the current one:

. ~/.bashrc
echo "$GPG_TTY"
test -t 0 && echo "interactive terminal"

The printed value should resemble /dev/pts/3. If it is empty, you loaded the setting from a non-interactive shell or placed it in a startup file your shell does not read. For another shell, put the same export in its own interactive startup file.

Checkpoint: You should see a terminal device such as /dev/pts/3 and the text interactive terminal.

2. Confirm on-demand startup and pinentry

You normally do not start gpg-agent by hand: GnuPG tools start it on demand. Ask the agent to initialise its sockets, then inspect the directories GnuPG is using:

gpg-connect-agent /bye
gpgconf --list-dirs agent-socket agent-ssh-socket

The first command should exit without an error. The second prints paths for the native agent socket and, when available, the SSH agent socket. Run a harmless GnuPG operation that can prompt for your passphrase, such as signing a test file, when you are ready to test pinentry. Do not paste a real passphrase into a shell command or into a script.

If pinentry is not found at its default name, set it explicitly in ~/.gnupg/gpg-agent.conf. Create the directory first only if it does not exist, and keep its permissions private:

mkdir -p ~/.gnupg
chmod 700 ~/.gnupg
printf '%s\n' 'pinentry-program /absolute/path/to/pinentry' >> ~/.gnupg/gpg-agent.conf

Replace the placeholder with the path printed by command -v. This changes a per-user configuration file. To undo this exact change, remove the corresponding pinentry-program line with an editor, then reload the agent.

3. Set cache lifetimes deliberately

A shorter cache reduces the time an unlocked key stays usable; a longer cache reduces prompts while you work. For example, this configuration keeps ordinary passphrases cached for five minutes, SSH passphrases for 15 minutes, and caps either at one hour:

default-cache-ttl 300
default-cache-ttl-ssh 900
max-cache-ttl 3600
max-cache-ttl-ssh 3600

These are option-file forms, so they have no leading dashes. Add them to ~/.gnupg/gpg-agent.conf only after deciding that the policy suits the machine. The file is sensitive configuration; back it up with the rest of your GnuPG home, but protect the backup.

Warning: the cache holds passphrase-derived key material inside the running agent. It is not a replacement for locking your session, protecting your account, or removing a key from a compromised host.

4. Enable SSH use only when you need it

On Unix, the OpenSSH protocol is implemented, but SSH_AUTH_SOCK is set for it only when SSH support is enabled. Add this line to gpg-agent.conf:

enable-ssh-support

Then set the socket in your shell startup file:

unset SSH_AGENT_PID
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then
  export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
fi

Reload the agent and check the environment:

gpgconf --reload gpg-agent
. ~/.bashrc
echo "$SSH_AUTH_SOCK"
ssh-add -l

ssh-add -l may report that no identities are loaded, which is a useful distinction from a missing socket. Add a private SSH key with ssh-add /path/to/key only when you have verified the path and intend to cache that key: the agent stores the imported key in its own private-key directory. To remove it later, use ssh-add -d /path/to/key, or clear all loaded SSH identities with ssh-add -D after checking the command.

If a signature prompt appears on the wrong terminal, run:

gpg-connect-agent updatestartuptty /bye

5. Reload or stop the agent safely

gpgconf --reload gpg-agent asks a running agent to reread its configuration. Only selected options are reloaded, including pinentry choice and several cache settings. If a change does not take effect, stop the agent and let GnuPG start a fresh one:

gpgconf --kill gpg-agent
gpg-connect-agent /bye

Warning: this flushes cached passphrases and disrupts current operations, so do it when no signing, decryption or SSH authentication is in progress. It does not delete your keys or configuration: the next GnuPG operation starts the agent again.

Done means