Getting Started¶
Get up and running with a private AWS RDS tunnel in about 5 minutes.
Install StormTunnel¶
- Download from the official website
- Drag to your Applications folder
- Launch StormTunnel
- Complete onboarding — review privacy info and import SSH keys only if you need SSH tunnels
First Launch
StormTunnel will ask to access your Keychain and network. Keychain is used for credentials and local configuration; network access is required to create tunnels.
Create Your First AWS RDS Tunnel¶
Step 1: Open New Tunnel Dialog¶
Click the + button in the toolbar, or press Cmd+N.
Step 2: Choose Tunnel Type¶
- AWS Session Manager — Recommended for private AWS RDS and internal services
- SSH Tunnel — For existing bastions and self-managed servers
Step 3: Configure the Tunnel¶
For a private RDS database, select AWS Session Manager and fill in:
| Field | Example | Description |
|---|---|---|
| Name | prod-postgres | A clear name for the database or environment |
| AWS Profile | production | Your configured AWS CLI or SSO profile |
| AWS Region | us-east-1 | Region containing the SSM-managed EC2 instance |
| EC2 Instance ID | i-0abc123def456 | Instance that can reach the private RDS endpoint |
| Local Port | 5432 | Port on your Mac |
| Remote Host | mydb.abc123xyz.us-east-1.rds.amazonaws.com | RDS endpoint |
| Remote Port | 5432 | Database port |
Step 4: Confirm AWS Access¶
Make sure your Mac has:
- AWS CLI installed
- Session Manager plugin installed
- A valid AWS profile or SSO session
- IAM permission to start Session Manager sessions
See AWS Configuration for the infrastructure setup.
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 TablePlus, DBeaver, pgAdmin, or psql to localhost:5432. The connection routes through AWS Session Manager to the private RDS endpoint.
Status Colors¶
| Color | Meaning |
|---|---|
| Green | Connected |
| Gray | Disconnected |
| Yellow | Connecting |
| Red | Error |
Common Issues¶
"Connection refused"¶
- Check that the RDS endpoint and port are correct
- Verify the EC2 instance can reach the RDS security group
- Confirm the local port is not already in use
"Access denied" or "Session Manager failed"¶
- Confirm your AWS profile or SSO session is active
- Verify IAM permissions for Session Manager
- Check that the EC2 instance is registered with Systems Manager
"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 AWS RDS Connections and 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