Skip to content

Key Management

Manage your SSH keys in StormTunnel.

Opening Key Management

  • Press ⌘K to open Key Management
  • Or go to Settings → SSH Keys

Window Overview

The Key Management window has three main areas:

Left: List of all your SSH keys

Middle: Details about the selected key (format, validation status, fingerprint)

Right: Actions you can perform on the key

Finding Your Keys

StormTunnel automatically finds SSH keys in your ~/.ssh/ directory. When you open Key Management, existing keys appear automatically.

Importing Keys

To use an SSH key from another location:

  1. Click Import button
  2. Select your key file (.pem, .key, or id_rsa/id_ed25519)
  3. Click Open

Or drag and drop a key file directly into the Key Management window.

Understanding SSH Keys

An SSH key pair consists of:

  • Private Key - Secret file that stays on your Mac (like a password)
  • Public Key - Shared with servers (like a username)

Common key types:

Type Best For Recommended?
ED25519 Modern servers (fast + secure) Yes
RSA Older servers (widely compatible) OK

Key Status Indicators

  • ✅ Green - Key is valid and ready to use
  • ⚠️ Yellow - Key works but has warnings (weak encryption, permissions)
  • ❌ Red - Key has problems and won't work

Using Keys in Tunnels

When creating or editing a tunnel:

  1. Choose "SSH Key" authentication method
  2. Click the dropdown and select your key
  3. Save the tunnel

The tunnel now uses that key to connect.

Copying Your Public Key

To add your key to a server:

  1. Select your key
  2. Click Copy Public Key
  3. Paste the key into the server's ~/.ssh/authorized_keys

Ask your server administrator if you're not sure where to paste it.

Filtering Keys

Click the Filter dropdown to show:

  • All Keys - Everything
  • Valid Only - Working keys (green status only)
  • Needs Attention - Keys with warnings (yellow)
  • Encrypted Keys - Password-protected keys
  • Unencrypted Keys - Keys without password protection

Searching Keys

Use the search box to find keys by name. For example:

  • github → Find keys named "github-*"
  • prod → Find production keys
  • ed25519 → Find ED25519 keys

Common Issues

Key Not Appearing

Problem: You have an SSH key but it's not showing in Key Management

Solution:

  1. Check if it's in ~/.ssh/ directory
  2. Try clicking Import manually
  3. Restart StormTunnel if needed

"Invalid Key Format" Error

Problem: Key won't import

Solution:

  • Make sure you're selecting the private key (not the .pub file)
  • Verify the file starts with -----BEGIN OPENSSH PRIVATE KEY----- or -----BEGIN RSA PRIVATE KEY-----
  • Ask where you got the key from if unsure of the format

Key Works Elsewhere But Not in StormTunnel

Problem: SSH works from Terminal but not StormTunnel

Possible solutions:

  1. Re-import the key fresh
  2. Check if key has a passphrase - StormTunnel will ask for it
  3. Verify file permissions are 600 or 400

Best Practices

  1. Use ED25519 keys - They're modern and secure
  2. Use descriptive names - e.g., id_ed25519_work instead of id_rsa
  3. Keep separate keys - Use different keys for work, personal, staging
  4. Never share private keys - Only share public keys
  5. Rotate keys regularly - At least once per year
  6. Keep backups - Store a secure backup of important keys

Need Help?

Documentation

Support