This post is about a portable Unix shell script, socklink.sh, written to keep SSH_AUTH_SOCK working within a long-running tmux session—even when switching between multiple clients that have different SSH agents, whether those clients are simultaneously connected or attaching and detaching over time. I also digresses into what I’ve learned from writing and testing a cross-platform shell script in 2025.
Target audience
If you’re reading this I’ll assume you have some knowledge of Secure Shell agent forwarding and how the SSH_AUTH_SOCK environment variable works. I also expect you already have SSH clients configured to use agent forwarding.
The problem
I use tmux almost everywhere I SSH to. I’m also a fan of hardware tokens with proof-of-presence for SSH authentication. [1]
But out of the box, this combination introduces major usability problems when I connect to my dev server from multiple clients. SSH agent requests need to be directed to whichever client I’m currently using so that I can provide proof-of-presence, like by touching the contacts on a YubiKey or using Face ID in Termius. However, in practice the request will go to whichever agent was defined when tmux started. Even if that one is no longer connected!
Different workarounds for scenario this have emerged. A previous employer had a wrapper script called tmx that would fix up SSH_AUTH_SOCK when re-attaching a session from a new client. Meanwhile, this popular gist uses ~/.ssh/rc to override SSH_AUTH_SOCK to the path of a symlink that can be updated as new clients connect. Other solutions involve configuring tmux’s update-environment to reconfigure the session-wide environment when new clients join.