SSHPortForwarder Support Doc

🌐 العربية · Deutsch · Español · Français · Italiano · 日本語 · 한국어 · Nederlands · Português (BR) · Русский · ภาษาไทย · Türkçe · 简体中文 · 繁體中文

---

SSH Port Forwarder Support Doc

Getting Started

SSH Port Forwarder (MacSSHPortForwarder) is a macOS app that creates SSH port forwards and SOCKS proxies. You configure remote hosts, ports, and authentication (password or private key), then start a forward to get a local port or SOCKS proxy without leaving the terminal or changing your SSH config. The app can run in the menu bar for quick start/stop. Your configurations, passwords (in Keychain), and key file access stay on your Mac; the app does not upload your data.

To get started with SSH Port Forwarder

1. Download and install the app (from the App Store or your distribution channel).
2. Launch the app. You can use the main window to manage configurations or the menu bar icon for quick access.
3. Add or select a forwarding configuration:
   • Enter a name, remote host, SSH port (default 22), and username.
   • Choose Password or Private Key for authentication. If using a private key, use the Browse button next to the key path to select your key file (required for the app to access it under sandbox).
   • Choose SOCKS Proxy (local SOCKS proxy) or Local Forward (forward a specific remote port to a local port), and set the local port (and remote port for Local Forward).
4. Optionally use Test to verify the SSH connection before starting.
5. Click Start to begin forwarding. Use the menu bar icon to start or stop forwards quickly.
6. Save your configuration so it persists; if you use a password, it is stored in the system Keychain.

Important: Private key file and re-selection

If you use Private Key authentication and select a key file in the app:

• The app remembers access to that file via a system bookmark (path + file identity).
• If you delete that key file and then create a new file with the same name (or same path), the app still points to the old file. The bookmark may become invalid or point to the wrong file.
• You must re-select the key file in the client: open the configuration, click Browse next to the key path, choose the new key file, then Save. Otherwise the app may fail to connect or show permission errors.

Troubleshooting

• Connection or authentication fails

  • Check remote host, SSH port, and username.
  • For password auth: ensure the password is correct and saved (Keychain).
  • For private key: ensure you selected the key via Browse, the key format is supported (OpenSSH or PEM), and if the key has a passphrase, enter it when prompted. If you replaced the key file (e.g. deleted and recreated one with the same name), re-select the key file in the app and save.

• “No permission to read the key file” or key-related errors

  • Use the Browse button to select your private key file again, then save. This is also required after replacing the key file (e.g. new key with the same path/name).

• Local port in use

  • Pick another local port in the configuration, or stop the application that is using the current port.

• Forward does not start or stays “connecting”

  • Run Test to verify SSH connectivity. Check firewall and network. Ensure the remote host allows SSH and, for Local Forward, that the remote port is correct.

• Menu bar icon or main window

  • The app can run with only the menu bar icon. Use the menu to open the full window for configuration or to start/stop forwards.

Feedback and Suggestions

We value your feedback and suggestions for improving SSH Port Forwarder.
If you have any ideas or suggestions, please send them to aidoge@yeah.net.

Thank you for using SSH Port Forwarder!