basforge

Search titles, text and the “If it doesn’t work” cases.

    RU
    ManualLinuxSSH

    ssh-agent: type the passphrase once per session, and why not ForwardAgent

    The agent keeps the decrypted key in memory and signs logins instead of the file: you type the passphrase once, not on every ssh and git push. Don’t forward the agent to servers — use ProxyJump for jumps and a deploy key for git on the server.

    How the agent works

    ssh web1 ──── "sign the server's challenge" ────→ ssh-agent ── key decrypted, in memory
         ↑                                                     │
         └──────────────────── signature ←─────────────────────┘
    the server checks the signature with the public key from authorized_keys

    The agent never hands out the private key — not to ssh, not to anyone. It only signs what it’s given. So ssh, scp, git and an editor with remote development all use one key, and you type the passphrase once: on ssh-add or on the first login with AddKeysToAgent yes (~/.ssh/config).

    Where to keep the key

    Where How the passphrase lives When to use
    the OS agent: the Windows service, Keychain on macOS, the session agent on Linux Windows keeps an added key even across reboots — you type the passphrase once, ever. macOS and Linux — once per login one computer, one or two keys
    a password manager’s agent: KeePassXC, 1Password, Bitwarden the key lives in the vault, and the agent opens with it keys on several computers, and the vault syncs anyway
    a hardware key, ed25519-sk the private part never leaves the device; you log in with a touch a laptop that might get stolen; access to important servers

    The rest of this page uses the OS agent: it’s everywhere and costs nothing.

    Setup

    1. Start the agent

      Windows. The ssh-agent service is built in but disabled. In PowerShell as Administrator:

      Get-Service ssh-agent | Set-Service -StartupType Automatic
      Start-Service ssh-agent
      Get-Service ssh-agent
      # Status   Name        DisplayName
      # Running  ssh-agent   OpenSSH Authentication Agent

      macOS. The system starts the agent itself.

      Linux with a desktop. The session starts the agent: GNOME Keyring or the systemd ssh-agent unit. Check that echo $SSH_AUTH_SOCK isn’t empty.

      A server or a console without a desktop. In the current shell:

      eval "$(ssh-agent -s)"
      # Agent pid 41873
    2. Add the key

      ssh-add ~/.ssh/id_ed25519
      # Enter passphrase for /home/me/.ssh/id_ed25519:
      # Identity added: /home/me/.ssh/id_ed25519 (laptop-2026)

      The parentheses hold the key’s comment from ssh-keygen -C (SSH keys).

      On macOS, also store the key in Keychain so the passphrase isn’t asked after a reboot:

      ssh-add --apple-use-keychain ~/.ssh/id_ed25519

      and add UseKeychain yes under Host * in ~/.ssh/config.

    3. Point Git on Windows at the same ssh

      Git for Windows ships its own ssh.exe, which doesn’t see the Windows service: git push keeps asking for the passphrase. Point it at the system one:

      git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe

      Use forward slashes: both git and the shells inside it understand them.

    4. Restrict it on a shared computer

      ssh-add -t 8h ~/.ssh/id_ed25519     # the key leaves the agent after 8 hours
      ssh-add -c ~/.ssh/id_ed25519        # every use needs confirmation in a window
      ssh-add -D                          # remove all keys from the agent

      -c needs a confirmation program (ssh-askpass); without one, signing is silently refused.

    Why not ForwardAgent

    ssh -A or ForwardAgent yes forwards the agent to the server: a socket appears there that can sign logins with your key — say, git pull from GitHub right on the server.

    Your session isn’t the only thing that can sign through that socket. Root on the server can open your session’s socket (its path is in $SSH_AUTH_SOCK) and, while you’re connected, log in with your key to any server or repository the key opens. The key itself doesn’t leak — the ability to use it does. And a compromised server is exactly that: a stranger with root.

    Task Instead of agent forwarding
    reach an internal server through a public one ProxyJump (~/.ssh/config): the connection goes straight through, and the agent stays on your computer
    git pull on the server a deploy key on the server, read-only and for one repository (Server configs in git)
    copy files between two servers scp -3 web1:/a web2:/b routes through your computer; or a backup key with restrict (SSH keys)

    If you do need forwarding, use it for one command and with confirmation: ssh-add -c and ssh -A web1. And close it on your own servers: AllowAgentForwarding no (sshd_config).

    If it doesn’t work

    Could not open a connection to your authentication agent.

    Cause
    The agent isn’t running in this session, or SSH_AUTH_SOCK points to a socket that’s gone.
    Fix
    Linux: eval "$(ssh-agent -s)" and ssh-add. Windows: the ssh-agent service — step 1.

    On Windows: Error connecting to agent: No such file or directory

    Cause
    The ssh-agent service is stopped; Windows ships it disabled (Disabled).
    Fix
    Set it to start automatically and start it — step 1, in PowerShell as Administrator.

    The key is in the agent, but git push still asks for the passphrase

    Cause
    Git for Windows runs its own ssh.exe, which doesn’t see the Windows service.
    Fix
    git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe.

    sign_and_send_pubkey: signing failed for ED25519 … agent refused operation

    Cause
    The key in the agent is locked or has expired (ssh-add -t), or it was added with confirmation (-c) and there’s no window to confirm in.
    Fix
    ssh-add -l shows what’s in the agent; add the key again with ssh-add ~/.ssh/id_ed25519.

    Many keys in the agent, and the server drops the connection: Too many authentication failures

    Cause
    The agent offers every key in turn.
    Fix
    IdentitiesOnly yes and IdentityFile for the host (~/.ssh/config).

    How to check

    What’s in the agent:

    ssh-add -l
    # 256 SHA256:u7WTRQvHCGalFd0cVdGQ7Wm7cULmdHtHUpyj6Q0uXcA laptop-2026 (ED25519)

    If it’s empty: The agent has no identities.

    The login goes through the agent, not the file: in the debug output the key is marked agent.

    ssh -v web1 true 2>&1 | grep 'Offering'
    # debug1: Offering public key: /home/me/.ssh/id_ed25519 ED25519 SHA256:u7WT… explicit agent

    The agent isn’t forwarded to the server:

    ssh web1 'echo ${SSH_AUTH_SOCK:-no agent}'
    # no agent