Getting Started¶
Get up and running in about 5 minutes.
Install StormTunnel¶
- Download from the App Store or official website
- Drag to your Applications folder
- Launch StormTunnel
- Complete onboarding — import SSH keys (optional) and review privacy info
First Launch
StormTunnel will ask to access your Keychain and network. Both 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 — Standard SSH port forwarding
- 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 | user@server.com | 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 — Stored in Keychain
Step 5: Save and Connect¶
- Click Save
- Click the play button next to your tunnel
- Wait for the status to turn green
Use Your Tunnel¶
Once connected, the remote service is available at localhost:[local port].
Example: A PostgreSQL tunnel with local port 5432 — connect your database client to localhost:5432. The connection routes through SSH to the remote database.
Status Colors¶
| Color | Meaning |
|---|---|
| Green | Connected |
| Gray | Disconnected |
| Yellow | Connecting |
| Red | Error |
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:
- Go to Settings > General
- Enable Show in Menu Bar
- Click the StormTunnel icon in your menu bar to connect/disconnect tunnels