SSH Tunnel Manager

You are managing SSH tunnels using the ssh-tunnels CLI tool backed by a declarative JSON config at ~/.ssh-tunnels/config.json.

Step 1: Ensure the tool is installed

Before doing anything, check if the CLI is available:

which ssh-tunnels 2>/dev/null && echo "installed"

If NOT installed, run:

npm install -g @statechange/ssh-tunnel-manager

This single command installs the CLI, creates ~/.ssh-tunnels/ directories, sets up a macOS LaunchAgent for the menu bar app, and starts it automatically.

After installation, verify:

ssh-tunnels status

Step 2: Manage tunnels

Check current tunnels

ssh-tunnels status

Add a new tunnel

ssh-tunnels add \
  --name "Descriptive Name" \
  --host <ssh-host> \
  --user <ssh-user> \
  --localPort <local-port> \
  --remoteHost <remote-host> \
  --remotePort <remote-port> \
  --enabled

Enable / disable / remove

ssh-tunnels enable <tunnel-id>
ssh-tunnels disable <tunnel-id>
ssh-tunnels remove <tunnel-id>

Sync all tunnels to match config

ssh-tunnels sync

Use --json for programmatic output

ssh-tunnels status --json
ssh-tunnels enable <id> --json

Critical knowledge

The --user flag is the #1 source of errors

The SSH username defaults to the local OS user. Most servers require root or a specific service account. If you see "Permission denied (publickey)" in the logs, change the user first.

The --remoteHost is relative to the SSH server

When the service runs directly on the SSH host, use --remoteHost localhost. When the service is on a different machine accessible from the SSH host, use that machine's internal hostname or IP.

Common ports

Tunnel IDs

The ID is auto-generated from the name by slugifying it (lowercase, hyphens). For example, "Production Postgres" becomes production-postgres. Always use the ID (not the name) for enable/disable/remove/logs commands.

After adding an enabled tunnel, verify it started

Always check status or logs after enabling a tunnel. The enable and add --enabled commands will automatically verify and report issues, but with --json output you should check the healthy field:

ssh-tunnels enable my-tunnel --json
# Look for: "healthy": true

If unhealthy, check logs:

ssh-tunnels logs my-tunnel

Menu bar app

The Electron menu bar app provides a GUI for the same functionality:

• Tray icon: green (all OK), yellow (partially running), red (failures)
• Click to see tunnel list with toggle switches
• "Add Tunnel..." opens a form
• "Sync Now" forces immediate reconciliation
• Auto-syncs every 30 seconds for crash recovery

The app reads/writes the same ~/.ssh-tunnels/config.json as the CLI. Changes from either the CLI or the app are reflected in both.

The menu bar app is automatically set up as a macOS LaunchAgent during installation. To manually start it:

cd $(npm root -g)/@statechange/ssh-tunnel-manager && npx electron dist/app.mjs