Why I Built an SSH Config and Tunnel Manager for macOS

Every internal tool I need resides behind SSH connections. This includes services like Grafana, Prometheus, staging clusters, and internal AI tooling. None of these services are accessible via a public address, and they are only reachable through a bastion host guarded by a specific SSH key. This configuration is ideal for handling sensitive data, but it does require repetitive typing of long commands across multiple machines.

To alleviate this tedious process, I began developing an SSH Config and Tunnel Manager for macOS. This native application, named SSH Config Manager, simplifies the process of managing SSH configuration files and tunnel settings. It was initially created to enhance my personal workflow, but its usefulness quickly became apparent to others facing similar challenges.

The VPN alternative was proposed, but it was dismissed in favor of SSH due to the complexity it introduces. VPNs require an additional network layer, separate credentials, background daemons, and unique failure modes to troubleshoot. Additionally, SSH is already familiar, widely used, and requires no additional setup. The main drawback of not using a VPN is the need for manual port forwarding for internal services, which can be cumbersome for colleagues using different machines with varying configurations.

Shell aliases, while a potential solution, proved unreliable due to inconsistencies across different environments, making it difficult to maintain a consistent setup. The configuration file itself, ~/.ssh/config, is the most portable and standardized solution. The app was designed to work seamlessly with this file, rather than relying on shell scripts.

One of the main issues with the configuration file is the lack of user-friendly documentation and auto-completion features. To address this, the app includes a comprehensive keyword catalog, complete with detailed descriptions and expected value types for each SSH configuration option. This feature helps users avoid mistakes and quickly find the information they need while editing the configuration file.

All changes made to the configuration file are preserved, and the app ensures that comments, blank lines, and custom formatting remain intact. The tunnel engine, which handles the actual SSH tunnel connections, operates entirely within the app, avoiding the use of the system's built-in SSH binary. This approach aligns with Apple's App Store guidelines and provides a more secure and controlled environment for managing SSH tunnels.

The tunnel engine supports local listeners, SOCKS5 proxy listeners, and reverse connections, with each type of tunnel managed through the same connection model. ProxyJump directives are handled recursively, ensuring that the correct configuration is applied at each step of the connection process. To maintain compatibility with existing SSH configurations, the app verifies host keys against the known_hosts file and utilizes the trust-on-first-use (TOFU) mechanism for new hosts.

This SSH Config and Tunnel Manager for macOS aims to streamline the process of managing SSH connections and tunnels, making it easier for users to access internal services securely and efficiently.