Help

Two systems

SSHush does two separate things, and it is worth understanding the difference before anything else.

Live metrics come from your device's own SSH session. Open the app, it connects to your servers and shows you what they are doing right now. This is free, unlimited, and installs nothing on your servers.

Alerting is a different system. A small agent runs on your server and reports to our backend on its own schedule, independently of your phone. When a threshold is breached, the alert originates on your server and arrives as a push notification. This requires a subscription.

The two do not depend on each other. If a server card shows as offline, that describes your device's SSH connection to it - it says nothing about your alerting, which is still running.

Getting started

Adding a server

• On the Servers tab, tap the add button.
• Enter the host (an IP address or hostname), the port (22 unless you have changed it), and your username.
• Choose how to authenticate: a password, or an Ed25519 private key.
• Tap to connect. On the first connection you will be asked to verify the server's host key (see below).
• Once verified, the server appears in your list and metrics begin loading.

Authentication

SSHush supports two methods:

• Password. Your account password on the server.
• Ed25519 key. Paste your private key. If it is passphrase-protected, enter the passphrase as well.

Only Ed25519 keys are supported. RSA, ECDSA, and DSA keys are not. If your key is one of those types, you can generate an Ed25519 key with ssh-keygen -t ed25519 and add its public half to your server's ~/.ssh/authorized_keys.

Your credentials are stored in your iCloud Keychain, encrypted by Apple. They are never sent anywhere except to your own server when connecting.

Verifying the host key

The first time you connect, SSHush shows the server's host key fingerprint in SHA256: format. This is how you confirm you are talking to the right machine. Accept it to continue, and SSHush remembers it.

If the fingerprint ever changes on a later connection, SSHush warns you and will not connect silently. That can mean the server was rebuilt or its key was rotated, but it can also mean something is intercepting the connection. Only accept a changed key if you know why it changed.

What SSHush monitors

SSHush reads standard files and command output from your server, such as /proc/stat, /proc/meminfo, and df. It shows:

• CPU usage overall and per core, plus temperature where the host has a sensor
• Memory actually in use, excluding page cache, so it matches what htop shows
• Disk usage for each mounted filesystem
• Network throughput for each interface
• Disk I/O
• Load and uptime
• Processes currently running
• Latency, the round-trip time measured from your device to the server

Why is there no temperature reading?

Temperature only appears when the host exposes a thermal sensor. Many virtual private servers do not, so on those hosts the temperature is simply left out.

The terminal

The Terminal tab gives you a full interactive SSH shell to any of your servers. It uses the same credentials and the same verified host key as monitoring, so there is nothing extra to set up. It supports full xterm-256color emulation, so editors and tools like nano, vim, and htop work as expected.

Swipe down to dismiss the keyboard. Rotate the device or resize the window to reflow the terminal.

Alerting

Enabling it

Alerting requires a subscription. Enable it on a server and SSHush installs the agent over the SSH connection you already have - there is nothing to download, no script to run, and no account to create.

What gets installed

The agent binary, an uninstall script, three systemd units, an unprivileged system user called sshush, and two directories: /etc/sshush for its credentials and /var/lib/sshush for its rules.

Nothing else on your system is touched. There is no package manager integration, no cron entry, and no modification of any existing file. Nothing is downloaded at install time.

The agent is open source under Apache 2.0 and you are encouraged to read it before you install it: github.com/inatthegeekend/sshush-agent

How it runs

As the unprivileged sshush user, never as root, under systemd restrictions that make your entire filesystem read-only to it. /var/lib/sshush is the single exception and the only place it can write.

It does not listen on any port, does not execute remote commands, and does not fetch anything. Its whole network footprint is the two endpoints written in its config file, both of which must be HTTPS.

Its rules live in /var/lib/sshush/rules.json, owned by the user who installed it, so you can edit them without root. That also means anyone who can act as that user can change what the agent alerts on. Its credentials in /etc/sshush stay root-only either way.

Configuring rules

Rules are configured in the app, per server: CPU, memory, swap, disk per mount point, load average, temperature, and interface down. Each rule has a threshold and a duration. A rule breaches only after the value has stayed past its threshold for the full duration, so a momentary spike does not wake you. It clears on a single sample back the other side - slow to alarm, fast to reassure.

Silence detection

The agent beats to our backend on a fixed interval. If those beats stop, we tell you.

