Skip to content

Getting Started

Get up and running with StormTunnel in about 5 minutes.

Install StormTunnel

  1. Download from the App Store or official website
  2. Drag to your Applications folder
  3. Launch StormTunnel
  4. Complete onboarding - import SSH keys (optional) and review privacy info

First Launch

StormTunnel will ask to access your Keychain (for secure password storage) and network. These are required for SSH connections.

Create Your First Tunnel

Step 1: Open New Tunnel Dialog

Click the + button in the toolbar, or press Cmd+N.

Step 2: Choose Tunnel Type

  • SSH Tunnel - For servers you connect to via SSH
  • AWS Session Manager - For EC2 instances (requires AWS CLI)

Step 3: Configure the Tunnel

For an SSH Tunnel, fill in:

Field Example Description
Name dev-postgres A name you'll recognize
SSH Host [email protected] Your SSH connection
Local Port 5432 Port on your Mac
Remote Host localhost Where to forward (usually localhost)
Remote Port 5432 Port on the server

Step 4: Set Up Authentication

Choose one:

  • SSH Key (recommended) - Select your private key file
  • Password - Enter your SSH password (stored in Keychain)

Step 5: Save and Connect

  1. Click Save
  2. Click the play button ▶️ next to your tunnel
  3. Wait for the status to turn green

Use Your Tunnel

Once connected, the remote service is available on your Mac at localhost:[local port].

Example: If you created a PostgreSQL tunnel with local port 5432:

  • Connect your database client to localhost:5432
  • The connection goes securely through SSH to the remote database

Quick Reference

Status Colors

Color Meaning
🟢 Green Connected
⚫ Gray Disconnected
🟡 Yellow Connecting
🔴 Red Error

Essential Shortcuts

Action Shortcut
New tunnel Cmd+N
Connect/disconnect Space
Settings Cmd+,
Search Cmd+F

Common Issues

"Connection refused"

  • Check hostname/IP is correct
  • Verify SSH port (usually 22)
  • Make sure server is accessible

"Permission denied"

  • Select the correct SSH key
  • Enter passphrase if key is encrypted
  • Verify your public key is on the server

"Port already in use"

  • Choose a different local port (e.g., 5433 instead of 5432)
  • Or close the application using that port

More Help

See Troubleshooting for detailed solutions.

Enable Menu Bar (Optional)

For quick access without opening the main window:

  1. Go to Settings → General
  2. Enable Show in Menu Bar
  3. Click the StormTunnel icon in your menu bar to connect/disconnect tunnels

Next Steps