Your first connection

Getting from a fresh install to a shell takes one screen of details and one question about the server's identity. This page walks through both.

Start from the machines list

Termphin opens on "Your machines". On a fresh install it says "No machines yet" and "Add a server to start your first SSH session."

Tap "Add machine".

Fill in the connection details

A screen titled "New Machine" opens. It closes with the X at the top left, and saves with "Save" at the top right - there is no save button at the bottom of the form.

The form is one scrolling list of sections. It opens on Avatar, where you pick an icon and a colour to mark the machine in the list. Under Connection are the four fields that matter:

• Name - what the machine is called in the list, for example "Production".
• Host - the address to connect to, for example "192.168.1.1".
• Port - 22 unless you change it.
• Username - the account you log in as, for example "root".

Name, Host and Username are required. Everything else on this screen can be left alone on a first connection.

Skip the optional sections

Below the connection fields are three sections you can ignore for now:

• Fallback addresses - other addresses to try, in order, if the host above does not answer. Useful when the same machine is reachable on a LAN address and a Tailscale one.
• Jump host - connect through another saved machine first, the way OpenSSH's ProxyJump does. Set to "Connect directly" unless you need it.
• Tags - labels for filtering a long list.

Choose authentication

"Authentication" offers three choices:

• Password - one field for the password of the username you entered, with an eye icon to show what you typed.
• SSH Key - pick a key you have already saved, or paste one in. If the key is protected, enter its passphrase here too.
• No authentication - for the rare server that asks for nothing.

Save and connect

Tap "Save". The machine appears in the list. Tap it to connect.

Accept the host key

The first time Termphin reaches an address it stops before logging in and shows "Unknown host":

Termphin has not connected to this address before. Check that the fingerprint matches the server, then accept it to remember this host.

It shows the address, the key type and the fingerprint. This is the step that makes the rest of the connection trustworthy, so it is worth doing properly: run ssh-keygen -lf against the server's host key file and compare - it prints the same fingerprint. Then tap "Accept and remember", which pins that key.

From then on the check is silent, and every later connection is compared against what you accepted.

If you are told the key changed

If the address ever answers with a different key, the prompt reads "Host key changed" instead. A rebuilt server or a rotated key looks exactly like this - and so does someone sitting between you and the server. Accept it only when you know the server's key changed, and "Do not connect" if you are unsure.

If the server asks a question

Some servers want more than a password - a code from an authenticator app, or a new password if yours has expired. When that happens a prompt titled "The server is asking" shows the server's own questions, one field each. Fill them in and tap "Send".

This does not appear for most servers, and nothing needs setting up for it.

What the connection states mean

While connecting, the screen shows "Connecting..." and a running log of what it is doing. That log stays available afterwards as "Connection log", which is the first place to look when a connection does not come up.

Once you are in, the state reads "Connected". The others you may see:

• Reconnecting - the connection dropped and Termphin is restoring it.
• Retrying in a few seconds - waiting before the next attempt, counting down.
• Waiting for a network - the phone has no network at all, so there is nothing to retry against yet. It resumes on its own once there is.
• Disconnected - the session is over.