sshm

SSHM - SSH Manager

A modern, interactive SSH Manager for your terminal

SSHM is a beautiful command-line tool that transforms how you manage and connect to your SSH hosts. Built with Go and featuring an intuitive TUI interface, it makes SSH connection management effortless and enjoyable.

️ Click on the image to view in full size

✨ Features

Core Capabilities

• ** Beautiful TUI Interface** - Navigate your SSH hosts with an elegant, interactive terminal UI
• ⚡ Quick Connect - Connect to any host instantly through the TUI or the CLI with sshm
• ** Port Forwarding** - Easy setup for Local, Remote, and Dynamic (SOCKS) forwarding with history persistence
• ** Easy Management** - Add, edit, move, and manage SSH configurations seamlessly
• ️ Tag Support - Organize your hosts with custom tags for better categorization; use the special hidden tag to exclude hosts from the list while keeping them connectable
• ** Smart Search** - Find hosts quickly with built-in filtering and search
• ** Real-time Status** - Live SSH connectivity indicators with asynchronous ping checks and color-coded status
• ** Smart Updates** - Automatic version checking with update notifications
• ** Connection History** - Track your SSH connections with last login timestamps

️ Technical Features

• ** Secure** - Works directly with your existing ~/.ssh/config file
• ** Custom Config Support** - Use any SSH configuration file with the -c flag
• ** SSH Include Support** - Full support for SSH Include directives to organize configurations across multiple files
• ⚙️ SSH Options Support - Add any SSH configuration option through intuitive forms
• ** Automatic Conversion** - Seamlessly converts between command-line and config formats
• ** Automatic Backups** - Backup configurations automatically before changes
• ✅ Validation - Prevent configuration errors with built-in validation
• ** ProxyJump/ProxyCommand Support** - Secure connection tunneling through bastion hosts
• ⌨️ Keyboard Shortcuts - Power user navigation with vim-like shortcuts
• ** Cross-platform** - Supports Linux, macOS (Intel & Apple Silicon), and Windows
• ⚡ Lightweight - Single binary with no dependencies, zero configuration required

Quick Start

Installation

Homebrew (Recommended for macOS):

brew install Gu1llaum-3/sshm/sshm

Unix/Linux/macOS (One-line install):

curl -sSL https://raw.githubusercontent.com/Gu1llaum-3/sshm/main/install/unix.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/Gu1llaum-3/sshm/main/install/windows.ps1 | iex

Alternative methods:

Linux/macOS:

# Download specific release
wget https://github.com/Gu1llaum-3/sshm/releases/latest/download/sshm-linux-amd64.tar.gz

# Extract and install
tar -xzf sshm-linux-amd64.tar.gz
sudo mv sshm-linux-amd64 /usr/local/bin/sshm

Windows:

# Download and extract
Invoke-WebRequest -Uri "https://github.com/Gu1llaum-3/sshm/releases/latest/download/sshm-windows-amd64.zip" -OutFile "sshm-windows-amd64.zip"
Expand-Archive sshm-windows-amd64.zip -DestinationPath C:\tools\
# Add C:\tools to your PATH environment variable

Usage

Interactive Mode

Launch SSHM without arguments to enter the beautiful TUI interface:

sshm

Navigation:

• ↑/↓ or j/k - Navigate hosts
• Enter - Connect to selected host
• a - Add new host
• e - Edit selected host
• d - Delete selected host
• m - Move host to another config file (requires SSH Include directives)
• f - Port forwarding setup
• H - Toggle hidden hosts visibility
• q - Quit
• / - Search/filter hosts

Real-time Status Indicators:

• Online - Host is reachable via SSH
• Connecting - Currently checking host connectivity
• Offline - Host is unreachable or SSH connection failed
• ⚫ Unknown - Connectivity status not yet determined

Sorting & Filtering:

• s - Switch between sorting modes (name ↔ last login)
• n - Sort by name (alphabetical)
• r - Sort by recent (last login time)
• Tab - Cycle between filtering modes
• Filter by name (default) - Search through host names
• Filter by last login - Sort and filter by most recently used connections

The interactive forms will guide you through configuration:

• Hostname/IP - Server address
• Username - SSH user
• Port - SSH port (default: 22)
• Identity File - Private key path
• ProxyJump - Jump server for connection tunneling
• ProxyCommand - Jump command for connection tunneling
• SSH Options - Additional SSH options in -o format (e.g., -o Compression=yes -o ServerAliveInterval=60)
• Tags - Comma-separated tags for organization

Port Forwarding

SSHM provides an intuitive interface for setting up SSH port forwarding. Press f while selecting a host to open the port forwarding setup:

Forward Types:

• Local (-L) - Forward a local port to a remote host/port through the SSH connection

  • Example: Access a remote database on localhost:5432 via local port 15432
  • Use case: ssh -L 15432:localhost:5432 server → Database accessible on localhost:15432

• Remote (-R) - Forward a remote port back to a local host/port

  • Example: Expose local web server on remote host's port 8080
  • Use case: ssh -R 8080:localhost:3000 server → Local app accessible from remote host's port 8080
  • ⚠️ Requirements for external access:
    • SSH Server Config: Add GatewayPorts yes to /etc/ssh/sshd_config and restart SSH service
    • Firewall: Open the remote port in the server's firewall (ufw allow 8080 or equivalent)
    • Port Availability: Ensure the remote port is not already in use
    • Bind Address: Use 0.0.0.0 for external access, 127.0.0.1 for local-only

