Skip to content

First-Time Setup

When you launch StormTunnel for the first time, a quick onboarding flow helps you get started.

The 3 Onboarding Steps

Step 1: Welcome

Overview of StormTunnel's features:

  • SSH Key Management
  • Secure Tunneling
  • SSH Config Integration
  • Smart Notifications

Click Continue to proceed.

Step 2: SSH Key Import (Optional)

StormTunnel can import your existing SSH keys from ~/.ssh/.

If keys are found:

  • Review the list of discovered keys
  • Click Import SSH Keys to copy them to StormTunnel's secure storage
  • Your original keys remain untouched

If no keys are found:

  • This is normal if you're new to SSH or haven't created keys yet
  • Click Skip to continue without importing
  • You can add keys later from Settings

What gets imported

StormTunnel copies your private keys to its own app directory. Your original ~/.ssh/ keys are never modified.

Step 3: Privacy

Learn about StormTunnel's privacy approach:

  • Local-first - All data stays on your Mac
  • No tracking - No analytics or telemetry
  • Secure storage - Passwords in macOS Keychain

Click Get Started to finish onboarding.

After Onboarding

Once complete, the main StormTunnel window opens and you're ready to create your first tunnel.

Next step: Create your first tunnel

Troubleshooting

"No SSH keys found"

This is normal if:

  • You haven't created SSH keys yet
  • Your keys are in a non-standard location

Solutions:

  • Skip import and create tunnels using password authentication
  • Add keys later from Settings → Keys
  • Generate new keys using StormTunnel's key management

"Permission denied" during import

StormTunnel can't read your ~/.ssh/ directory.

Solution: Grant Full Disk Access:

  1. Open System Settings → Privacy & Security → Full Disk Access
  2. Add StormTunnel to the list
  3. Restart StormTunnel and try again

Import seems stuck

  • Wait a moment - import usually completes in 1-2 seconds
  • If it doesn't complete, click Skip and import keys later from Settings

Keyboard Shortcuts

Action Shortcut
Continue / Primary action Enter
Skip (on import screen) S
Navigate between buttons Tab

Reset Onboarding

To see the onboarding flow again:

  1. Quit StormTunnel
  2. Delete the app container: ~/Library/Containers/in.rs.olujic.StormTunnel/
  3. Launch StormTunnel

Warning

This resets all app settings, not just onboarding.

Next Steps