ssh-tunnel-swarm

ssh-tunnel-swarm is a Bash script that keeps a set of SSH tunnels open. You list hosts and tunnels in a plain-text rules file; it checks every line, starts one ssh -N per host with all of that host’s -L and -R flags, and starts it again 5 seconds after it fails.

rules.txt ── load_rules (validate every line)
               │
               ├─ user@vps1:22  ── ssh -N -R ... -L ... ── retry every 5s
               ├─ user@vps2:22  ── ssh -N -R ...        ── retry every 5s
               └─ ...

It is one file with no daemon, no flags and no config format beyond the rules file. Four environment variables cover the rest. It needs bash and ssh, and it only does key authentication.

Quick start

1. Download the latest release into the current directory (needs jq and wget):

   wget -qO- https://raw.githubusercontent.com/psyb0t/ssh-tunnel-swarm/master/tools/downloader.sh | bash
   

2. Write rules.txt. This makes a web app on port 3000 of your machine reachable on port 8080 of a VPS:

   user@myvps.com:22=/home/user/.ssh/id_ed25519
   reverse localhost:3000:0.0.0.0:8080
   

3. Make sure the VPS host key is already in ~/.ssh/known_hosts (connect once with plain ssh user@myvps.com), then run it:

   ./ssh-tunnel-swarm
   

The remote side only listens on 0.0.0.0 if the server’s GatewayPorts setting allows it. Rules file has the details, and Installation puts the script on your PATH.

Where to go next

Page	What is in it
Installation	The downloader, putting the script on PATH, building from source, upgrading and removing it
Rules file	Header and tunnel line syntax, what forward and reverse turn into, validation rules and examples
Configuration	RULES_FILE, LOG_ENABLED, LOG_FILE, LOG_LEVEL, log levels and the log line format
Running the swarm	The exact ssh command, the retry loop, stopping it, and running it under systemd
Security	Host key checking, key files, what forward and reverse expose, what the logs contain
Troubleshooting	Every startup error message, connection errors, and what to do about them
Agent integrations	The agent skill for Claude Code, Codex and OpenClaw
Development	Source layout, Make targets, tests, the build step and the release pipeline