SSH key setup

How to create a key, put it on your relay, and load it into the app. Takes about five minutes.

On iPhone there is no password field — this is deliberate. The iOS app connects with an SSH key only. Typing a root password into a phone app is exactly the habit this app should not teach, so it was never built. The Mac, Windows and Linux versions do accept a password, but a key is better there too.

What you need

Item	Detail
Key type	`ed25519`, OpenSSH format, no passphrase
Where the private key lives	iPhone Keychain, on that device only. It is never uploaded anywhere.
Where the public key goes	`~/.ssh/authorized_keys` on each relay
A terminal	On your Mac or PC — one time, for two commands

Use a key dedicated to the phone. Do not copy the key you already use to administer your servers. Make a separate one: if the phone is lost or sold, you remove that single key and everything else stays as it was.

Step by step

1Create the key

On your Mac or Linux box (on Windows use PowerShell — ssh-keygen ships with it):

ssh-keygen -t ed25519 -f ~/.ssh/relaypulse_phone -C "relaypulse-phone" -N ""

This writes two files: relaypulse_phone (private — goes on the phone) and relaypulse_phone.pub (public — goes on the relays). -N "" means no passphrase, which the app requires; that is why this key must be a limited, phone-only key.

2Put the public key on your relay

ssh-copy-id -i ~/.ssh/relaypulse_phone.pub root@YOUR.RELAY.IP

Repeat for each relay you want to reach from the phone. If ssh-copy-id is not installed, the manual equivalent is:

cat ~/.ssh/relaypulse_phone.pub | ssh root@YOUR.RELAY.IP \
  'mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys'

Many relays run SSH on a non-standard port. Add -p 2222 (or whichever port you use) to either command.

3Get the private key onto the phone

Two ways — pick whichever is easier:

AirDrop the file. Send ~/.ssh/relaypulse_phone to your iPhone, then in the app open Settings → SSH → Import from file and choose it.

Or copy and paste. On the Mac:

pbcopy < ~/.ssh/relaypulse_phone

Then on the phone: Settings → SSH → Paste key, paste, and tap Save. The key must start with -----BEGIN OPENSSH PRIVATE KEY----- and include every line down to the matching END line.

4Test it

Settings → SSH → Try on <your relay> opens a real connection and prints the result. A loaded key also shows its fingerprint, which you can compare against:

ssh-keygen -lf ~/.ssh/relaypulse_phone.pub

If the two fingerprints match, the phone is holding the key you think it is.

If it does not work

What you see	What it usually means
`Authentication refused (is the key in the relay's authorized_keys?)`	Step 2 did not land, or it landed for a different user. The key must be in the `authorized_keys` of the same user you connect as — `/root/.ssh/` for `root`, `/home/<user>/.ssh/` for anyone else.
The app refuses the key when you paste it	It is not an unencrypted ed25519 OpenSSH key. An RSA key, a PuTTY `.ppk`, a key with a passphrase, or the `.pub` file by mistake will all be rejected. Regenerate with the exact command in step 1.
Connection times out	Wrong port, or the relay's firewall does not allow your phone's network. Check the SSH port on the server entry.
It worked, then stopped	Some hosts run `fail2ban`. Repeated failed attempts ban the source IP for a while — including the one your phone is on. Wait it out, or unban from the server.

Removing the key later

On the phone: Settings → SSH → Remove key deletes it from the Keychain.

On the relay, delete the matching line from ~/.ssh/authorized_keys — the one ending in relaypulse-phone:

ssh root@YOUR.RELAY.IP "sed -i '/relaypulse-phone/d' ~/.ssh/authorized_keys"

Do this on every relay if the phone is lost. Because this key is separate from the one you administer your fleet with, nothing else needs to change.

The agent is a separate thing. If you installed the metrics agent on a relay, its token is generated by the app and stored encrypted — you never type it by hand. SSH keys are only needed for the tools: Nyx, logs, the config editor and fix commands.