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

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

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

// 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 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 hosts. Choose where to save the file using the system file picker. The file is named sshborg_hosts.json by default.

Importing

Go to Settings → Backup → Import hosts. 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.

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": 1,
  "exported_at": "2026-05-14T10:00:00Z",
  "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
    }
  ]
}

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