// USER GUIDE

Operational guide — what to do, step by step, to get the most out of SSHBorg.

⚙⚙⚙

// ADDING A HOST

Tap the + button on the hosts screen to add a new server.

Required fields

  • Hostname / IP — the server address or IP. Both IPv4 and IPv6 are supported.
  • Port — defaults to 22. Change it if your server runs SSH on a different port.
  • Username — the Unix user you want to log in as (e.g. ubuntu, root, deploy).
  • Authentication — choose between password or SSH key (recommended).

Host fingerprint verification

On the first connection SSHBorg shows you the server's fingerprint and asks you to accept it. This is a security check: it ensures you are connecting to the right machine and not to an impostor. You should verify the fingerprint matches the one shown by your server admin or obtained via a trusted channel before accepting.

Once accepted, the fingerprint is stored locally. If it changes on a future connection, SSHBorg will warn you — this could indicate a server rebuild, a key rotation, or a man-in-the-middle attack.

// TIP
You can check the server fingerprint at any time with: 
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

// SSH KEYS

Key-based authentication is more secure than passwords and does not require you to remember or type anything after setup.

Generating a key

Go to Settings → SSH Keys → Generate new key. SSHBorg supports:

  • Ed25519 — recommended. Fast, compact, and secure.
  • ECDSA (P-256 / P-384) — good compatibility with older servers.
  • RSA (2048 / 4096 bit) — maximum compatibility, but slower.

Give the key a meaningful name (e.g. my-vps or work-server) so you can identify it later.

// SECURITY NOTE
SSHBorg intentionally does not allow exporting private keys. The key never leaves the device. If you need the same key on another device, generate a new key on that device and authorize it separately on your servers — this is the safer approach.

Authorizing the key on the server

After generating a key, tap it to see the public key. Copy it and paste it into the server's ~/.ssh/authorized_keys file for the user you want to log in as.

  1. On your phone, open SSHBorg → Settings → SSH Keys → tap the key → copy the public key.
  2. Log into your server (with a password, or another key you already have).
  3. Append the public key to the authorized keys file: 
    mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "ssh-ed25519 AAAA...yourcopiedkey..." >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
  4. Try connecting with SSHBorg — it should log in without asking for a password.
// SERVER REQUIREMENT
Make sure your server has PubkeyAuthentication yes in /etc/ssh/sshd_config. This is the default on most distributions, but some hardened images disable it.

Additional key encryption

SSHBorg offers an optional additional passphrase for your keys (Settings → SSH Keys → tap a key → Enable encryption). When enabled, the key is encrypted with a passphrase that SSHBorg does not store — you will be asked to enter it each time the key is used.

This is strongly recommended if you store sensitive server credentials on your phone, or if you have biometric lock disabled.

// COMMAND SUGGESTIONS

SSHBorg shows a suggestion bar above the keyboard while you type in the terminal. Suggestions are drawn from the shell history of the user you connected as.

How it works

When a terminal session opens, SSHBorg reads the shell history file from the remote server. It tries the following locations in order:

  1. ~/.bash_history — default for Bash shells
  2. ~/.zsh_history — default for Zsh (also checked as $HISTFILE if set)
  3. ~/.local/share/fish/fish_history — for Fish shell users

The first file that exists and is readable is used. As you type, commands are filtered in real time and shown as chips in the suggestion bar. Tap a chip to insert the command.

Troubleshooting

No suggestions appear

  • The history file may not exist yet (first login, or shell not configured to save history).
  • Make sure your shell is configured to write history. For Bash, add to ~/.bashrc: 
    HISTFILE=~/.bash_history
HISTSIZE=10000
HISTFILESIZE=20000
  • For Zsh, add to ~/.zshrc: 
    HISTFILE=~/.zsh_history
HISTSIZE=10000
SAVEHIST=10000
setopt APPEND_HISTORY SHARE_HISTORY

Suggestions are from the wrong user

// KNOWN LIMITATION
If you connect as one user and then run sudo su - root (or switch to another user with su), the suggestion bar still shows the history of the original login user, not of root. This is because SSHBorg reads the history file before the shell starts, using the credentials you connected with.

To get root's history suggestions, add a separate host entry in SSHBorg configured to log in directly as root (if your server allows it).

// AGENT FORWARDING

SSH agent forwarding lets the keys stored in SSHBorg be used to authenticate further connections made from inside the remote server — for example, to git clone a private repo, or to hop to a second machine.

Enabling forwarding in SSHBorg

When adding or editing a host, enable the Agent forwarding toggle. SSHBorg will act as an SSH agent for that session.

Server-side configuration

The server must allow agent forwarding. Check /etc/ssh/sshd_config:

AllowAgentForwarding yes

This is the default on most systems. After changing it, restart the SSH daemon:

sudo systemctl restart sshd

Per-host client configuration (optional)

If you also connect to this server from a laptop or desktop, you can configure forwarding persistently in your local ~/.ssh/config:

Host myserver
    HostName 203.0.113.42
    User ubuntu
    ForwardAgent yes
// SECURITY NOTE
Agent forwarding gives the remote server temporary access to your SSH agent socket. A root user (or a compromised process) on that server could use your keys to connect elsewhere while your session is active. Only enable forwarding on servers you trust.

// CONNECTION DROPS & TERMINAL MULTIPLEXERS

SSH is a live TCP connection between your phone and the server. If the connection is interrupted — even for a second — the session and everything running inside it is lost.

Why connections drop on mobile

