<img src="https://github.com/Gu1llaum-3/sshm/raw/v1.11.0/images/logo.png" alt="SSHM Logo" width="120" />

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

<a href="https://github.com/Gu1llaum-3/sshm/raw/v1.11.0/images/sshm.gif" target="_blank">
    <img src="https://github.com/Gu1llaum-3/sshm/raw/v1.11.0/images/sshm.gif" alt="Demo SSHM Terminal" width="800" />
</a>



<em>🖱️ Click on the image to view in full size</em>

✨ 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 <host>
• 🔄 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:

# Launch interactive TUI mode for browsing and connecting to hosts
sshm

# Connect directly to a specific host (with history tracking)
sshm my-server

# Execute a command on a remote host
sshm my-server uptime

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

# Force TTY allocation for interactive commands
sshm -t my-server sudo systemctl restart nginx

# Launch TUI with custom SSH config file
sshm -c /path/to/custom/ssh_config

# Connect directly with custom SSH config file
sshm my-server -c /path/to/custom/ssh_config

# Add a new host using interactive form
sshm add

# Add a new host with pre-filled hostname
sshm add hostname

# Add a new host with custom SSH config file
sshm add hostname -c /path/to/custom/ssh_config

# Edit an existing host configuration
sshm edit my-server

# Edit host with custom SSH config file
sshm edit my-server -c /path/to/custom/ssh_config

# Move a host to another SSH config file (requires Include directives)
sshm move my-server

# Move host with custom SSH config file (requires Include directives)
sshm move my-server -c /path/to/custom/ssh_config

# Search for hosts (interactive filter)
sshm search

# Print machine-readable info (JSON) for scripting
sshm info prod-server
sshm info prod-server --pretty

# With a custom SSH config file
sshm -c /path/to/custom/ssh_config info prod-server

# Pipe to jq
sshm info prod-server | jq -r '.result.target.hostname'
sshm info prod-server | jq -r '.result.target.user'

# Show version information
sshm --version

# Disable automatic update check (useful on air-gapped machines)
sshm --no-update-check

# Show help and available commands
sshm --help

Host Info (JSON)

sshm info <hostname> 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 <TAB>           # Lists all available hosts
sshm pro<TAB>        # Completes to hosts starting with "pro" (e.g., prod-server)

Setup Instructions:

Bash:

# Enable for current session
source <(sshm completion bash)

# Enable permanently (add to ~/.bashrc)
echo 'source <(sshm completion bash)' >> ~/.bashrc

Zsh:

# Enable for current session
source <(sshm completion zsh)

# Enable permanently (add to ~/.zshrc)
echo 'source <(sshm completion zsh)' >> ~/.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 manu