Creating Tunnels¶

Set up SSH and AWS Session Manager tunnels to securely access remote services.

Create a New Tunnel¶

Click + in the toolbar (or press Cmd+N)
Choose SSH Tunnel or AWS Session Manager
Fill in the configuration
Click Save

SSH Tunnel Configuration¶

Required Fields¶

Field	Description	Example
Name	Descriptive name	`dev-postgres`
SSH Host	Server to connect through	`[email protected]`
Local Port	Port on your Mac	`5432`
Remote Host	Destination service	`localhost`
Remote Port	Port on remote host	`5432`

SSH Host Formats¶

You can specify the SSH connection as:

[email protected]      # Direct connection
[email protected]     # IP address
my-server              # SSH config alias

SSH Config Aliases

If you have servers defined in ~/.ssh/config, just enter the alias name. StormTunnel reads the hostname, user, port, and key automatically.

Authentication¶

Choose one:

SSH Key (recommended) - Select from your imported keys
Password - Enter SSH password (stored in Keychain)

See Authentication for details.

AWS Session Manager Tunnel¶

For EC2 instances using AWS Session Manager instead of SSH.

Required Fields¶

Field	Description	Example
Name	Descriptive name	`aws-prod-db`
Instance ID	EC2 instance ID	`i-0123456789abcdef0`
Region	AWS region	`us-east-1`
Local Port	Port on your Mac	`5432`
Remote Host	Destination service	`mydb.rds.amazonaws.com`
Remote Port	Port on remote	`5432`

AWS Profile¶

Select your AWS profile in Settings → AWS or per-tunnel in the configuration.

Port Forwarding Examples¶

Database (PostgreSQL)¶

Access a database on the SSH server:

Field	Value
Local Port	`5432`
Remote Host	`localhost`
Remote Port	`5432`

Connect your database client to localhost:5432.

Web Server¶

Access a web app running on port 80:

Field	Value
Local Port	`8080`
Remote Host	`localhost`
Remote Port	`80`

Open http://localhost:8080 in your browser.

Internal Service¶

Access a service on the internal network:

Field	Value
Local Port	`6379`
Remote Host	`redis.internal`
Remote Port	`6379`

Connect to localhost:6379 to reach redis.internal:6379.

Common Service Ports¶

Service	Port
PostgreSQL	5432
MySQL	3306
Redis	6379
MongoDB	27017
HTTP	80
HTTPS	443
Elasticsearch	9200

Naming Conventions¶

Use clear, consistent names:

✅ Good:
dev-postgres
staging-api
prod-redis

❌ Avoid:
tunnel1
database
test

Recommended format: [environment]-[service]

Duplicate a Tunnel¶

Create a similar tunnel quickly:

Select the tunnel
Press Cmd+D (or right-click → Duplicate)
Edit the copy
Save

Useful for creating tunnels for different environments.

Advanced Options¶

Auto-Reconnect¶

Automatically reconnect if the tunnel disconnects:

Edit the tunnel
Enable Auto-Reconnect in Advanced settings
Save

Connection Timeout¶

Adjust how long to wait for connections:

Settings → General → Connection Timeout (global)
Or per-tunnel in Advanced settings

Verbose Logging¶

Enable detailed SSH output for troubleshooting:

Edit tunnel → Advanced → Enable Verbose Output
Connect the tunnel
Check Console.app for detailed logs

Troubleshooting¶

"Port already in use"¶

Another application is using that port.

Solutions:

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

"Host not found"¶

The hostname can't be resolved.

Solutions:

Check spelling of hostname
Try using IP address instead
Verify DNS is working

"Connection timeout"¶

Can't reach the server.

Solutions:

Check network connection
Verify server is accessible
Increase timeout in settings

Next Steps¶

Managing Tunnels - Connect and monitor tunnels
Authentication - Set up SSH keys
Settings - Configure defaults