Updates Settings¶

Configure how StormTunnel checks for and installs software updates.

Location¶

StormTunnel → Settings (Cmd+,) → Updates tab

Or via menu bar: StormTunnel → Settings... → Select Updates icon

Overview¶

The Updates settings panel controls StormTunnel's automatic update behavior, allowing you to balance convenience with control over when updates are installed.

Settings Reference¶

Automatically Check for Updates¶

Default: ✅ Enabled

Controls whether StormTunnel automatically checks for new versions in the background.

Check interval: 24 hours from last check

Network impact: Minimal (< 10 KB per check)

Keep this enabled to stay informed about security updates and new features.

When this is enabled:

• Background check runs every 24 hours
• No interruption to your work
• Notification only if update is available
• You're always in control of installation

When this is disabled:

• No automatic checks
• Must manually check via StormTunnel → Check for Updates...
• May miss important security updates

Automatically Download Updates¶

Default: ❌ Disabled

Controls whether updates are downloaded in the background when found.

Requires: "Automatically check for updates" must be enabled

Download timing: Immediately when new version is detected

Network impact: Varies by update size (typically 50-100 MB)

When this is enabled:

1. New version detected during automatic check
2. Download starts automatically in background
3. Progress runs silently (no progress bar)
4. When download completes:
   • Native popup appears: "Update Ready to Install"
   • Your options:
     • "Install and Relaunch" - Quit → Install → Relaunch now
     • "Later" - Install automatically next time you quit

When this is disabled:

1. New version detected during automatic check
2. Notification appears: "Update Available"
3. You click to see update dialog
4. You choose to download or skip
5. If downloaded, you control installation timing

Enable both settings for the smoothest experience:

- ✅ Automatically check for updates
- ✅ Automatically download updates

This gives you:

- ✅ Awareness of updates
- ✅ No waiting for downloads when ready
- ✅ Still in control of installation timing

Display Information¶

Last Checked¶

Format: "Last checked: Jan 15, 2026 at 2:30 PM"

Shows when the most recent update check occurred (automatic or manual).

Not shown if:

• Never checked for updates
• Fresh installation

Security Message¶

Fixed text: "All updates are cryptographically signed for security"

Reminds you that every update is verified before installation using EdDSA signatures.

Actions¶

Check for Updates Now¶

Button: "Check for Updates Now"

Behavior:

• Triggers immediate update check
• Shows progress indicator: "Checking..."
• Contacts updates.storm-tunnel.app
• Compares your version with latest available

Results:

Shows update dialog with:

