Connection History¶
Track and analyze SSH tunnel connections. The history window records every connection event automatically and stores it locally.
Opening the History Window¶
Open connection history from the main application menu, or from an individual tunnel's detail view.
Event Types¶
Each history entry shows the tunnel name, event type, SSH mode (NIOSSH or CLI), remote host, local port, and timestamp.
| Event | Description |
|---|---|
| Connected | Tunnel established successfully |
| Disconnected | Tunnel closed; shows session duration |
| Error | Connection failed; includes error message |
| Stage Changed | Progression through preflight/auth/connected stages |
| Mode Changed | Switch between NIOSSH and CLI implementations |
Stage change events are disabled by default. Enable them in Settings > Advanced if you need connection-stage diagnostics.
Search and Filtering¶
The filter bar at the top of the history window has four controls:
- Search -- matches against tunnel name, remote host, and error messages (case-insensitive).
- Event type -- limit to one of the five event types above.
- Tunnel -- show events for a single tunnel.
- Time range -- last 24 hours, 7 days, 30 days, or all time.
All filters combine. For example, set Event type to "Error", Tunnel to "Production DB", and search for "timeout" to find timeout errors on that tunnel in one step.
Statistics Dashboard (Premium)¶
Premium users see a statistics panel above the history list with four metrics: total sessions, successful, failed, and success rate. Below the metrics:
- Connection timeline chart -- plots connections over time with duration on the Y-axis. Green dots are successes, red dots are failures. Requires macOS 13+.
- SSH mode breakdown -- connection counts per SSH implementation.
- Tunnel type breakdown -- SSH vs. AWS Session Manager usage.
Statistics update automatically when you change the time range filter.
Settings¶
Configure connection history in Settings > Advanced.
| Setting | Default | Range | Notes |
|---|---|---|---|
| Max events per tunnel | 50 | 20--200 | Oldest events pruned when limit reached |
| Retention period | 30 days | 7--90 days | Events older than this are auto-deleted |
| Track error events | On | On/Off | |
| Track stage events | Off | On/Off | Enable for connection-stage diagnostics |
| Track mode events | On | On/Off | |
| Anonymize hostnames | Off | On/Off | Replaces hosts with consistent SHA-256 hash |
| Tunnel exclusions | None | Per-tunnel | Excluded tunnels are never recorded |
Settings take effect immediately.
Privacy¶
- Hostname anonymization replaces hostnames with a stable SHA-256 hash, so you can still correlate events without exposing the actual host.
- Tunnel exclusions prevent selected tunnels from appearing in history at all.
- Clear All in the history window header permanently deletes all history. You can also clear history for a single tunnel from its detail view.
Clearing history is irreversible
Deleted history cannot be recovered. Clearing applies immediately.
Storage¶
History is stored in UserDefaults on your Mac. It is encrypted at rest by macOS, never transmitted externally, and never synced to the cloud. Typical size is under 1 MB. Credentials and passwords are never stored in history.
License Tiers¶
| Capability | Free | Premium |
|---|---|---|
| Visible events | Last 5 | Unlimited |
| Search and filtering | Yes | Yes |
| Statistics dashboard | No | Yes |
| Time range options | Limited | All |
| Max retention | Default only | Up to 90 days |
Events are still recorded on the free tier -- they become visible if you upgrade. Downgrading hides events beyond the last 5 but does not delete them.