Authentication
Log in with the SSH agent, a private key, a password or keyboard-interactive MFA, and control the order methods are tried in.
Gatesys SSH logs you in with the same methods OpenSSH uses. You choose which ones a host may use, and the app tries them in order until one succeeds.
Choose methods for a host
Open the host editor and go to Authentication. Turn on one or more methods:
| Method | Use it when |
|---|---|
| SSH agent | Your keys are loaded in a running agent (ssh-agent, the macOS keychain agent, 1Password, gpg-agent, Pageant or the Windows OpenSSH agent) |
| Private key file | The key is a file on this computer, such as ~/.ssh/id_ed25519 |
| Password | The server accepts passwords. It comes from the local vault if saved, or you are asked on connect |
| Keyboard-interactive | The server asks its own questions, such as a one-time MFA code |
Enabled methods are tried top to bottom, in the order shown in the editor; the number beside each one is its place in that order. At least one method must be on, and Private key file needs a key chosen.
Fewer methods, faster failures
Each method a server refuses counts towards its MaxAuthTries limit, and tools such as fail2ban count refusals too. Turn on only the methods the host actually uses.
Use the SSH agent
The agent is found the same way OpenSSH finds it:
- macOS and Linux: the socket named by
SSH_AUTH_SOCK. macOS sets it for you. 1Password and gpg-agent change it when they take over agent duty. - Windows:
SSH_AUTH_SOCKif set, otherwise the Windows OpenSSH agent, otherwise Pageant.
Check Settings › Safety › Vault and keys › SSH agent:
| Status | Meaning |
|---|---|
| Connected | The agent is reachable and holds keys |
| Empty | The agent is reachable but holds no keys. Load one with ssh-add |
| Not found | SSH_AUTH_SOCK is not set, so agent authentication is skipped |
ssh-add ~/.ssh/id_ed25519The Keychain lists every key the agent holds next to the keys in ~/.ssh. With Pageant, keys cannot be listed, and the app says so rather than calling the agent empty.
Use a private key file
- Turn on Private key file.
- Type the path or click Browse… to choose the key.
- Save the host.
Encrypted keys work. You are asked for the passphrase the first time the key is used; tick Remember on this device to keep it in the vault.
Use a password or MFA
With Password on, the app uses a saved password or asks for one. With Keyboard-interactive on, it shows each prompt the server sends, so you can answer a one-time code or a second factor in the same dialog.
The login timer stops while any prompt is open. Checking a code on your phone never looks like a declined login.
Saved secrets
Passwords and passphrases you choose to remember are sealed in the local vault on this computer, never written to the config file. See Credential storage.
The Authentication tab shows what is saved for the host, for example Saved on this device: password. Click Forget to remove it. Deleting a host forgets its secrets too.
If the vault cannot be opened, the editor says so and nothing is saved; you are asked each time instead.
When a login fails
Hop Doctor records what happened to each method: offered and refused, or skipped and why (no agent running, key file missing, passphrase not given). Its report names the problem in plain words, such as permission denied for deploy (server offers: publickey); key refused, and can fix the user, key, auth order or port for you. See Hop Doctor.
Something unclear or wrong? Tell us.