// USER GUIDE

// 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.

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

// HOST GROUPS

When the server list grows, you can organize hosts into collapsible, color-coded groups — for example Production, Home lab, Clients.

Creating a group

1. Add or edit a host and open the Group dropdown.
2. Choose New group…, type a name and pick one of the predefined colors.
3. Save the host — the host list now shows the group as its own section.

Working with groups

• Collapse / expand — tap a group header to fold or reopen it. The state is remembered, even after restarting the app.
• Color — the group color appears as a dot in the header and as the tint of the host icons inside the group.
• Edit — long-press the group header and choose Edit to rename the group or change its color.
• Delete — long-press the header and choose Delete. The hosts in the group are not deleted — they simply become ungrouped.

Colors can be picked from the quick swatches or mixed freely with the gradient color picker. A host can also have its own color — set it in the host editor, right below the group — which overrides the group color and works for ungrouped hosts too.

Hosts without a group stay at the top of the list, and if you never create a group the list looks and behaves exactly as before.

// SFTP FILE MANAGER

The SFTP file manager lets you browse, upload, download, rename, and delete files on your server directly from your phone. Open an SFTP session from the hosts screen by tapping SFTP.

Navigation

Tap a folder to open it. Use the back arrow or tap any segment of the path bar to jump up the directory tree.

Symbolic links are shown with a small link icon badge. Tapping a symlink navigates to its target: if it points to a directory you enter it, if it points to a file it behaves like a regular file.

Uploading files

Tap the upload button (↑) to pick one or more files from your phone's storage. The upload starts immediately and progress is shown at the top of the screen.

Downloading files and folders

Tap any file to download it immediately. To download an entire folder, tap the download icon next to it — SSHBorg will download the entire directory tree and save it under the Downloads folder on your phone.

If a file already exists at the destination, a dialog will ask you whether to overwrite, skip the file, or cancel the entire transfer.

Multi-select and batch operations

Long-press any item to enter selection mode, then tap additional items to build up your selection. The toolbar shows actions for the current selection:

• Download — downloads all selected files and folders at once, with a progress dialog and cancellation support.
• Delete — deletes all selected items. Deleting a non-empty folder removes all its contents recursively. There is no undo.

// 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.

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.

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

// TERMINAL GESTURES

The terminal responds to a few touch gestures beyond typing:

• Scroll history — swipe up or down to browse the terminal's scrollback buffer.
• Zoom — pinch to increase or decrease the text size.
• Copy text — long-press anywhere on the terminal to enter selection mode. Drag the handles to adjust the selected area, then tap Copy selection to copy only the highlighted text, or Copy all to copy the entire output. Tap anywhere else to cancel.
• Paste — use the Paste button in the extra-key bar (visible when the keyboard is open).

// TERMINAL SETTINGS

Under Settings → Terminal you can adapt the terminal to your needs:

• Terminal colors — the classic dark scheme (white on black), a light scheme (black on white) that is easier to read in bright daylight, or match app theme, which switches automatically together with the app theme. The change applies immediately, including to sessions that are already open.
• Keep screen on — prevents the display from turning off while a terminal is open. Handy when watching logs or long-running commands. Off by default.
• Default font size — the text size new terminal sessions start with; you can still pinch-zoom each session individually.
• Scrollback, inverted scrolling and command suggestions — control how much output history is kept, the scroll direction, and the suggestion bar described above.
• Double-tap action — optionally make a double-tap on the terminal send Tab (auto-complete), or two Tabs (list all candidates). Off by default.

// EXTRA KEY BAR

When the soft keyboard is open, a row of shortcut buttons appears above it. Scroll the bar sideways to reach all the keys.

Modifier keys

Ctrl and Alt are sticky toggles — tap one, then tap a letter key to send the combination. They reset automatically after the next keystroke.

• Ctrl+C — interrupt the running process.
• Ctrl+D — send EOF / close the shell.
• Ctrl+Z — suspend the process.
• Ctrl+L — clear the screen.

Word mode

The spellcheck icon toggles the keyboard between terminal mode and word mode. In terminal mode (default) autocorrect and word suggestions are disabled — ideal for commands and file paths. In word mode the keyboard behaves like a normal text field, with suggestions and autocorrect enabled. Useful when typing natural language over SSH, for example with Claude Code or other interactive tools.

