Skip to content

This document is a WORK IN PROGRESS.
This is just a quick personal cheat sheet: treat its contents with caution!


Keychain helps you to manage SSH and GPG keys in a convenient and secure manner. It acts as a front-end to ssh-agent and ssh-add, but allows you to easily have one long running ssh-agent process per system, rather than the norm of one ssh-agent per login session. This dramatically reduces the number of times you need to enter your passphrase. With keychain, you only need to enter a passphrase once every time your local machine is rebooted.


Table of contents


# apk add keychain
# apt install cronie
# dnf install cronie
# emerge -a net-misc/keychain
# nix-env -iA nixos.keychain
# nix-env -iA nixpkgs.keychain
# pacman -S keychain


# xbps-install -S keychain
# zypper install keychain


Assuming you have id_rsa and id_bis_rsa key pairs in your $HOME/.ssh/ directory, you can do the following:

$ mkdir ${XDG_CONFIG_HOME:-${HOME/.config}}/keychain

$ vi $HOME/.bashrc # or ${ZDOTDIR:-${HOME}}/.zshrc or wherever
    > ...
  + >
  + > # keychain
  + > #
  + > # prerequisite:
  + > #   * keychain:
  + > #
  + > # see:
  + > #   *
  + > #
  + > eval `keychain --dir $XDG_CONFIG_HOME/keychain --agents ssh --eval id_rsa id_bis_rsa`


  • Sometimes, it might be necessary to flush all cached keys in memory (but note that any agent(s) will continue to run):

    $ keychain --clear

  • List signatures of all active SSH keys, and exit (similar to ssh-add -l):

    $ keychain --list

  • Kill currently running agent processes.

    • Kill all agent processes and quit keychain immediately:

      $ keychain --stop all

    • Kill agent processes other than the one keychain is providing. Prior to keychain-2.5.0, keychain would do this automatically. The new behavior requires that you specify it explicitly if you want it:

      $ keychain --stop others

    • Kill keychain's agent processes, leaving other agents alone:

      $ keychain --stop mine

If this cheat sheet has been useful to you, then please consider leaving a star here.