Debugging & Logs
Connection issues are often timing-sensitive: login startup, network changes, VPN readiness, or quick forwards added while a master is still connecting. SSH Tunnel logs each connection step so failures can be reconstructed after the fact.
Use Copy Debug Log from the menu bar to copy recent logs to the clipboard and reveal the persistent log file in Finder.
Log sinks
Section titled “Log sinks”| Sink | Location | Survives relaunch? | Best for |
|---|---|---|---|
| Unified logging | Console.app or log CLI | Yes | Live filtering |
| Persistent file | ~/Library/Logs/SSHTunnel/tunnel.log | Yes | Login and restart issues |
| In-memory buffer | Copy Debug Log | No | Quick bug reports |
All sinks use the subsystem com.sshtunnel.app, with categories such as
lifecycle, ssh, master, forward, network, ports, reconnect, and
health.
Stream logs live
Section titled “Stream logs live”log stream --predicate 'subsystem == "com.sshtunnel.app"' --level debugPull the last hour after the fact
Section titled “Pull the last hour after the fact”log show --last 1h --predicate 'subsystem == "com.sshtunnel.app"' --info --debugDiagnostics
Section titled “Diagnostics”For configuration problems, use Run Diagnostics in Settings. It validates
required fields, runs ssh -G, lists SSH config forwards, checks ControlPath
safety, and verifies local port availability. See
Settings.