gopass is a modern, interactive UNIX password manager wrapper designed for secure, multi-store (e.g., combining independent stores like personal and acme for work), and Git-native secret operations. This guide covers setting up gopass from foundation to team-mount configuration utilizing age encryption.

[!TIP] Since gopass is fully backward-compatible with the standard pass directory structure and commands, you can also review my core UNIX Password Manager (pass) Cheat Sheet for standard references.

🛠️ Foundation & Prerequisites

First, install Xcode command line tools and bootstrap Homebrew (if not already present):

xcode-select --install

cd $HOME
git clone https://github.com/Homebrew/brew homebrew
curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew

export PATH=$HOME/homebrew/bin:$PATH

Install core utilities and dotfile tools:

export HOMEBREW_CASK_OPTS="--appdir=~/Applications"
brew install -q \
    jq yq curl wget coreutils diffutils findutils gawk gnu-sed gnu-tar rsync make just age \
    gopass chezmoi nnn

🔑 SSH Key & Agent Setup

To authorize secure clones and synchronizations with private repositories, generate a hardware-bound SSH key pair:

cd ~/.ssh

# Get platform serial number
export HWSERIAL=$(ioreg -l | grep IOPlatformSerialNumber | awk -F= '{print $2}' | xargs -n1 echo)

# Generate key pair
ssh-keygen -t ed25519 -f id_ed25519_$HWSERIAL

# Authorize your own key locally
cp id_ed25519_$HWSERIAL.pub authorized_keys

Git Deploy Key Authorization

Copy your public key to your clipboard and register it as a Deploy Key with write access on your private Git workspace:

cat id_ed25519_$HWSERIAL.pub | pbcopy

# Paste key as deploy key with write access:
open https://gitea.apealive.net/epcim/passotp-acme/settings/keys

⚙️ Initial Gopass Setup (Using Age Encryption)

We will set up a store using modern, secure age encryption instead of legacy GPG. This setup represents initializing a dedicated work store (acme), which can coexist perfectly with any personal or global stores:

export GPG_TTY=$(tty)

# Setup root crypto interface
gopass setup --crypto age

# Define store name variable (e.g., acme for work, personal for home)
MY_GOPASS_STORE=acme

# Initialize the store as a git-backed age repository (First time only)
gopass init --crypto age --storage gitfs --alias $MY_GOPASS_STORE

# Add remote Git tracking repositories
gopass git remote add --store $MY_GOPASS_STORE git@git.apealive.net:epcim/gopass-$MY_GOPASS_STORE.git
gopass git remote add --store me git@git.apealive.net:epcim/gopass-$MY_GOPASS_STORE.git

🔄 Cloning an Existing Store (New Machine)

If you are setting up a new laptop, you can clone your existing encrypted store directly:

# Clone the repository natively using gitcli
gopass clone git@git.apealive.net:epcim/gopass-acme.git acme --gitcli

# Sync and verify list
gopass sync
gopass list acme

🔄 Recipient Management & Key Rotation (Access Control)

Since age is built for modern, lightweight cryptography, rotating keys or onboarding/offboarding teammates is exceptionally elegant.

Under the hood, gopass tracks authorized keys inside a .age-recipients file in the root of your secrets repository. Adding or removing keys automatically triggers a background re-encryption of all secret payload files with the updated set of public keys.

1. Listing Authorized Recipients

To view all public keys currently authorized to decrypt secrets:

gopass recipients

2. Onboarding a New Key (Key Rotation)

When a team member gets a new machine, or when you rotate your own primary identity key, generate the new key pair, copy the public key, and authorize it:

# Add a new recipient (gopass will auto-reencrypt all secrets instantly)
gopass recipients add age1newrecipientkeyplaceholder0000000000000000000000000

3. Revoking a Key (Offboarding)

To revoke access or complete a rotation, remove the old public key from the store. Once removed, gopass strips the recipient and instantly re-encrypts all files using only the remaining authorized keys:

# Revoke an old recipient (gopass will auto-reencrypt and secure all secrets)
gopass recipients remove age1oldrecipientkeyplaceholder0000000000000000000000000

Finally, synchronize the rotation changes with your Git remotes to propagate access controls:

gopass sync

💡 Practical Configuration Tweaks

To prevent repetitive passphrase prompts on macOS, configure age to securely leverage your native system keychain:

gopass config age.usekeychain true