Common Workflows¶

Practical step-by-step guides for everyday StormTunnel tasks.

Daily Database Access¶

The most common workflow - connecting to a remote database for development work.

Quick Steps¶

1. Open StormTunnel from your Applications or menu bar
2. Find your database tunnel in the list (e.g., "dev-postgres")
3. Click Connect (or press Space with the tunnel selected)
4. Wait for green status - tunnel is now active
5. Connect your app to localhost on the local port (e.g., localhost:5432)

Example: PostgreSQL Database¶

You need to access a PostgreSQL database on a remote server for local development.

Once connected, use any database client:

• TablePlus: Connect to localhost:5432
• pgAdmin: Server → localhost, Port → 5432
• Command line: psql -h localhost -p 5432 -U youruser

Accessing Internal Web Services¶

Connect to internal APIs, admin panels, or web applications behind a firewall.

Quick Steps¶

1. Create tunnel with local port matching the service (e.g., 8080 for web)
2. Connect the tunnel
3. Open browser to http://localhost:8080

Example: Internal Admin Panel¶

Your company has an admin dashboard at admin.internal:3000 that's only accessible from the server network.

After connecting, open http://localhost:3000 in your browser.

Working with Multiple Services¶

When you need several connections at once - database, cache, and API.

Quick Steps¶

1. Create separate tunnels for each service
2. Use different local ports to avoid conflicts
3. Connect all needed tunnels before starting work
4. Disconnect when done to free up ports

Example: Full Development Stack¶

Tip: Use consistent naming like dev-postgres, staging-postgres, prod-postgres to quickly find what you need.

Quick Connect from Menu Bar¶

The fastest way to manage tunnels without opening the main window.

Quick Steps¶

1. Click the StormTunnel icon in your menu bar
2. See all tunnels with their current status
3. Click the play button next to any tunnel to connect
4. Click stop to disconnect

Menu Bar Benefits¶

• Always visible - no need to find the app window
• Status at a glance - see which tunnels are active
• One-click connect - fastest way to start a tunnel
• Keyboard shortcut - click icon or use global shortcut

If you don't see the menu bar icon, go to Settings → General and enable Show in Menu Bar.

Switching Between Environments¶

Moving from development to staging to production throughout the day.

Quick Steps¶

1. Disconnect current environment tunnel
2. Connect the new environment tunnel
3. Verify your app connects to the right environment

Example: Dev → Staging → Production¶

Morning (Development):

• Connect dev-postgres (port 5432)
• Work on new features

Afternoon (Staging):

• Disconnect dev-postgres
• Connect staging-postgres (port 5432)
• Test your changes

Production Check:

• Disconnect staging-postgres
• Connect prod-postgres (port 5432)
• Verify deployment

Only one tunnel can use a port at a time. Disconnect the current tunnel before connecting another that uses the same local port.

Handling Connection Issues¶

What to do when a tunnel won't connect or keeps disconnecting.

Quick Checks¶

1. Check your network - Are you connected to the internet?
2. Check VPN - Some servers require VPN access first
3. Check the error message - Click the tunnel to see details
4. Try reconnecting - Sometimes a simple retry works

Common Solutions¶

Auto-Reconnect¶

Enable automatic reconnection for important tunnels:

1. Edit tunnel (right-click → Edit)
2. Enable Auto-Reconnect in the connection settings
3. StormTunnel will automatically retry if disconnected

Connection Retry and Reliability¶

StormTunnel provides two mechanisms for handling connection failures - each serves a different purpose.

Understanding Retry vs Reconnect¶

• Retry: Automatically tries to connect again when initial connection fails
• Reconnect: Automatically re-establishes a connection that was previously working but dropped

Auto-Retry (Premium Feature)¶

When enabled, StormTunnel automatically retries failed initial connection attempts.

How It Works¶

1. You click Connect on a tunnel
2. If connection fails, StormTunnel waits with exponential backoff
3. Retry attempt 1: Wait ~1 second
4. Retry attempt 2: Wait ~2 seconds
5. Retry attempt 3: Wait ~4 seconds
6. Continue until max retry attempts reached or connection succeeds
7. Each retry is tracked in Connection History

Enabling Auto-Retry¶

1. Edit tunnel (right-click → Edit)
2. Go to Advanced settings
3. Enable "Auto-Retry"
4. Set "Max Retry Attempts" (default: 3, range: 1-10)

Auto-Retry requires a Premium license. Free tier users must retry manually.

When to Use Auto-Retry¶

Enable retry for tunnels that:

Retry vs Reconnect¶

Best Practices¶

Do enable retry for:

• Production database tunnels (server might be restarting)
• Cross-region AWS tunnels (higher latency)
• Remote development servers (unstable networks)

Do NOT enable retry for:

• Localhost tunnels (should connect instantly)
• Frequently changed credentials (retry will fail repeatedly)
• Known bad configurations (fix the issue instead)

Viewing Retry Attempts¶

Check your connection history to see retry activity:

1. Open Connection History (View → Connection History)
2. Click on a tunnel
3. Look for error events with retry attempt count
4. Compare error timestamps to see retry spacing

Troubleshooting Retry Issues¶

Retry is designed for transient failures. If a tunnel consistently fails after max retries, investigate the root cause rather than increasing retry count.

Backing Up Your Tunnels¶

Save your tunnel configurations before updating or switching computers.

Export Tunnels¶

1. Go to File → Export
2. Choose which tunnels to export (all or selected)
3. Save the file somewhere safe
4. Optional: Enable encryption for sensitive configurations

Import Tunnels¶

1. Go to File → Import
2. Select your backup file
3. Review the tunnels to import
4. Click Import

Export your tunnels monthly or before major changes. Store backups in a secure location.

Sharing Tunnel Configurations¶

Share tunnel setups with colleagues (without sharing credentials).

What Gets Shared¶

When you export a tunnel:

• ✅ Tunnel name and settings
• ✅ Host, ports, and connection type
• ❌ Passwords (never exported)
• ❌ Private SSH keys (only references)

How to Share¶

1. Export the tunnel configuration
2. Send the file to your colleague (email, Slack, etc.)
3. They import the file into their StormTunnel
4. They configure their own credentials (SSH key or AWS profile)

Using AWS Session Manager Tunnels¶

Connect to EC2 instances without SSH keys using AWS Session Manager.

Prerequisites¶

• AWS CLI installed with Session Manager plugin
• AWS credentials configured (profile or SSO)
• Proper IAM permissions for Session Manager

Quick Steps¶

1. Create new tunnel → Select AWS Session Manager
2. Enter Instance ID (e.g., i-0123456789abcdef0)
3. Select AWS Profile from your configured profiles
4. Set ports - local and remote
5. Connect

Verify AWS Setup¶

If AWS tunnels aren't working:

1. Go to Settings → AWS
2. Check your AWS Profile is selected
3. Click Test Connection to verify credentials
4. See AWS Settings for detailed configuration

Keyboard Shortcuts for Speed¶

Work faster with keyboard shortcuts.

Essential Shortcuts¶

Navigation¶

See Keyboard Shortcuts for the complete list.

Quick Reference¶

Tunnel Status Colors¶

Recommended Port Ranges¶

Organize your tunnels with consistent port assignments:

Naming Convention¶

Use descriptive names that are easy to search:

[environment]-[service]

Examples:
dev-postgres
staging-api
prod-redis

Next Steps¶

• Creating Tunnels - Detailed tunnel configuration options
• Main Window Overview - Learn the full interface
• Team Workflows - Sharing and collaboration
• Troubleshooting - Solve common problems