Your first connection

This page takes you from a new install to a working shell. The first-run setup brings your servers in; after that you add hosts one of three ways, connect, and confirm the server’s identity the first time.

First-run setup #

The first time Gatesys SSH starts, a full-window setup walks you through seven steps. It takes about a minute, and every step can be skipped and changed later in Settings.

Looking for models on the Farabi step asks local model servers on this computer for their lists and looks for the agent CLIs; nothing leaves the computer, and with Use Farabi off nothing is asked at all. Without Pro, what you choose for Farabi and hooks is kept and used as soon as Pro is on.

In the setup, Enter continues and Esc goes back a step. Skip setup at the top right ends it at any step.

Sample hosts #

If you skip the Servers step, or the whole setup, without adding a host to an empty list, the setup adds a few sample hosts so the app opens on something. They point at documentation-range addresses that go nowhere and are marked sample. Editing one makes it yours; Remove sample hosts at the bottom of the list clears them all.

What’s new, and running the setup again #

• Upgrading from an earlier version with hosts of your own, you get a short What’s new instead of the full setup. Take the tour opens the setup; Not now puts it away for good.
• To run the setup again, open Settings › Account and click Run setup again. Nothing is reset.

Add a host #

Fill in the host editor #

1. In Hosts, click New (or press ⌘N, CtrlN on Windows and Linux).
2. On General, enter a Display name (db-primary), the Hostname or IP (10.0.3.4), the Port and the Username (deploy). Group and Tags are optional.
3. On Authentication, turn on the methods this server accepts. They are tried top to bottom until one works. For Private key file, choose the key.
4. If the host sits behind a bastion, open Routing and add the bastion as a jump host. See Jump hosts.
5. Click Save, or press ⌘Enter (CtrlEnter).

Paste an ssh command or type a sentence #

The search box at the top of the host list reads these as a new host:

ssh -J edge-bastion -p 2223 [email protected]
ssh://[email protected]:2223
add 10.0.3.4 as deploy behind edge-bastion

1. Paste or type it into the search box.
2. Click Add as a host: “…” under the box, or press Enter when no saved host matches.
3. The host editor opens, filled in. Check it and click Save.

Nothing is saved until you click Save. A few things are worth knowing:

• A jump host such as edge-bastion must already be saved under that exact name. A near miss shows Did you mean …? instead of guessing.
• Options the app does not keep are listed. StrictHostKeyChecking=no is ignored because host keys are always checked; a remote command, agent forwarding and X11 forwarding are not kept.
• A password in the text is replaced with [redacted] before anything reads it. You are asked for it on first connect.

More on sentences in Say it, Gatesys sets it up.

Import ~/.ssh/config #

1. Choose File › Import from ~/.ssh/config…. On an empty host list you can also click Import config.
2. The dialog reads ~/.ssh/config. Click Browse… to read another file.
3. Untick any hosts you do not want, then click Import.

ProxyJump entries become real jump chains. If you import a host, its jump hosts come along even when unticked, so the chain never points at a missing host. A hop written as user@host:port with no Host block of its own becomes a host too. Imported hosts land in the Imported group.

Host edge-bastion
  HostName bastion.example.com
  User deploy

Host db-primary
  HostName 10.0.3.4
  User deploy
  IdentityFile ~/.ssh/id_ed25519
  ProxyJump edge-bastion

Importing this gives you two hosts, with db-primary routed through edge-bastion.

The import never runs Match exec commands. Import again whenever your config changes: it updates what the config says and keeps what you set in Gatesys SSH, such as tags, notes, keepalive, tunnels, what runs on connect, and Remember facts if you turned it off.

Connect #

Double-click the host in the list, or select it and click Connect. You can also press ⌘K and type the host’s name. A session tab opens in the title bar and the terminal appears once the login finishes.

Trust the host key #

The first time you reach a server, Gatesys SSH shows Unknown host key with the server’s key type and SHA256 fingerprint.

1. Compare the fingerprint with one from the server’s operator, or with the output of this command run on the host:

   ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

2. If they match, click Trust and connect. Otherwise click Cancel.

Each hop in a jump chain asks for its own key the first time. After that, a matching key connects silently. Gatesys SSH keeps its own list of trusted keys rather than reading ~/.ssh/known_hosts, so you confirm each server once even if OpenSSH already knows it. See Host keys.

Answer login prompts #

Depending on the methods you enabled, you may be asked for:

• Password required: the account password.
• Key passphrase: the passphrase of an encrypted key.
• Additional verification: the server’s own prompts, such as a one-time MFA code.

Tick Remember on this device to keep a password or passphrase in the local vault. The login timer pauses while a prompt is open, so taking your time never reads as a failure.

If it does not connect #

The terminal shows a Hop Doctor report instead of a bare error: which hop broke, at which step, the evidence, and fixes you can apply with one click. See Hop Doctor.

Next #

• Terminal: tabs, splits, snippets and recording.
• SFTP: browse and edit files on the same connection.
• Port forwarding: reach a database or a web UI on the server.