Skip to content

Connection History Reference

Quick reference for connection history data, settings, and usage.

For the complete guide, see Connection History & Analytics.

Event Types

Event Description
connected Tunnel successfully established
disconnected Tunnel closed (manual or automatic)
error Connection failed with error details
stage_changed Connection progress update (optional, disabled by default)
mode_changed SSH mode switched (NIOSSH ↔ CLI)

Connection Stages

Stage Description
preflight Checking port availability and initial validation
authenticating Connecting to SSH server with authentication
complete Tunnel active and port forwarding established
orphaned App terminated while connected (cleanup event)

Statistics Metrics

Metric Description
Total Sessions All connection attempts (successful and failed)
Successful Connections that completed without errors
Failed Connections that ended in error
Success Rate (Successful ÷ Total) × 100%

Settings Reference

Located in Settings → Advanced under Connection History section:

Setting Range Default Description
Max Events per Tunnel 20-200 50 Maximum history entries stored per tunnel
Retention Period 7-90 days 30 days How long to keep connection events
Track Error Events On/Off On Record connection failures in history
Track Stage Events On/Off Off Record connection progression stages
Track Mode Events On/Off On Record SSH mode switches
Anonymize Hostnames On/Off Off Replace remote hosts with secure hashes
Excluded Tunnels List Empty Tunnels excluded from history tracking

Performance Recommendation

Use default settings (50 events, 30 days, stage events disabled) for optimal performance.

Data Storage

Location: Application UserDefaults (encrypted on macOS)

What's stored:

  • Connection timestamps (ISO 8601 format)
  • Event types and details
  • Tunnel names and identifiers
  • Remote hosts (or anonymized hashes)
  • Local ports
  • SSH mode used
  • Error messages
  • Connection durations
  • Session metadata (retry attempts, etc.)

What's NOT stored:

  • Passwords
  • SSH private keys
  • Authentication credentials
  • Command line input/output

Backup and Restore

Automatic backup of previous history data is maintained. If data corruption occurs, the backup is automatically restored.

License Tiers

Feature Free Premium
Connection History Last 5 events Unlimited
Search & Filter Available Available
Statistics Dashboard Upgrade prompt Full analytics
Timeline Chart Not available macOS 13+ only
Time Range Filters Limited All options
Retention Settings 30 days max Up to 90 days

Search & Filters

Search Fields

  • Tunnel Name: Partial matches
  • Remote Host: Domain names, IP addresses
  • Error Messages: Text from error events only

Filter Options

Filter Options
Event Type All Events, Connected, Disconnected, Error, Stage Changed, Mode Changed
Tunnel All Tunnels, or specific tunnel
Time Range Last 24 Hours, Last 7 Days, Last 30 Days, All Time

Combined Filtering

Multiple filters work together. For example, filter by "Error" event type + specific tunnel + time range.

Duration Formatting

Duration Format Examples
< 1 minute 45s 30s, 45s
1-59 minutes 15m 5m, 30m, 45m
1-24 hours 2h 30m 1h, 2h 30m, 8h 15m
> 24 hours 3d 5h 1d 2h, 3d 5h, 7d 12h

Status Icons

Icon Status Color
● Connected Green
○ Disconnected Gray
✗ Error Red
→ Stage Changed Blue
🔄 Mode Changed Orange

Common Error Messages

Error Common Cause Solution
Connection refused Server not listening or firewall blocking Check server status and firewall rules
Authentication failed Invalid credentials or key Verify SSH key and permissions
Connection timeout Network unreachable or slow Check network connectivity and DNS
Permission denied Insufficient user permissions Verify user account and sudo requirements
Host key verification failed Host key changed or unknown Update known_hosts or verify server

Privacy Features

Hostname Anonymization

Replaces remote hostnames with consistent SHA-256 hashes:

Before: prod-db.example.com
After:  3A7F9C2D

Benefits:

  • Protects sensitive infrastructure names
  • Maintains analysis capabilities (same host = same hash)
  • No impact on error tracking or troubleshooting

Tunnel Exclusion

Prevents specific tunnels from being tracked:

  1. Open Settings → Advanced
  2. Locate Connection History section
  3. Add tunnels to exclusion list
  4. Excluded tunnels won't appear in history

Use Cases:

  • Production tunnels with compliance requirements
  • Temporary or test tunnels
  • Sensitive infrastructure connections

Troubleshooting

History Shows No Data

Causes:

  1. No connections established yet
  2. Filters hiding all events
  3. History recently cleared
  4. Fresh application installation

Solutions:

  1. Connect to at least one tunnel
  2. Clear all filters
  3. Check retention settings
  4. Wait for connections to accumulate

Can't Find Specific Connection

Causes:

  1. Outside selected time range
  2. Filter excludes the connection
  3. Connection exceeded retention period
  4. Free tier limit (only last 5 visible)

Solutions:

  1. Select "All Time" or longer range
  2. Clear filters and try search
  3. Check if tunnel is in exclusion list
  4. Upgrade to Premium for full history

Statistics Incorrect

Causes:

  1. Time range filtering affects calculations
  2. Active filters change which sessions counted
  3. Cached data not yet updated

Solutions:

  1. Verify selected time range
  2. Clear all filters
  3. Refresh the history window
  4. Wait for statistics to recalculate