Navigation and editing

• ESC — Escape key.
• Tab — shell autocomplete.
• ↑ ↓ ← → — cursor arrow keys.
• Home / End — jump to the beginning or end of the line.
• PgUp / PgDn — page up / page down.
• Del — forward delete (character to the right of the cursor).
• Paste — paste the clipboard into the terminal.

Function keys

Scroll the bar to the right to reach F1 through F12.

// 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

// LEGACY CIPHER SUPPORT

Some older servers — network appliances, embedded devices, or systems running outdated OpenSSH versions — only support cipher algorithms that modern SSH clients no longer advertise by default.

When you enable the Allow Legacy Ciphers toggle in the host settings, SSHBorg appends the following additional algorithms to the negotiation list:

Added algorithms

• Ciphers: aes128-cbc, aes192-cbc, aes256-cbc, 3des-cbc
• Key exchange: diffie-hellman-group14-sha1, diffie-hellman-group-exchange-sha1, diffie-hellman-group1-sha1
• Host key type: ssh-dss (DSA 1024-bit)

The server always negotiates the strongest algorithm both sides support, so enabling this option does not weaken connections to modern servers — the legacy algorithms are only used when the server cannot offer anything better.

// 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.

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.

// 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.

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

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.

// 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.

// CONFIGURATION BACKUP

SSHBorg can export and import host configurations and app settings as a JSON file. This lets you transfer your server list to another device or keep a portable backup of your setup.

Exporting

Go to Settings → Backup → Export backup. Choose where to save the file using the system file picker. The file is named sshborg_backup.json by default.

Importing

Go to Settings → Backup → Import backup. Select the .json file you previously exported (or created manually). SSHBorg merges it with the existing host list:

• Hosts whose label matches an existing entry are updated.
• Hosts with a new label are added.
• Hosts not present in the file are left unchanged.
• An updated host keeps its saved password, key and accepted host key — the backup never carries them.

JSON format

The export file is a plain JSON object. You can also create it by hand to bulk-import a server list from another source.

{
  "version": 3,
  "exported_at": "2026-05-14T10:00:00Z",
  "groups": [
    { "name": "Production", "color": -1754827 }
  ],
  "hosts": [
    {
      "label":           "My VPS",
      "hostname":        "203.0.113.42",
      "port":            22,
      "username":        "ubuntu",
      "agentForwarding": false,
      "jumpMode":        "simple",
      "jumpHosts":       null,
      "jumpHostIdList":  null,
      "portForwardings": null,
      "sftpStartMode":   "last",
      "sftpStartDir":    null,
      "allowLegacyCiphers": false,
      "group":           "Production"
    }
  ],
  "settings": {
    "night_mode":            0,
    "scrollback_lines":      2000,
    "terminal_font_size":    13,
    "terminal_color_scheme": 0,
    "double_tap_action":     0
  }
}

The optional settings object holds your app preferences and is written automatically on export; you can leave it out when creating the file by hand.

Field reference

• label — display name shown in SSHBorg. Used as the unique key for merging on import. Required.
• hostname — server address or IP (IPv4 or IPv6). Required.
• port — SSH port. Defaults to 22.
• username — login user. Required.
• agentForwarding — true to enable SSH agent forwarding. Defaults to false.
• jumpMode — "simple" (use the jumpHosts text) or "host_list" (use SSHBorg internal host IDs). Use "simple" when creating the file manually.
• jumpHosts — comma-separated jump hosts in [user@]host[:port] format. Only used when jumpMode is "simple".
• portForwardings — newline-separated local port-forwarding rules in SSH -L syntax, e.g. "8080:localhost:8080".
• sftpStartMode — SFTP starting directory: "last" (remember last visited), "fixed" (always use sftpStartDir), "home" (server home). Defaults to "last".
• sftpStartDir — path to use when sftpStartMode is "fixed".
• allowLegacyCiphers — true to enable the legacy cipher algorithms described above. Defaults to false.
• group — name of the group the host belongs to. Groups are listed in the top-level groups array with their name and color (ARGB as a signed 32-bit integer). If a host references a group that is not in the array, it is created automatically with a default color — so you can omit the array entirely when writing the file by hand.
• color — optional per-host color (ARGB as a signed 32-bit integer). It overrides the group color.