• Dynamic (-D) - Create a SOCKS proxy for secure browsing

  • Example: Route web traffic through the SSH connection
  • Use case: ssh -D 1080 server → Configure browser to use localhost:1080 as SOCKS proxy
  • ⚠️ Configuration requirements:
    • Browser Setup: Configure SOCKS v5 proxy in browser settings
    • DNS: Enable "Proxy DNS when using SOCKS v5" for full privacy
    • Applications: Only SOCKS-aware applications will use the proxy
    • Bind Address: Use 127.0.0.1 for security (local access only)

Port Forwarding Interface:

• Choose forward type with ←/→ arrow keys
• Configure ports and addresses with guided forms
• Optional bind address configuration (defaults to 127.0.0.1)
• Real-time validation of port numbers and addresses
• Port forwarding history - Save frequently used configurations for quick reuse
• Connect automatically with configured forwarding options

Troubleshooting Port Forwarding:

Remote Forwarding Issues:

# Error: "remote port forwarding failed for listen port X"
# Solutions:
1. Check if port is already in use: ssh server "netstat -tln | grep :X"
2. Use a different port that's available
3. Enable GatewayPorts in SSH config for external access

SSH Server Configuration for Remote Forwarding:

# Edit SSH daemon config on the server:
sudo nano /etc/ssh/sshd_config

# Add or uncomment:
GatewayPorts yes

# Restart SSH service:
sudo systemctl restart sshd  # Ubuntu/Debian/CentOS 7+
# OR
sudo service ssh restart     # Older systems

Firewall Configuration:

# Ubuntu/Debian (UFW):
sudo ufw allow [port_number]

# CentOS/RHEL/Rocky (firewalld):
sudo firewall-cmd --add-port=[port_number]/tcp --permanent
sudo firewall-cmd --reload

# Check if port is accessible:
telnet [server_ip] [port_number]

Dynamic Forwarding (SOCKS) Browser Setup:

Firefox: about:preferences → Network Settings
- Manual proxy configuration
- SOCKS Host: localhost, Port: [your_port]
- SOCKS v5: ✓
- Proxy DNS when using SOCKS v5: ✓

Chrome: Launch with proxy
chrome --proxy-server="socks5://localhost:[your_port]"

CLI Usage

SSHM provides both command-line operations and an interactive TUI interface:

…

Host Info (JSON)

sshm info prints a single JSON object to stdout so you can script against it with jq.

# Extract fields
sshm info prod-server | jq -r '.result.target.hostname'
sshm info prod-server | jq -r '.result.target.port'

# Check not-found (exit code 2)
sshm info does-not-exist | jq -r '.error.code'

Shell Completion

SSHM supports shell completion for host names, making it easy to connect to hosts without typing full names:

sshm            # Lists all available hosts
sshm pro        # Completes to hosts starting with "pro" (e.g., prod-server)

Setup Instructions:

Bash:

# Enable for current session
source > ~/.bashrc

Zsh:

# Enable for current session
source > ~/.zshrc

Fish:

# Enable for current session
sshm completion fish | source

# Enable permanently
sshm completion fish > ~/.config/fish/completions/sshm.fish

PowerShell:

# Enable for current session
sshm completion powershell | Out-String | Invoke-Expression

# Enable permanently (add to your PowerShell profile)
Add-Content $PROFILE 'sshm completion powershell | Out-String | Invoke-Expression'

Direct Host Connection

SSHM supports direct connection to hosts via the command line, making it easy to integrate into your existing workflow:

# Connect directly to any configured host
sshm production-server
sshm db-staging
sshm web-01

# All direct connections are tracked in your history
# Use the TUI to see your most recently connected hosts

Features of Direct Connection:

• Instant connection - No TUI navigation required
• History tracking - All connections are recorded with timestamps
• Error handling - Clear messages if host doesn't exist or configuration issues
• Config file support - Works with custom config files using -c flag

Remote Command Execution

Execute commands on remote hosts without opening an interactive shell:

# Execute a single command
sshm prod-server uptime

# Execute command with arguments
sshm prod-server ls -la /var/log

# Check disk usage
sshm prod-server df -h

# View logs (pipe to local commands)
sshm prod-server 'cat /var/log/nginx/access.log' | grep 404

# Force TTY allocation for interactive commands (sudo, vim, etc.)
sshm -t prod-server sudo systemctl restart nginx

Features:

• Exit code propagation - Remote command exit codes are passed through
• TTY support - Use -t flag for commands requiring terminal interaction
• Pipe-friendly - Output can be piped to local commands for processing
• History tracking - Command executions are recorded in connection history

Backup Configuration

SSHM automatically creates backups of your SSH configuration files before making any changes to ensure your configurations are safe.

Backup Location:

• Unix/Linux/macOS: ~/.config/sshm/backups/ (or $XDG_CONFIG_HOME/sshm/backups/ if set)
• Windows: %APPDATA%\sshm\backups\ (fallback: %USERPROFILE%\.config\sshm\backups\)

Key Features:

• Automatic backup before any modification
• One backup per file (overwrites previous backup)
• Stored separately to avoid SSH Include conflicts
• Easy manual recovery if needed

Additional Storage:

• Connection History: Stored in the same config directory for persistent tracking
• Port Forwarding History: Saved configurations for quick reuse of common forwarding setups

Quick Recovery:

# Unix/Linux/macOS
cp ~/.config/sshm/backups/config.backup ~/.ssh/config

# Windows
copy "%APPDATA%\sshm\backups\config.backup" "%USERPROFILE%\.ssh\config"

Configuration File Options

By default, SSHM uses the standard SSH configuration file at ~/.ssh/config. You can specify a different configuration file using the -c flag:

``