Skip to content

Common Workflows

Database Tunnels

Create a tunnel to forward a remote database port to localhost, then connect with your preferred client.

PostgreSQL

Setting Value
Tunnel Name dev-postgres
Local Port 5432
Remote Host localhost
Remote Port 5432

Connect once the status turns green:

psql -h localhost -p 5432 -U youruser -d yourdb

In TablePlus or pgAdmin, point at localhost:5432 with your database credentials.

MySQL

Setting Value
Tunnel Name dev-mysql
Local Port 3306
Remote Host localhost
Remote Port 3306 
mysql -h 127.0.0.1 -P 3306 -u youruser -p

Redis

Setting Value
Tunnel Name dev-redis
Local Port 6379
Remote Host localhost
Remote Port 6379 
redis-cli -h localhost -p 6379

Web Service Tunnels

Forward an internal web service to a local port, then open it in your browser.

Example: An admin dashboard at admin.internal:3000 only reachable from the server network.

Setting Value
Tunnel Name internal-admin
Local Port 3000
Remote Host admin.internal
Remote Port 3000

After connecting, open http://localhost:3000.

Multiple Tunnels

When your stack needs several services at once, create a separate tunnel for each and use distinct local ports.

Tunnel Local Port Remote Service
dev-postgres 5432 PostgreSQL
dev-redis 6379 Redis
dev-api 8080 Backend API

A naming convention like [environment]-[service] keeps things searchable:

dev-postgres
staging-postgres
prod-postgres

Port Conflicts

Only one tunnel can bind a given local port. Disconnect the active tunnel before connecting another on the same port.

Switching Environments

If your dev, staging, and production tunnels share the same local port (e.g., 5432), disconnect one before connecting the next. StormTunnel will refuse to bind a port that is already in use.

To avoid the disconnect-reconnect cycle, assign different local ports per environment:

Tunnel Local Port
dev-postgres 5432
staging-postgres 5433
prod-postgres 5434

Update your application's connection string to match.

Importing SSH Config

Import existing tunnels from your ~/.ssh/config instead of recreating them by hand.

  1. Go to File > Import.
  2. Select your SSH config file.
  3. Review the parsed tunnels and adjust names or ports.
  4. Click Import.

StormTunnel reads Host, HostName, Port, User, IdentityFile, and LocalForward directives. Entries without LocalForward are imported as SSH hosts you can attach tunnels to later.

Exporting and Sharing Configurations

File > Export saves tunnel definitions to a portable file. Passwords and private keys are never included -- only references to key paths.

Recipients import the file and supply their own credentials.

AWS Session Manager Tunnels

Prerequisites: AWS CLI with the Session Manager plugin installed, credentials configured, and IAM permissions for ssm:StartSession.

  1. Create a new tunnel and select AWS Session Manager as the connection type.
  2. Enter the Instance ID (e.g., i-0123456789abcdef0).
  3. Select your AWS Profile.
  4. Set local and remote ports.
  5. Connect.

If connections fail, verify your profile under Settings > AWS and click Test Connection.