Connecting and signing in

Every connection has two parts: reaching the server, and proving who you are. This page covers both, and what Vaulterm does when a connection drops.

A host’s identity says who to sign in as and how. It can be set on the host or inherited from its group.

The identity says	Vaulterm
Key	Signs in with that key from your vault.
Password	Signs in with the password saved in your vault, or asks each time if none is saved.
ssh-agent	Signs in with the keys loaded in your running SSH agent.
(no identity)	Asks who to sign in as when you connect, then tries your agent and asks for a password if needed.

If the first way doesn’t work, Vaulterm carries on the way OpenSSH does:

The identity’s key, or your agent’s keys.
Keyboard-interactive: the server’s own questions, such as a password and then a one-time code. Up to three rounds.
A plain password prompt.

If none of these gets in, the pane says “That username or password didn’t work.” or, with a key, the server’s reason followed by “Check the username and the key or password in this host’s identity.”

Passwords

A password saved in an identity is stored in your encrypted vault and never shown again. Vaulterm offers it for you: first as the answer to the server’s “Password:” question, then as a plain password if the server asks that way.

Leave the identity’s password empty to be asked each time. The prompt is titled with the user and server (“Password for [email protected]”). What you type is used for that connection only and isn’t saved.

Two-factor codes

Servers that ask for a code (Google Authenticator, Duo, a YubiKey OTP and so on) do it through keyboard-interactive. Vaulterm shows the server’s questions in a dialog, one field per question, titled with the server’s own heading. If you have a saved password, Vaulterm answers the password question for you and only shows you the code question.

Your SSH agent

If you already keep keys in an agent, Vaulterm can use them without importing anything.

macOS: the agent in SSH_AUTH_SOCK, which macOS starts for you. Add keys to it with ssh-add.
Linux: the agent in SSH_AUTH_SOCK, such as ssh-agent, GNOME Keyring, KeePassXC or 1Password.
Windows: the Windows OpenSSH agent service (“OpenSSH Authentication Agent” in Services), or PuTTY’s Pageant if that’s running instead.

Vaulterm tries the agent’s keys first when a host has no identity, or when its identity says ssh-agent. If the agent fails in the middle of signing (it’s locked, it wants you to confirm, or a hardware key was pulled out), Vaulterm starts the connection again without the agent and goes on to the next way of signing in.

When you type a password in the sign-in dialog, Vaulterm skips the agent: its keys would use up the server’s allowed attempts before your password was tried.

Agent forwarding

Agent forwarding lets the server you’re on use the keys in your local agent, for example to git pull from a private repository on web-01 with your own GitHub key, without copying the key to the server.

Turn it on in the host’s or group’s More options: Agent forwarding set to On.

Only forward your agent to servers you trust. While you’re connected, anyone with root on that server can ask your agent to sign things as you. They can’t copy the key out, but they can use it until you disconnect.

Vaulterm only forwards the agent to the host you connected to, not to the jump hosts on the way.

Jump hosts

A jump host (also called a bastion) is a server you connect through to reach others that aren’t reachable directly.

Say db-primary (10.0.4.12) is only reachable from inside the network, and bastion is reachable from the internet:

Save bastion as a host, with its own identity.
Open db-primary, go to More options, and set Jump host to bastion.

Now connecting to db-primary connects to bastion first, then to 10.0.4.12 from there. The pane shows “Connecting to bastion…” and then the next hop.

The rules:

The jump host is a saved host, and signs in with its own identity, port and settings.
Jump hosts chain: if bastion has a jump host of its own, Vaulterm goes through that first. Chains can be as long as you need.
Set the jump host on a group to use it for every host inside. The jump host itself is never sent through itself, so it can live in the same group.
A chain that loops (a through b through a) is refused: “That jump host would loop back to this host.” when you save, or “This host’s jump hosts loop back on themselves.” when you connect.
ProxyJump lines in an imported ~/.ssh/config become jump hosts. See Bring your hosts over.
ProxyCommand isn’t supported.

Signing in without a saved identity

When a host has no identity, or you type an address without a username, Vaulterm asks “Sign in to web-01.prod.internal”:

Sign in with: one of your identities, or A username and password.
Username, and an optional Password (asked for later only if the server wants one).
Save as an identity, or Save as an identity and use it for this host for a saved host, keeps the login for next time.

After a quick-connect login like [email protected] works, Vaulterm offers once to keep it: “Save deploy as an identity?” with Save and Not now.

Keep-alive and reconnecting

Vaulterm sends a keep-alive every 15 seconds. If three in a row go unanswered, the connection is treated as lost.

When a connection that was working drops (the Wi-Fi changes, a laptop wakes up, a VPN reconnects), Vaulterm reconnects on its own:

The pane says, for example, “Connection lost (timed out). Reconnecting in 4 s, attempt 3 of 10.”
It waits 1 second, then 2, 4, 8, 16, and then 30 seconds between each try, up to 10 tries.
Anything you type while it’s reconnecting is thrown away, so a half-typed command doesn’t land in the new shell.
The Files tray and your tunnels share the connection, and come back with it. Transfers say they’re waiting for the connection.
You get a new shell. Programs that were running in the old one ended with it: use tmux or screen on the server to keep them running.

A first connection that fails isn’t retried. Neither is a sign-in failure or a host key problem, since retrying wouldn’t help. The pane says why, with a Reconnect button. You can also find the pane in the Command Center and press Tab for Reconnect.

Connection timeouts

Vaulterm gives a server 15 seconds to accept the connection, for each hop through a jump host. Time spent on prompts (a host key, a password, a code) doesn’t count.

What the messages mean

The pane says	What happened
The server’s host key has changed since you last connected…	See Host keys and trust. Vaulterm won’t connect.
You didn’t trust the server’s host key, so Vaulterm didn’t connect.	You pressed Cancel on the trust prompt.
That username or password didn’t work.	Wrong password, or the user doesn’t exist.
Connection cancelled.	You cancelled a prompt.
Unlock Vaulterm to connect.	The vault locked. Unlock it and reconnect.
This host no longer exists.	The host was deleted while the pane was open.
Vaulterm’s core stopped. Restart Vaulterm.	The part of Vaulterm that runs connections stopped. Quit and reopen Vaulterm.

More problems and fixes are on Troubleshooting.

Good to know

Vaulterm speaks SSH itself. It doesn’t use your system’s ssh command or read ~/.ssh/config when connecting; import the config once instead.
A password you type when connecting is held for that connection only, and is gone when the pane closes.
Stored passwords and keys stay inside Vaulterm’s core, the part that runs connections. The window you see never has them.