This is the failure a monitoring system exists to catch. A server that has gone away cannot report that it has gone away, so the absence of a report is itself the signal.

What is sent

Metrics are sampled and rules evaluated on your server. Only a crossed threshold is ever sent, never the underlying numbers. Your metrics do not leave the machine.

Turning it off

Disable alerting on a server and the app asks the agent to remove itself. You can also run sudo /usr/local/bin/sshush-uninstall on the server directly. Both routes run the same script and remove everything.

The mechanism is worth understanding if you care how this works. The agent is unprivileged and uninstalling needs root, so rather than granting the agent any privilege, a systemd path unit watches for a marker file. When it appears, systemd runs the uninstall script as root. The file's contents are never read and every path the script touches is hardcoded, so the marker carries exactly one bit of meaning: the agent asked. A completely compromised agent gains the ability to uninstall itself and nothing else.

Subscription tiers

Tiers differ only in how many servers may have alerting enabled at once. Metrics and the terminal are free and unlimited regardless of which tier you hold, or whether you hold one at all.

Monitoring while the app is open

Live metrics are read by your device, so they update only while the app is open. When you leave the app, polling stops.

Alerting is not affected by this. The agent runs on your server and reports independently of your device - backgrounding the app, force-quitting it, or deleting it from your home screen does not stop alerts arriving.

Poll interval

You can set how often SSHush refreshes metrics from the Settings tab. This affects the live metrics only and has no effect on alerting.

Networking

Local network permission

The first time SSHush needs to reach a server on your local network, iOS asks for permission to access devices on that network. This is required to connect to servers on your LAN by their local address. If you only ever connect to servers on the public internet or over a VPN, you may not see this prompt.

Changing networks

If your device switches network while you are watching a server, for example moving from Wi-Fi to cellular, SSHush detects the change and reconnects automatically. Stale readings stay on screen under a "Reconnecting" indicator until the fresh connection is established. If a server genuinely cannot be reached, the card shows it as offline and you can tap to retry.

What the agent needs

The agent makes outbound HTTPS connections only, on port 443, to api.sshush.app. It needs to be able to reach the internet, but nothing needs to be able to reach it - no inbound rule, no port forward, no reverse proxy.

Your servers and your data

Does SSHush change anything on my server?

For live metrics, no. SSHush logs in with your credentials and runs standard read-only commands. Nothing is installed and nothing is written.

If you enable alerting, the agent is installed, with your explicit consent, on the servers you choose. It is removed when you disable alerting on that server.

Removing a server

Removing a server forgets it on your device and removes it from your iCloud-synced list. If alerting was enabled on it, the agent is removed from the server first - there is nothing left to clean up.

Syncing across devices

Your server list syncs across your Apple devices through your private iCloud account, and your credentials sync through iCloud Keychain. If iCloud is unavailable, SSHush still works and simply keeps your servers on the one device until iCloud is reachable again.

Your credentials

Your SSH credentials never leave your device except to connect to your own servers. They are not transmitted to our backend and our backend is not built to hold them.

Troubleshooting

It will not connect.
Check that the host and port are correct and that the server is reachable from your device (try connecting over the same network from a computer). If you use a firewall, make sure your device's network can reach the SSH port. If you are away from home, you may need a VPN into your network.

My key is rejected.
Confirm the key is an Ed25519 key and that its public half is in the server's ~/.ssh/authorized_keys. If the key has a passphrase, make sure you entered it.

The host key warning appeared.
This means the fingerprint changed since you last connected. If you rebuilt the server or rotated its key, that is expected. If you did not, do not accept it until you understand why it changed.

A server shows as offline but I am still getting alerts.
That is expected. The card describes your device's SSH connection to the server. Alerting runs on the server itself and is unaffected.

I am not receiving alerts.
Check that notifications are enabled for SSHush in iOS Settings, that your subscription is active, and that the server has alerting switched on with at least one rule configured. Remember that a rule fires only after its threshold has been breached for the duration you set.

Which servers are supported?
SSHush monitors full Linux hosts. Containerised environments such as Docker and LXC are not supported. Alerting additionally requires systemd - Debian, Ubuntu, RHEL/Alma/Rocky and Raspberry Pi OS are all fine.

Contact

Questions, ideas, and bug reports are welcome. Please use the 'Contact' link in the footer.