Skip to content

FAQ

Jump to bottom
Mehdi edited this page Sep 3, 2026 · 14 revisions

FAQ

Short answers to common questions. For deeper guides, follow the links. For failure fixes, see Troubleshooting.

General

Why use a GUI for SSH?
Because it’s convenient to see and manage all your servers from one clean, unified interface. No more memorizing aliases or long commands—click, connect, done.

What is SSH Pilot?
SSH Pilot is a modern, lightweight SSH connection manager for Linux and macOS that includes an integrated terminal and productivity features such as tabbed sessions, SFTP file management, connection grouping, broadcast commands, port forwarding, SCP transfers, keypair workflows, theming, and SSH config integration.

I don’t want a third-party app touching my SSH config!
Turn on Isolated Mode. SSH Pilot then uses its own SSH config, known_hosts, and keys under the app config directory, and leaves your ~/.ssh/config intact. See Isolated Mode.

Which operating systems and packages are supported?
Pre-built packages are available for Debian/Ubuntu (PPA/DEB), Fedora/RHEL/CentOS Stream (COPR/RPM), Flatpak, Arch Linux (AUR), and macOS (Homebrew and DMG for Apple Silicon and Intel). Windows is not supported natively. See Installation.

Installation & Startup

How do I install the Flatpak build?

flatpak install flathub io.github.mfat.sshpilot

Or install from Flathub. See Installation.

How do I install packages on Debian/Ubuntu or Fedora-based systems?
Use the PPA (Ubuntu) or COPR (Fedora/RHEL), or download packages from Releases. Details: Installation.

How do I run SSH Pilot from source?
Install dependencies for your distro, then launch from a checkout (for example python3 run.py). Append --verbose for detailed logging. See the project’s running from source docs.

Working with Connections

How do I open or search for connections using the keyboard?

  • Ctrl+Shift+N / Cmd+N — new connection
  • Ctrl+F / Cmd+F — search the sidebar
  • Enter — connect to the selected host
  • Ctrl+Enter / Cmd+Enter or middle-click — force a new tab
  • Double-tap Shift — Omni-search

More: Keyboard Quick Reference.

How do I manage tabs with the keyboard?
Next/previous tab: Ctrl+Page Down / Ctrl+Page Up. Close tab: Ctrl+Shift+W / Cmd+Shift+W. Tab overview: Ctrl+Shift+Tab. Toggle sidebar: F9 or Cmd+B. See Keyboard Shortcuts.

Can I organize servers into groups?
Yes. Create groups from the sidebar, drag connections onto a group, or use Move to Group / Copy to Group from the right-click menu. See Groups.

Does SSH Pilot load my existing ~/.ssh/config entries?
Yes, in default mode. Connectable Host entries appear in the sidebar. Wildcard / pattern-only hosts are treated as config rules, not as servers to click. See Connections.

How can I import my SSH config in Flatpak or Isolated Mode?
Open the application menu → SSH Config Editor, then paste or edit the config SSH Pilot uses in that mode. Changes apply to that mode’s config, not necessarily your system ~/.ssh/config.

Will edits in SSH Pilot change my ~/.ssh/config?
In default mode, yes — that keeps the CLI and the app in sync. Use Isolated Mode if you want them separate.

Terminal & File Management

What terminal features are available?
Local terminals, split view, broadcast mode, find, zoom, copy/paste (including optional copy-on-select and paste-on-right-click). See Terminal.

How do I get a plain / full-width terminal?
Hide the sidebar with F9 / Cmd+B, or set When a Terminal Opens → Hide Sidebar in Settings. See Plain Terminal Mode.

How do I work with remote files?
Use the dual-pane SFTP File Manager (Ctrl+Shift+O / Cmd+Shift+O, or Manage Files). Legacy SCP is still available for quick one-off transfers. On Linux you can also open a host in your system file manager when supported.

Key Management & Authentication

How do I generate a new SSH key from the app?
Open Copy Key to Server (Ctrl+Shift+K / Cmd+Shift+K), choose Generate new key, pick ed25519 or rsa (3072-bit), optionally encrypt with a passphrase, then OK. See Key Management.

Will existing keys show up in the key picker?
Yes. Keys with matching .pub files under your SSH directory are discovered and listed.

How do I copy a key to a remote server?
Select a server and use Copy Key to Server (toolbar or Ctrl+Shift+K / Cmd+Shift+K). You can reuse an existing key or generate one first.

How do I manage authorized_keys?
Local: application menu → Manage Local authorized_keys…. Remote: right-click a connection → Manage authorized_keys…. See Authorized Keys.

I'm still being prompted for a passphrase even though it's saved!
If your SSH config disables the agent, or BatchMode is on, OpenSSH may keep prompting. Prefer loading keys into ssh-agent (Add keys to agent on the connection), or adjust those options. See Credentials and Key Management.

My private key isn't being used for authentication!
Non-default key names often need to be selected explicitly in the connection editor (Authentication), rather than relying on automatic discovery.

Host key verification failed — what now?
Remove the old fingerprint in the Known Hosts editor, save, reconnect, and accept the new key.

Security & Privacy

Does it store passwords or passphrases in plain text?
No. Secrets go into a credential backend (system keyring / libsecret, KeePass, Bitwarden/Vaultwarden, or pass). See Security and Credentials.

How does SSH Pilot protect my credentials?
Connect-time secrets are supplied to OpenSSH through askpass — not typed into the terminal stream or written into preference files as plaintext. See Security.

Is the application open source?
Yes. SSH Pilot is free software under the GPL v3 license.

Where can I find askpass debug logs?
sshpilot-askpass.log under $XDG_RUNTIME_DIR (or SSHPILOT_ASKPASS_LOG_DIR if set). You can also run sshpilot --verbose and look for ASKPASS: lines. See Troubleshooting.

Customization & Appearance

Can I adjust the interface to my preferences?
Yes — themes, accent color, terminal fonts/schemes, sidebar Full vs Minimal, and what the sidebar shows. See Settings and Sidebar.

Default shortcuts interfere with another app I use in the terminal.
Open Settings → Shortcuts (or Ctrl+? / Cmd+?) and change or clear the shortcut. Or enable Terminal Shortcut Pass-through under Settings → Terminal → Keyboard. See Keyboard Shortcuts.

Troubleshooting & Support

CLI ssh works, but SSH Pilot won’t connect?
Usually the graphical askpass prompt failed. Run sshpilot --verbose and check ASKPASS: logs. See Troubleshooting.

Does it support feature X/Y/Z?
If OpenSSH supports it, SSH Pilot usually does — it uses your config and the system ssh. Common options such as Host patterns, IdentityFile, ProxyJump, and port forwarding are supported. See Connections and Protocols for non-SSH connection types.

How do I report a bug?
Run sshpilot --diagnostics and attach the sanitized zip to a GitHub Issue. See Troubleshooting.

Where can I ask questions or follow updates?
GitHub Issues for bugs and requests, and the Telegram channel t.me/sshpilot for announcements and community chat.

Related

Clone this wiki locally