Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

sshelf

A fast terminal UI for managing and connecting to SSH hosts. Save each node once, then fuzzy-search and connect in two keystrokes.

sshelf keeps its own host database and generates the correct ssh command for you. It never reads or edits ~/.ssh/config (except an explicit, read-only import). No account, no cloud, no telemetry: your hosts live in a human-readable TOML file on your disk, secrets live in your OS keyring, and the only network activity is the ssh it hands your terminal to.

Get started

brew install max-rh/tap/sshelf     # macOS or Linux
sshelf                             # launch the TUI
  • Install: Homebrew, shell installer, .deb, .rpm, Gentoo, or cargo.
  • Quickstart: the first five minutes, adding or importing hosts, connecting.
  • FAQ & troubleshooting: common questions, quick answers.
  • sshelf doctor: when something isn’t working, run this first.

What’s in the box

  • An atuin-style fuzzy launcher with frecency ordering. Searching & connecting
  • A dual-pane SFTP file browser (Ctrl-t): mark several, send in one go, F7 to create a directory. Transferring files
  • tmux mode, where Enter opens each host in a new window or pane and keeps the picker up. Connecting inside tmux
  • Background port forwards that survive quitting (Ctrl-f / F4). Port forwarding
  • Sites with a shared bastion and defaults, plus free-form tags (F3). Sites & tags
  • Stored passwords and passphrases auto-supplied at connect, and 2FA code prompts. Passwords, keys & 2FA
  • SSH-config export: one Include line and plain ssh/scp, rsync, and VS Code Remote see your hosts. Exporting to SSH config
  • Import from ~/.ssh/config or your whole Tailscale tailnet (--tailscale). Importing hosts
  • A scriptable CLI (sshelf add, list --json, print-command, …). CLI reference
  • sshelf doctor, one command that checks your setup and names the fix. Checking your setup

Platforms: macOS + Linux, x86_64 and arm64. Runtime: OpenSSH 8.4+ for password auto-supply.

How it’s built

Deciding whether to trust it, or just curious how the pieces fit?

  • Security & threat model: exactly what stored secrets are protected against, and what they are not.
  • How the ssh command is built: argv generation and the SSH_ASKPASS mechanism that supplies passwords without sshpass.
  • Privacy: what sshelf reads, writes, runs, and sends, in plain terms. Nothing leaves your machine.

Contributing

Questions, ideas, and feature requests belong in GitHub Discussions.

Start with CONTRIBUTING.md, then the Development section in the sidebar: architecture, module map, data model, and the decision log. Docs follow the docs-in-sync rule: every behavior change updates the relevant page here in the same change, with a dated entry in the progress log.