OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
apps-services low very-common DISPUTE

Make the SSH agent visible to GUI apps in a Wayland session

omarchyarchendeavouroscachyosmanjarohyprlandwaylandflatpaklaptopdesktop
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Checked on this Omarchy 4 workstation (omarchy 4.0.2-1, openssh 10.5p1-1, systemd 261.2-1, uwsm 0.26.7-1) and found one hard defect that makes the fix not work as written. Confirmed on this machine: ~/.config/environment.d/*.conf does NOT expand %t. Running the real generator against a throwaway config under /tmp, /usr/lib/systemd/user-environment-generators/30-systemd-environment-d-generator emitted A_PCT_T=%t/ssh-agent.socket verbatim while B_XDG=${XDG_RUNTIME_DIR}/ssh-agent.socket expanded to /run/user/1000/ssh-agent.socket. man 5 environment.d (systemd 261.2-1) documents only $VAR, ${VAR}, ${FOO:-D}, ${FOO:+A} and $$, and says 'No other elements of shell syntax are supported'. %t is a unit-file specifier, correct in ssh-agent.socket's ListenStream=%t/ssh-agent.socket and wrong in environment.d, so the record's printf 'SSH_AUTH_SOCK=%%t/ssh-agent.socket\n' writes a path nothing can connect to, and its parenthetical '(%t expands to $XDG_RUNTIME_DIR.)' is false for that file. The previous audit note praised the escaping and missed the specifier. Also confirmed on this machine: the record is not noise, because Omarchy 4 sets up no agent at all. grep -rniI 'ssh-agent|SSH_AUTH_SOCK|askpass' /usr/share/omarchy returns nothing, systemctl --user show-environment has no SSH_AUTH_SOCK, pgrep -c ssh-agent is 0, and gcr-ssh-agent.socket is disabled and inactive even though gnome-keyring 1:50.0-1 is in /usr/share/omarchy/install/omarchy-base.packages and pam_gnome_keyring.so auto_start is in /etc/pam.d/sddm. gnome-keyring-daemon runs here with --components=pkcs11,secrets and no ssh component, matching https://wiki.archlinux.org/title/GNOME/Keyring which records the move into gcr-4. Second correction, to the Omarchy branch: the record's ~/.config/uwsm/env claim is sourced to raw.githubusercontent.com/basecamp/omarchy/master/config/uwsm/env, which still returns 200 but is the Omarchy 3 tree (it exports OMARCHY_PATH=$HOME/.local/share/omarchy), and config/uwsm/env is a 404 in omacom/omarchy at ref=quattro. On Omarchy 4 the shipped file is /usr/share/uwsm/env.d/10-omarchy (owned by omarchy-settings 4.0.2-1) and its own comment names ~/.config/uwsm/env.d/* as the preferred user override. ~/.config/uwsm/ does not exist on this machine, so the audit note's 'Omarchy's ~/.config/uwsm/env is confirmed to exist' is wrong for Omarchy 4. The path still works, because the uwsm README sources uwsm/env and uwsm/env.d/* from ${XDG_CONFIG_HOME}, so I kept it as an alternative under the name Omarchy documents. That README also disproves the record's reason for needing two files: uwsm adds the difference those files make to 'activation environment of systemd user manager and D-Bus', so uwsm/env does reach user units in a uwsm session. The environment.d file alone is sufficient, which I proved end to end: ~/.config/environment.d/omarchy-firefox-wayland.conf contains MOZ_ENABLE_WAYLAND=1, that appears in systemctl --user show-environment, and a shell inside an app in this session sees MOZ_ENABLE_WAYLAND=1. Third correction, to the askpass step: /usr/lib/gcr4-ssh-askpass and /usr/lib/gcr-ssh-askpass are already installed here (gcr-4 4.4.0.1-1, gcr 3.41.2-2) but are internal helpers, not general askpass programs. strings /usr/lib/gcr4-ssh-askpass contains GCR_SSH_ASKPASS_SOCKET and gcr4-ssh-askpass: this program is not meant to be run directly, so the fix now warns against them instead of recommending them. The record's seahorse path survives: seahorse 1:47.0.1-6 ships usr/lib/seahorse/ssh-askpass per the Arch package file list, though seahorse is not installed here so I did not exercise the dialog. Everything else held. openssh 10.5p1-1 ships /usr/lib/systemd/user/ssh-agent.service and ssh-agent.socket, the socket listens on %t/ssh-agent.socket, the service has Also=ssh-agent.socket so enable --now ssh-agent.service covers both, and man ssh-agent on this machine documents the socket-activation mode used when -D is given with no -a. https://wiki.archlinux.org/title/SSH_keys supports the 9.4p1-3 floor, $XDG_RUNTIME_DIR/ssh-agent.socket, AddKeysToAgent yes (also confirmed in man ssh_config here) and the whole forwarding hazard including the literal The agent has no identities and the if [[ -z "${SSH_CONNECTION}" ]] guard, so the danger's substance is sourced. I sharpened the danger to scope the rc-file hazard correctly, since environment.d does not leak into an ssh session, and to name the verified ExecStartPost=-/usr/bin/systemctl --user set-environment SSH_AUTH_SOCK=%t/gcr/ssh in gcr-ssh-agent.socket as the concrete way two agents fight. https://wiki.archlinux.org/title/Systemd/User supports environment.d as the per-user mechanism. --socket=ssh-auth appears in the flatpak sandbox-permissions documentation I retrieved, but flatpak is not installed here so the override was not exercised. NOT exercised at all: enabling or starting any unit, adding a key to an agent, a log out and back in, a Flatpak client, and the seahorse dialog. I left severity low and frequency very-common alone, since the consequence is repeated passphrase prompts rather than data loss, and this is a common first-week complaint.

The cause above was rewritten on 2026-09-11 to match this note; the fix was corrected by the audit itself.
RISK

Do not set SSH_AUTH_SOCK in a shell rc file if you use agent forwarding. On a machine you SSH *into*, a locally set value overrides the forwarded socket and ssh-add -l on the remote reports The agent has no identities. Guard it with if [[ -z "$SSH_CONNECTION" ]] if you must use a shell rc file. ~/.config/environment.d/ does not have this problem, because an sshd session's environment comes from sshd and PAM and not from the systemd user manager. Running both ssh-agent.service and gcr-ssh-agent.socket leaves you guessing which agent holds which key, and they actively fight: gcr-ssh-agent.socket runs systemctl --user set-environment SSH_AUTH_SOCK=%t/gcr/ssh in its ExecStartPost, so it wins for everything started after it while your own value still applies to everything started before.

Symptom

git push works in the terminal but the same repo in VS Code, a JetBrains IDE, or a Flatpak Git client asks for the key passphrase every time or fails with Permission denied (publickey). ssh-add -l in a terminal lists the key, but a shell spawned from the GUI app says Could not open a connection to your authentication agent. Every new terminal also starts its own ssh-agent process (pgrep -c ssh-agent climbs).

Cause

Applications and units started by the systemd user manager do not read ~/.bashrc, so an agent started there, and the SSH_AUTH_SOCK it prints, is invisible to them. On Omarchy 4 the session itself is a user unit: Hyprland runs as wayland-wm@hyprland.desktop.service under uwsm, so every GUI app it launches inherits the user manager's environment rather than an interactive shell's. Omarchy's default/hypr/autostart.lua then runs systemctl --user import-environment and dbus-update-activation-environment --systemd --all exactly once, at hyprland.start, so a variable exported after that moment never reaches anything launched through a systemd user scope and apps already running keep the old value. The fix is to run one agent as a user unit and put SSH_AUTH_SOCK where the user manager sees it before the session starts, then log out and back in, rather than only where interactive shells see it.

Fix

Use the ssh-agent.service user unit shipped with openssh (in Arch's package since 9.4p1-3). It is socket activated, and ssh-agent.socket fixes the path at $XDG_RUNTIME_DIR/ssh-agent.socket:


systemctl --user enable --now ssh-agent.service   # Also= pulls in ssh-agent.socket
systemctl --user status ssh-agent.service

Set SSH_AUTH_SOCK in ~/.config/environment.d/, which the systemd user manager reads through its environment generator before it starts anything, including the compositor:


mkdir -p ~/.config/environment.d
cat > ~/.config/environment.d/50-ssh-agent.conf <<'EOF'
SSH_AUTH_SOCK=${XDG_RUNTIME_DIR}/ssh-agent.socket
EOF

Write ${XDG_RUNTIME_DIR}, never %t. %t is a unit-file specifier. environment.d expands only $VAR and ${VAR} and supports no other shell syntax, so SSH_AUTH_SOCK=%t/ssh-agent.socket is stored verbatim as the string %t/ssh-agent.socket and nothing can connect to it. %t is correct inside a unit file, which is why ssh-agent.socket itself uses ListenStream=%t/ssh-agent.socket.

On Omarchy 4 that one file is enough for the whole graphical session, because Hyprland runs as the user unit wayland-wm@hyprland.desktop.service and inherits the user manager's environment. Omarchy uses the same mechanism itself for /usr/lib/environment.d/10-omarchy-fcitx.conf.

If you would rather use uwsm's own hook, Omarchy 4's /usr/share/uwsm/env.d/10-omarchy names ~/.config/uwsm/env.d/* as the user override point, and uwsm adds the difference those files make to the activation environment of the systemd user manager and of D-Bus:


mkdir -p ~/.config/uwsm/env.d
echo 'export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/ssh-agent.socket"' > ~/.config/uwsm/env.d/50-ssh-agent

Pick one of the two files. Then log out and back in, because Omarchy's /usr/share/omarchy/default/hypr/autostart.lua runs systemctl --user import-environment and dbus-update-activation-environment --systemd --all once at hyprland.start, so a value exported after that point reaches nothing and apps already running keep the old one. Confirm:


systemctl --user show-environment | grep SSH_AUTH_SOCK
ssh-add -l

The value must be an absolute path such as /run/user/1000/ssh-agent.socket. A literal %t/... there is the mistake above.

Have keys added on first use instead of by hand:


# ~/.ssh/config
AddKeysToAgent yes

A passphrase prompt still needs a GUI askpass in a Wayland session, and seahorse provides one at /usr/lib/seahorse/ssh-askpass:


sudo pacman -S --needed seahorse
printf 'SSH_ASKPASS=/usr/lib/seahorse/ssh-askpass\nSSH_ASKPASS_REQUIRE=prefer\n' >> ~/.config/environment.d/50-ssh-agent.conf

Do not point SSH_ASKPASS at /usr/lib/gcr-ssh-askpass or /usr/lib/gcr4-ssh-askpass even though Omarchy 4 already installs gcr and gcr-4. Those are internal helpers of gcr-ssh-agent: they require GCR_SSH_ASKPASS_SOCKET and refuse to run with this program is not meant to be run directly. On plain Arch, x11-ssh-askpass is the other option, at /usr/lib/ssh/x11-ssh-askpass.

Remove any eval $(ssh-agent) from ~/.bashrc or ~/.zshrc. That is what was spawning an agent per terminal.

If you would rather have gnome-keyring hold the keys, use its agent instead of openssh's and do not set SSH_AUTH_SOCK yourself. The ssh component moved out of gnome-keyring-daemon into gcr-ssh-agent, and Omarchy 4 installs gnome-keyring but leaves gcr-ssh-agent.socket disabled, so nothing sets the variable until you enable it:


systemctl --user enable --now gcr-ssh-agent.socket

The socket's own ExecStartPost runs systemctl --user set-environment SSH_AUTH_SOCK=%t/gcr/ssh, which is why you must not set the variable yourself. Run only one of the two agents.

For a Flatpak app to reach the agent at all it needs the socket forwarded:


flatpak override --user --socket=ssh-auth com.visualstudio.code

Verify

systemctl --user show-environment | grep SSH_AUTH_SOCK prints an absolute path such as /run/user/1000/ssh-agent.socket and not a literal %t/..., systemctl --user is-active ssh-agent.service reports active, pgrep -c ssh-agent is 1, and ssh-add -l from a shell opened *inside* the GUI app lists your key.

Sources

ssh-agent-not-seen-by-gui-apps