---
layout: book_post
title: "So You're Confused About SSH Agent Again?"
series: "Notes to Self"
date: 2026-05-29
published: false
---
Changing PC can be hard.
You have to migrate all your configurations, install all your tools and set up your workflows just to get things 'normal'.
You go from everything working nicely on the old machine to the chaos of having to relearn a hundred and one things - knowing that you used to know how to do this, but can't remember for the life of you how to do it know.
I have found myself in this situation many a time.
The trouble is, I find, that PC migrations come just frequently enough to be a regular hurdle to overcome, but not quite frequently enough for me to build up the mental muscle memory for clambering over said hurdle.

Very recently, I was in this exact conundrum.
I had just installed Debian 13 on a desktop and needed to set up my SSH keys.
Thankfully, I generate keys often enough that I didn't find this too confusing, but I vaguely remembered that I also had do something with `ssh-agent`.
But lo and behold, I could not remember what!

After fettling and fiddling for a few days, I think I have it all straight in my mind.
So in an attempt to prevent such confusion next time I set up SSH keys on a new PC, I write this little note.

# What is ssh-agent?
When one creates a new SSH key with `ssh-keygen`, one has the option of providing a password.
This, in my opinion, should always be done.
The password is used to encrypt the private key on disk, so that if, heaven forbid, a malicious actor gets access to your files they cannot steal your private key and thus your identity.
But one, admittedly minor, downside is that you must type in that password every single time you want to use that key.
This can be annoying.
It is the job of `ssh-agent` to solve this issue.

`ssh-agent` is a program that will store the decrypted private key in memory for you after you have decrypted it once.
Then, any time that key is required by SSH, it can get it from the agent and you don't have to enter in your password.
But you must remember, the plain key is only stored in _memory_.
If the computer restarts, it's gone, and you must enter the password to decrypt the private key.

# How Does ssh-agent Work?
Now I am no expert, but my understanding is as follows.
`ssh-agent` exposes a socket when it is running, through which programs such as ssh can talk to it.
The details of this communication are unknown to me and are not required for this set up, but it is something to put a pin in.
In order for `ssh` to communicate with `ssh-agent` over this socket, it must know where this socket lives.
For that, it looks in the `SSH\_AUTH\_SOCK` environment variable.
If this variable is not set, then `ssh` will not be able to use the agent.

Once communication is established between the program and the agent, one of two things could happen.
Either the agent has a decrypted copy of the requested key available, or it does not.
If it does, the key is given to the program and the user does not have to intervene.
Happy days.
However, if it does not, then the program[^1] must access the encrypted key on disk and get the user to enter the password.

[^1]: Note that I do not know for sure if it is the program or the agent that is doing the actual access and decrypting, but I assume it is the program

So the question is, how does the SSH Agent get the decrypted key in the first place?
To my knowledge, this can happen in one of two ways.
The first is with `ssh-add`.
By providing the path to a _private_ key, the program will decrypt it (by asking for the password) then save it to the agent.
Now remember, the agent is not storing anything on disk, so when the computer is restarted the key will no longer be with the agent[^2].

[^2]: A handy way to see what keys the agent has is to run `ssh-add -l`

The second way is to configure the key to automatically get added to the agent when it is used.
This is done in the SSH config file, often found at `~/.ssh/config`.
In the entry for the key, add the line `AddKeysToAgent yes` and it will automatically be saved in the agent the first time it is decrypted by `ssh`.

It is also worth noting, that each `ssh-agent` instance has it's own memory, thus if you have multiple agents running at once, adding keys to one will not add them to all.

# The Checklist
In order to get `ssh-agent` set up, you'll need to do the following:
 1. Ensure `ssh-agent` is running by the time you need it
 2. Ensure that the environment variable `SSH\_AUTH\_SOCK` is available by the time you need it
 3. Ensure that `AddKeysToAgent yes` is in the config for any keys you want to be added to the agent

So there you have it.
Hopefully that is enough information to at least jog your memory, if not get `ssh-agent` set up in its entirity.
If you need to know more, then have a look at the following `man` pages:
 * `ssh-agent`
 * `ssh-add`
 * `ssh_config`