SSH connections

An SSH connection opens a shell on a server in a terminal tab. kaiport has its own SSH client, so it works without OpenSSH and doesn't read ~/.ssh/config or ~/.ssh/known_hosts when it connects – everything it needs is in the connection. This page explains every field of an SSH connection, how the login works and what to do when a connection fails.

Create an SSH connection

1. In the start window, click New connection. The SSH tile is already selected.
2. Enter the Host and the Username. Change the Port if the server doesn't use 22.
3. Choose the Authentication: Password, SSH key or SSH agent.
4. Click Create.
5. Click the new card to connect. The first time, kaiport asks you to confirm the server's host key.

Server and login

The fields for color, tags, group and favorite are the same for every connection type. See Common fields.

Authentication

Password

Enter the password in the Password field. kaiport stores it encrypted, see Where credentials are stored.

You can also leave the field empty. kaiport then asks for the password each time you connect (Password required). Tick Store encrypted for this connection in that dialog if kaiport should remember it.

If the server rejects the password, kaiport asks again (Login failed) – up to three times.

SSH key

1. Choose SSH key.
2. Next to Private key, click Choose and select your key file. The file dialog opens in ~/.ssh.
3. If the key is protected by a passphrase, enter it under Passphrase.
4. Click Create or Save.

Choose reads the key right away and imports it into kaiport's encrypted vault; the path stays in the field only for reference. The connection keeps working if you move or delete the file. Once a key is stored, the field says “The key is stored in the vault. “Choose” replaces it.”

If you type a path instead of using Choose, kaiport reads the file from that path every time you connect. Connections imported from ~/.ssh/config, WinSCP or PuTTY work this way until you choose the key again. The Mac App Store version can't read keys from a path: there, pick the key with Choose, so that kaiport imports it.

Encrypted keys work in every format. kaiport converts PuTTY keys in memory, so you don't need PuTTYgen. Two formats are not read:

• PuTTY format 1: save the key again with a current PuTTYgen.
• PKCS#8 (-----BEGIN PRIVATE KEY-----): save the key in the OpenSSH format, for example with ssh-keygen -p -f <file>.

The Passphrase is only needed for encrypted keys and is stored encrypted as well. If you leave it empty, kaiport asks when connecting (Passphrase required) and offers to store it. After three wrong attempts, the connection stops with “The passphrase was not accepted.”

SSH agent

With SSH agent, the login is signed by your running SSH agent; the keys never leave it.

Load your keys into the agent before you connect, for example with ssh-add. If kaiport finds no agent on macOS or Linux, the connection stops with “No SSH agent found (SSH_AUTH_SOCK is not set).”

Two-factor and other login prompts

Some servers ask questions during the login instead of, or in addition to, the password – for example a one-time code from an authenticator app (keyboard-interactive login). kaiport shows these questions in a Login dialog with user@host and one field per question. Answers the server marks as secret are hidden while you type.

• Click Connect to send your answers or Cancel to stop (“Connection cancelled”).
• If a password is stored and the server's first question asks for it, kaiport answers on its own, so you only see the next question, such as the verification code.
• Store encrypted for this connection only appears when the server asks for a password alone. One-time codes are never stored.

Host key check

The host key proves that you are talking to the right server. kaiport checks it on every connect and trusts a key on first use:

• First connection: kaiport shows the key type and the SHA256 fingerprint and asks: “The authenticity of server.example.com cannot be established.” Click Trust to store the key and connect, or Cancel to stop.
• Known key: kaiport connects without asking.
• Changed key: kaiport warns “The host key of server.example.com has changed!” and shows the new and the previously stored fingerprint. Cancel is preselected; Accept new key replaces the stored key and connects.

If you cancel, the connection fails with “Host key was not accepted.”

kaiport keeps its own list of host keys, one per host and port, separate from ~/.ssh/known_hosts. Settings → Known hosts lists them with key type and fingerprint. Forget removes a key, and kaiport asks again on the next connect. See Security.

Advanced settings

The Advanced tab holds the jump host, agent forwarding, the command after connecting, port forwards and your Notes.

The Advanced tab

Jump host

A jump host, also called bastion, is a server you connect through to reach servers that aren't directly reachable. kaiport first logs in to the jump host, opens a tunnel from there to the target and runs the SSH session through it – like ProxyJump in OpenSSH.

1. Save the jump host as an SSH connection of its own, with its credentials stored.
2. Open the target connection with Edit and switch to Advanced.
3. Under Jump host (ProxyJump), choose the jump host. Connect directly turns it off again.
4. Click Save.

The card of the target now shows Jump. Keep in mind:

• kaiport logs in to the jump host with the credentials stored for it and doesn't ask for anything on the way. Store the jump host's password, or use a key or the agent.
• The target's host name is resolved by the jump host, so internal names and addresses such as 10.0.0.12 work.
• There is one hop: a jump host's own jump host setting is not used.
• If you delete the jump host connection, the target fails with “The configured jump host no longer exists.”

When you import ~/.ssh/config, kaiport takes over ProxyJump, see Import and export.

Agent forwarding

Forward SSH agent makes your local SSH agent available on the server. You can then use your local keys from there – for example for git pull from a private repository or ssh to the next server – without copying keys to the server. Forwarding needs a running agent, see SSH agent, and isn't available in the Mac App Store version.

Command after connecting

Command after connecting runs automatically as soon as the prompt appears – on every connect, including reconnects. Examples: cd /var/www && ls or tmux attach || tmux new.

Port forwards

Local (-L), remote (-R) and SOCKS5 (-D) forwarding are described on Port forwarding. Port forwarding is part of kaiport Pro.

AI settings

The AI tab controls AI Pilot on this server:

• AI instructions for this connection are added to AI Pilot's system prompt, for example “This is a production system – never restart services without asking.”
• Denied commands (AI) and Allowed commands (AI) take one pattern (regular expression) per line, for example ^systemctl restart.

See Approvals and safety.

Connection states

Reconnect

To reconnect by hand, click Reconnect, choose File → Reconnect (⌘R/CtrlR) or pick Reconnect in the command palette.

With Settings → Terminal → Reconnect automatically (on by default), kaiport reconnects a session that was connected and then ended: up to three attempts, after 2, 5 and 10 seconds. The overlay counts down, for example “Retrying in 5s…”. This also happens when the shell on the server ends, for example after exit – close the tab with ⌘W/CtrlW when you are done. A connection that fails right away is not retried automatically.

A reconnect runs the whole login again: host key check, prompts for anything not stored, the command after connecting and the port forwards.

Keepalive and timeouts

kaiport sends a keepalive to the server every 15 seconds. If three in a row stay unanswered, kaiport treats the connection as lost. Setting up a connection times out after 20 seconds with “Connection timed out.”

Older and hardened servers

kaiport prefers modern algorithms but also offers older ones as a last resort, like PuTTY does. The best algorithm both sides support still wins, and old appliances, switches or NAS systems connect without extra settings. The fallbacks include CBC ciphers such as aes128-cbc and 3des-cbc, hmac-md5, key exchanges with SHA-1 such as diffie-hellman-group14-sha1, and ssh-dss host keys.

Servers hardened to offer only chacha20-poly1305@openssh.com work as well.

If the handshake still fails, kaiport adds what the server offers to the error, for example “Handshake failed: no matching C->S cipher. The server offers: …”. Compare that list with the server's configuration.

Common errors

For more help, see Troubleshooting.