Mobile networks are particularly prone to connection drops for several reasons:

  • IP address changes — when travelling or switching between cell towers, your carrier may assign you a new public IP. Since TCP connections are tied to the IP address, the existing SSH session becomes invalid immediately.
  • Wi-Fi ↔ mobile handover — switching between a Wi-Fi network and mobile data (or vice versa) changes your IP and breaks any open TCP connection.
  • Idle timeouts — carriers and NAT routers often drop idle connections after a few minutes. Long-running but silent sessions (watching logs, waiting for input) are vulnerable to this.
  • Signal loss — tunnels, underground car parks, or simply a weak signal can briefly drop the network, which is enough to kill a session.
// IMPORTANT
If you are running a long command (a build, a backup, a database migration) directly in the SSH terminal and the connection drops, the command is killed immediately. Any partial work may be left in an inconsistent state.

The solution: tmux or screen

A terminal multiplexer runs a persistent session on the server, completely independent of your SSH connection. If the connection drops, the session and everything running inside it keeps going. When you reconnect, you re-attach and find everything exactly as you left it.

This is the single most useful habit for anyone managing servers from a phone.

Quick start with tmux

tmux is available on most modern Linux distributions and is the recommended choice.

# Start a new named session
tmux new -s work

# Detach from the session (leave it running)
Ctrl+B, then D

# List running sessions
tmux ls

# Re-attach to a session
tmux attach -t work

# Re-attach to the most recent session
tmux attach

Quick start with screen

screen is older but available on virtually every Unix system, including minimal server images where tmux may not be installed.

# Start a new named session
screen -S work

# Detach from the session
Ctrl+A, then D

# List running sessions
screen -ls

# Re-attach to a session
screen -r work

Recommended workflow on mobile

  1. Connect to the server with SSHBorg.
  2. Start or re-attach a tmux/screen session immediately: tmux attach || tmux new -s main
  3. Run your commands inside the multiplexer.
  4. If the connection drops, just reconnect — your session is still there.
// TIP
You can add tmux attach || tmux new -s main to your ~/.bashrc or ~/.zshrc on the server so that a multiplexer session starts automatically every time you log in via SSHBorg.

// JUMP HOSTS

A jump host (also called a bastion host) is an intermediate server you must pass through to reach a target server that is not directly accessible from the internet. SSHBorg supports single and multi-hop jump chains natively.

Configuring a jump host in SSHBorg

  1. Add the bastion server as a regular host in SSHBorg (e.g. bastion).
  2. Add the target server as another host.
  3. In the target host settings, set Jump host to the bastion host you created.
  4. Enable Agent forwarding on the bastion entry — this allows your key to be forwarded through the bastion to authenticate on the target.
// HOW IT WORKS
SSHBorg establishes an SSH connection to the bastion first, then opens a forwarded TCP channel through it to the target server. Your private key never leaves the phone — the bastion only proxies the encrypted stream.

Multi-hop chains

If you need to jump through more than one intermediate server (e.g. internet → bastion → dmz → target), create an entry for each hop and chain them:

  • bastion — no jump host, agent forwarding on
  • dmz — jump host = bastion, agent forwarding on
  • target — jump host = dmz
// IMPORTANT
Agent forwarding must be enabled on every intermediate hop, not just the first one. Without it, the authentication chain breaks and the connection to the final server will fail with a "permission denied" error.

Equivalent manual configuration (for reference)

The equivalent setup in a desktop ~/.ssh/config looks like this:

Host bastion
    HostName bastion.example.com
    User admin
    ForwardAgent yes

Host target
    HostName 10.0.1.50
    User ubuntu
    ProxyJump bastion
    ForwardAgent yes

With this config, ssh target on your laptop transparently jumps through the bastion.

Firewall requirements

  • Your phone must be able to reach the bastion on its SSH port (usually 22).
  • The bastion must be able to reach the target on its SSH port.
  • The target does not need to be reachable directly from your phone.

// MULTIPLE SESSIONS

SSHBorg lets you keep several SSH terminal sessions and SFTP file manager sessions open at the same time, even to different servers.

  • Open a session from the hosts screen by tapping Terminal or SFTP.
  • Switch between open sessions using the session selector at the top of the screen.
  • Sessions stay alive in the background as long as the network connection holds.
  • The host list shows a small badge next to each host with the number of active SSH and SFTP sessions, so you can see at a glance what is open.
// TIP
Long-running commands (builds, backups, log tailing) keep running even when you switch to another session. Use a terminal multiplexer like tmux or screen on the server side if you want them to survive even if the SSH connection drops.

// APP SECURITY

Biometric lock

Enable biometric lock in Settings → Security → Biometric lock. When active, SSHBorg requires fingerprint or face unlock before showing any host, credential, or session data.

You can set an inactivity timeout — after that many minutes in the background the app locks automatically.

Screenshot protection

By default SSHBorg blocks screenshots and screen recording to prevent sensitive terminal content from leaking via the recent-apps screen or screen capture tools.

If you need to take a screenshot (e.g. to share a terminal output), you can temporarily disable screenshot protection in Settings → Security → Allow screenshots.

Credential storage

All credentials (passwords, private keys, passphrases) are stored encrypted using the Android Keystore — a hardware-backed secure enclave available on Android 10+. They are never written to external storage or transmitted anywhere.

// BACKUP NOTE
Because keys are stored in the Android Keystore, they cannot be backed up via Android's cloud backup mechanism and will not transfer to a new phone automatically. Before switching devices, make sure to authorize a new key generated on the new device on all your servers.
⚙⚙⚙