FABIAN

tmux-pinentry: Easy Pinentry for Remote Workspaces

// 3 min read

Short overview of a small tool for having easier pinentry via TMUX

tmux

So I work a lot in a remote dev workspace. And recently I started using gopass and other tools for secret management, this way I don’t have any tokens and keys lying around in environment variables or files.

And since I like to have the gpg password expiry set to 1 (meaning it will always ask for the password again), I need to enter my password every time I need a secret. Which is great, this way I can see when secrets are used.

The Annoyance: GPG Pinentry in Headless or Nested Worlds

The problem is, most GPG pinentry programs expect a graphical environment or a direct TTY to do their thing. When you’re running tmux and especially when you’re inside a terminal application like Neovim that’s taking over your current pane, GPG gets confused. It tries to ask for a password, but there’s no “nice” place for it to show up. You end up with a frozen terminal, or a prompt appearing somewhere you really don’t want it.

My Solution: tmux-pinentry

Since I couldn’t find any pinentry that would use TMUX or some other way of asking for the password when the TTY is pretty occupied, I built my own using a simple bash script and it’s been a game-changer for my workflow.

What does it do? It brings those pesky GPG password prompts right into a tmux popup window.

See it in action:

How It Works

It’s quite simple. When GPG needs a password, it calls a pinentry program. Instead of calling a graphical one or a basic TTY one that might freak out in neovim or whatever, you configure GPG to call the pinentry-tmux script.

This script then uses tmux commands to conjure up a temporary popup, shoves the password prompt in there, you type your password, hit enter, and it sends it back to GPG.

All without ever leaving your current tmux pane.

Getting It Set Up

It’s a breeze to get running:

  1. Fallback Pinentry: Edit pinentry-tmux.sh to point to your preferred fallback pinentry (like pinentry-curses or pinentry-tty). This is what it will call if you’re not in a tmux session.
  2. Path It: Drop the script (maybe rename it to pinentry-tmux for simplicity) into your $PATH, e.g., ~/.local/bin/.
  3. Tell GPG: Configure GPG to use pinentry-tmux as its pinentry program. Usually, this means adding something like pinentry-program /path/to/pinentry-tmux to your ~/.gnupg/gpg-agent.conf.
  4. Tiny TMUX config: For it to know you’re in TMUX, set PINENTRY_USER_DATA="tmux" in your TMUX config.