About

Origin

ssm started as a subcommand inside dots, a macOS development environment tool. It managed SSH sessions as part of a larger suite. Over time it grew enough features and complexity that it made sense to pull it out into its own binary.

Now ssm is a standalone tool that anyone can install without needing the rest of dots. The name stands for SSH Session Manager. It does one thing: manage your SSH sessions from a terminal UI. It handles connecting, storing passwords securely, organizing sessions with tags, and probing hosts to see which ones are alive.

What ssm does

ssm provides a rich terminal interface for managing SSH sessions. You can add, edit, and delete sessions through a form-based TUI. Each session stores a name, host, user, port, optional ProxyJump, tags, and optionally a password.

ssm supports two connection modes: plain SSH and herdr. For plain SSH, it passes the session config to ssh with StrictHostKeyChecking=accept-new so first-time connections work but changed host keys still abort. For herdr, it shells out to system ssh so the same SSH_ASKPASS mechanism supplies the password in both modes.

The password is the key part. Instead of storing it in a file, ssm puts it in your OS keychain. When you connect to a host that has a stored password, ssm acts as an SSH_ASKPASS helper, serving the password to ssh through a one-time-nonce Unix socket. The password never appears on the command line, in an environment variable, or on disk.

Security model

ssm takes a security-first approach to credential handling. Passwords live in the OS keychain (macOS Keychain or Linux Secret Service via the keyring crate). At connect time, ssm creates a temporary Unix domain socket with 0600 permissions and a random nonce. It tells ssh to use itself as the SSH_ASKPASS helper. The ssh process re-execs ssm, which connects to the socket, presents the nonce, and receives the password. This is serve-once: if auth fails, the helper returns empty instead of looping.

ssm only answers password prompts. It refuses key passphrase prompts and host key confirmation prompts. Unknown host keys are never auto-accepted; StrictHostKeyChecking is set to accept-new (first connection only).

There is also an optional biometric gate. When enabled, ssm checks for fingerprint presence via fprintd-verify on Linux before releasing a stored password. On macOS, Touch ID requires a stably code-signed binary and is not wired up yet; enabling it falls back to a plain keychain read with a warning.

Import and organization

ssm can import sessions directly from your ~/.ssh/config file. It reads concrete Host blocks (skipping wildcards like Host *) and carries over HostName, Port, User, and ProxyJump directives. Sessions are stored as JSON at ~/.config/ssm/sessions.json, but passwords are excluded from this file entirely.

Tags let you organize sessions into groups. Press T to open a tag picker and filter the list. Search also matches against tags.

Live probing

In the background, ssm runs TCP connect probes on a dedicated thread every few seconds. Each session gets a latency measurement and a color-coded status dot: green for fast (<50ms), yellow for moderate (<200ms), red for unreachable. A small sparkline shows latency history over time. You can toggle probing on or off at runtime.

Themes

ssm ships with 7 built-in themes derived from popular terminal color schemes: noir-cat (Catppuccin Mocha on neutral gray), knew-pines (Rose Pine), catppuccin (Catppuccin Mocha), gruvbox, nord, tokyo-night, and auto (follows your terminal's ANSI palette). Switch themes live from the TUI with Space, Settings, Theme.