- Version number (e.g., "Version 1.2.3")
- Release notes (what's new)
- Download size
- "Install and Relaunch" button
- "Skip This Version" button

Shows dialog:

"You're up to date!"

"StormTunnel 1.2.3 is currently the newest version available."

Shows error:

"Unable to check for updates"

Common causes:

- No internet connection
- Update server unreachable
- Firewall blocking connection

Disabled when:

• Update check already in progress
• Another Sparkle operation is active

Update Flow Examples¶

Scenario 1: Manual Check (Both Settings Disabled)¶

User workflow:

1. User clicks Check for Updates Now
2. Dialog appears if update is available
3. User clicks Install and Relaunch
4. App downloads update (with progress bar)
5. App verifies signature
6. App quits → installs → relaunches

User control: Full control at every step

Scenario 2: Automatic Check Only¶

Settings:

• ✅ Automatically check for updates
• ❌ Automatically download updates

User experience:

1. App checks in background (every 24 hours)
2. If update found: notification appears
3. User clicks notification
4. Update dialog appears
5. User decides: Download or Skip
6. If download: User controls installation timing

User control: High - notified but controls download and installation

Scenario 3: Full Automation (Recommended)¶

Settings:

• ✅ Automatically check for updates
• ✅ Automatically download updates

User experience:

1. App checks in background (every 24 hours)
2. If update found: download starts silently
3. When download completes: popup appears
   • "Update Ready to Install"
   • "Version X.X.X has been downloaded and is ready to install"
4. User chooses:
   • Install and Relaunch - Immediate installation
   • Later - Installs on next quit

User control: Balanced - download is automatic, but installation is user-controlled

This scenario provides the best balance of convenience and control:

- ✅ Always aware of updates
- ✅ No waiting for downloads
- ✅ Still control installation timing
- ✅ Minimal interruption

Technical Details¶

Update Check Mechanism¶

Protocol: HTTPS only (TLS 1.3)

Endpoint: https://updates.storm-tunnel.app/appcast.xml

Request includes:

• Current app version
• macOS version (for compatibility)
• System language (for localized release notes)

Request does NOT include:

• ❌ User personal data
• ❌ Machine identifiers
• ❌ Usage statistics
• ❌ Analytics tracking

Signature Verification¶

Algorithm: EdDSA (ed25519)

Public key: Embedded in app bundle (Info.plist)

Verification steps:

1. Download update file (.dmg)
2. Download signature file
3. Verify signature matches public key
4. Compare checksums
5. Only proceed if verification passes

Security guarantees:

• ✅ Authenticity (update is from official source)
• ✅ Integrity (update hasn't been modified)
• ✅ Freshness (update is newer than current version)

Download Location¶

Temporary storage: ~/Library/Caches/in.rs.olujic.StormTunnel/Updates/

Cleanup: Automatic after installation or 7 days

Installation Process¶

Method: Sparkle XPC service (sandboxed)

Steps:

1. User authorizes installation (clicks button or quits app)
2. App quits cleanly
3. Installer XPC service launches
4. Old app moved to Trash
5. New app copied to /Applications
6. New app launched
7. Installer XPC service terminates

Permissions required: None (standard app replacement)

Keyboard Shortcuts¶

Related Settings¶

General Settings¶

• Launch at Login - Ensures you get update notifications even after reboot

Advanced Settings¶

• Development Mode - May affect update channels (if beta testing)
• Logging - Can help diagnose update issues

Privacy¶

Data Transmission¶

Sent to update server:

• ✅ App version (e.g., "1.2.3")
• ✅ macOS version (e.g., "15.0")
• ✅ System language (e.g., "en")

NOT sent:

• ❌ User name or email
• ❌ License key
• ❌ Tunnel configurations
• ❌ SSH keys or credentials
• ❌ Usage patterns
• ❌ Any personal data

Server Logs¶

Temporarily stored (for rate limiting and abuse prevention):

• IP address (24 hours)
• Timestamp (30 days)
• User agent string (7 days)

Never stored:

• Personal information
• Usage analytics

Troubleshooting¶

Check Not Starting¶

Symptoms:

• Button does nothing when clicked
• No "Checking..." indicator appears

Solutions:

1. Check internet connection
2. Verify firewall allows HTTPS to updates.storm-tunnel.app
3. Restart StormTunnel
4. Check Console.app for error messages

Download Stalls¶

Symptoms:

• Download starts but never completes
• Progress indicator stuck

Solutions:

1. Cancel and retry
2. Check available disk space (need ~100 MB)
3. Clear update cache:

   rm -rf ~/Library/Caches/in.rs.olujic.StormTunnel/Updates/
   

4. Try manual download from website

Signature Verification Fails¶

Symptoms:

• Error: "Update verification failed"
• Download completes but won't install

Solutions:

1. Delete cached update:

   rm -rf ~/Library/Caches/in.rs.olujic.StormTunnel/Updates/
   

2. Check system date/time is correct
3. Try again
4. If persists, download manually from official website

Never attempt to bypass signature verification. This security feature protects you from malicious updates.

Popup Not Appearing¶

Symptoms:

• Both automatic settings enabled
• Update downloaded (confirmed in logs)
• No popup asking to install

Diagnosis:

1. Open Settings → Advanced → View Logs
2. Search for: "Update ready to install"
3. Check if delegate method was called

Solutions:

1. Verify settings are actually saved (reopen Settings to check)
2. Restart StormTunnel
3. Try manual update check

Best Practices¶

For Most Users¶

Recommended configuration:

• ✅ Automatically check for updates
• ✅ Automatically download updates

Why: Balances security, convenience, and control

For Cautious Users¶

Conservative configuration:

• ✅ Automatically check for updates
• ❌ Automatically download updates

Why: Full control over downloads while staying informed

For Offline/Air-Gapped Machines¶

Minimal configuration:

• ❌ Automatically check for updates
• ❌ Automatically download updates

Why: No network requests; manual updates only

Note: Download updates on connected machine, transfer via USB

Version History¶

See Also¶

• Software Updates Feature - Complete feature overview
• General Settings - Launch at login configuration
• Advanced Settings - Logging and diagnostics