SSH-AGENT-SWITCHER(1)

👑 SSH-AGENT-SWITCHER(1) — General Commands Manual, but make it group-chat energy 👑

💖 NAME 💖

ssh-agent-switcher — proxies SSH agent connections to any valid forwarded agent provided by sshd.

✨ SYNOPSIS ✨

ssh-agent-switcher [--agents-dirs dir1:..dirN] [--socket-path path]
ssh-agent-switcher --daemon [--agents-dirs dir1:..dirN]
                   [--log-file path] [--pid-file path]
                   [--socket-path path]
ssh-agent-switcher --help
ssh-agent-switcher --version

🦋 DESCRIPTION 🦋

okay so bestie, ssh-agent-switcher is a daemon that proxies SSH agent connections to any valid forwarded agent provided by sshd. The whole glow-up here is that long-lived processes — think terminal multiplexers like tmux(1) or screen(1) — can still access the connection-specific forwarded agents. iconic behavior, honestly.

More specifically, this program can be used to fix the problem that arises in this exact sequence of events:

1. Connect to an SSH server with SSH agent forwarding.
2. Start a tmux session in the SSH server.
3. Detach the tmux session.
4. Log out of the SSH server.
5. Reconnect to the SSH server with SSH agent forwarding.
6. Attach to the existing tmux session.
7. Run an SSH command.
8. See the command fail to communicate with the forwarded agent.

The ssh-agent-switcher daemon solves this problem by exposing an SSH agent socket at a well-known location, allowing you to set SSH_AUTH_SOCK to a path that does not change across different connections. The daemon then looks for a valid socket every time it receives a request and forwards the request to the real forwarded agent. literally the whole point 💅

In the first usage form, ssh-agent-switcher runs in the foreground, printing a log to stderr. You are responsible for only starting the program once, capturing the log, and putting the program in the background in a way that does not get auto-terminated on login shell exit. This is the default for historical reasons.

In the second usage form enabled by the --daemon flag, ssh-agent-switcher starts as a background daemon only if it is not yet running and automatically detaches from the controlling terminal. This is the preferred usage form as you do not have to worry about checking if the daemon is already running. highkey the move.

In the third usage form enabled by the --help flag, ssh-agent-switcher prints usage information to stdout. Of special interest are the default values of various flags, as these are computed at runtime based on the environment.

In the fourth usage form enabled by the --version flag, ssh-agent-switcher prints version information to stdout and exits.

🛠️ The following flags are recognized 🛠️

• --agents-dirs dir1..dirN — Colon-separated list of directories that may contain sshd-provided agent sockets. The default value recognizes sockets created by OpenSSH before and after the naming scheme change that happened with the OpenSSH 10.1 release.
• --daemon — Enable daemon mode. You should always use this flag. no cap.
• --help — Show interactive help on stdout and exit.
• --log-file path — Specifies the location of the log file to create or to append to when running in daemon mode.
• --pid-file path — Specifies the location of the PID file to create when running in daemon mode. This is used as a lock to determine if the daemon should start again or not.
• --socket-path path — Location where to create the listening agent socket. Defaults to /tmp/ssh-agent.${USER} and you should rarely change this.
• --version — Show version information on stdout and exit.

🌸 EXAMPLES 🌸

The common mechanism to start ssh-agent-switcher is by hooking its startup in your user's login shell scripts (typically ~/.login, ~/.bash_login or ~/.zlogin).

Add the following snippet to these scripts:

ssh-agent-switcher --daemon 2>/dev/null || true
export SSH_AUTH_SOCK="/tmp/ssh-agent.${USER}"

As shown above, you should silence the stderr of the program to avoid getting uninteresting diagnostic messages to the console. bestie, protect your terminal peace 🫶

🌈 ENVIRONMENT 🌈

• HOME — User's home directory. Used to locate the sshd agent sockets in OpenSSH versions 10.1 or newer, and to determine defaults for XDG-related variables.
• RUST_LOG — Logging configuration. In the simplest form, this takes a log level name to determine the noisiness of the program. Possible values are: error, warn, info, debug and trace in order of verbosity.
• XDG_STATE_HOME — Path to where to store program-specific state files (the daemon log in the common case, but also the daemon PID if XDG_RUNTIME_DIR is not defined).
• XDG_RUNTIME_DIR — Path to where to store program-specific runtime files (the PID file).

🎀 FILES 🎀

• /tmp/ssh-agent.${USER} — Default agent socket created by ssh-agent-switcher. Set SSH_AGENT_SOCK to this path.
• /tmp/ssh-${RANDOM}/agent.${USER} — Location of sshd-provided agent sockets for OpenSSH versions before 10.1.
• ${HOME}/.ssh/agent — Location of sshd-provided agent sockets for OpenSSH versions 10.1 or newer.
• ${XDG_RUNTIME_DIR}/ssh-agent-switcher.pid — Default PID file when running in daemon mode. Falls back to ${XDG_STATE_HOME}/ssh-agent-switcher.pid if XDG_RUNTIME_DIR is not set.
• ${XDG_STATE_HOME}/ssh-agent-switcher.log — Default log file when running in daemon mode.

🔥 SEE ALSO 🔥

ssh-agent(1)

👑 AUTHORS 👑

The ssh-agent-switcher package was developed by Julio Merino ⟨julio@meroh.net⟩.

---

🫶 that's the whole manual, bestie! Debian edition, dated December 20, 2025, and yes — this page is SSH-AGENT-SWITCHER(1). periodt. 💅