First-Time Setup¶

When you first launch StormTunnel, a short onboarding flow walks you through initial setup.

The Onboarding Steps¶

Step 1: Welcome¶

A brief overview of what StormTunnel does: SSH tunnel management, AWS Session Manager integration, menu bar access, and security-focused design.

Click Continue to proceed.

Step 2: SSH Key Import (Optional)¶

StormTunnel scans ~/.ssh/ for existing keys.

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:

• Click Skip and add keys later from Settings

Step 3: Privacy¶

StormTunnel's privacy model:

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

Click Get Started to finish onboarding.

After Onboarding¶

The main window opens and you're ready to create your first tunnel. See Create your first tunnel.

Troubleshooting¶

"No SSH keys found"¶

This is normal if you haven't created SSH keys yet or they're in a non-standard location.

• Skip import and use 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.

Grant Full Disk Access:

1. Open System Settings > Privacy & Security > Full Disk Access
2. Add StormTunnel
3. Restart StormTunnel and try again

Import seems stuck¶

Import usually completes in 1-2 seconds. If it doesn't, click Skip and import keys later from Settings.

Reset Onboarding¶

To see the onboarding flow again:

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