Documents

ssh-tunnel-swarm

Try it

Bash tool that spins up and holds open MANY concurrent SSH tunnels, both forward (-L) and reverse (-R), driven by a plain-text rules file. One connection block per host: a header line `user@host:port=/path/to/private/key` followed by one or more tunnel lines `forward|reverse local-iface:local-port:remote-iface:remote-port`. Each host connection runs in its own background loop (`ssh -N -i <key> -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -o StrictHostKeyChecking=yes`) and retries every 5s after a failed exit; Ctrl-C stops every tunnel. Configured entirely via env vars (RULES_FILE, LOG_ENABLED, LOG_FILE, LOG_LEVEL), no CLI flags. No password auth, key-based only. Use when the user wants to set up/manage multiple SSH forward or reverse tunnels from a single rules file across one or many hosts.

What it does

Bash tool for running a swarm of SSH tunnels — forward and reverse, many hosts at once — off one rules file. No daemon, no config DSL beyond plain text, just / looped forever per host with auto-reconnect.

The skill document

ssh-tunnel-swarm

Bash tool for running a swarm of SSH tunnels — forward and reverse, many hosts at once — off one rules file. No daemon, no config DSL beyond plain text, just ssh -L/ssh -R looped forever per host with auto-reconnect.

Security & safety

  • This opens real SSH connections using your keys to hosts you list in the rules file — anything wrong in that file connects somewhere real.
  • Reverse tunnels (reverse) expose a LOCAL service to the REMOTE host. Only point reverse rules at hosts you trust — a compromised or malicious remote can now reach whatever you bound on your side.
  • Forward tunnels (forward) expose a REMOTE service through YOUR local machine. Same trust logic in reverse: don't forward into networks you don't control.
  • All connections force StrictHostKeyChecking=yes — the target host must already be in known_hosts or the connection fails. That's intentional; don't work around it by disabling host key checking.
  • No password auth support — private key only. Keep the key file permissions tight (chmod 600) and never put keys or the rules file (which references key paths) in a world-readable location or a git repo.
  • Every connection block runs forever in a retry loop (5s backoff) until you kill it — make sure that's actually what you want before pointing this at a host.

When to use

  • Standing up several forward and/or reverse SSH tunnels across one or many hosts from a single declarative file, instead of hand-rolling a pile of ssh -L/ssh -R commands or systemd units.
  • Tunnels need to survive disconnects — the tool loops and reconnects automatically.
  • Exposing a local dev service to a remote box (reverse), or reaching a remote-network-only service from your machine (forward).

When NOT to use

  • One-off, single tunnel for a few minutes — just run ssh -L/ssh -R directly.
  • Password-based SSH auth — this tool only supports private key auth.
  • You need a full VPN / mesh network (e.g. overlay networking, NAT traversal across many peers) — this is tunnels over plain SSH, not a VPN.

Config grammar (rules file)

Plain text file, default path rules.txt, overridable via RULES_FILE. It's a sequence of connection blocks, separated by blank lines. Each block:

  user@host:port=/path/to/private/ssh/key
 forward|reverse local-interface:local-port:remote-interface:remote-port
          ... (one or more tunnel lines)
  • Header line — exactly one per block, always first: user@hostname:port=/path/to/private/key
    • user — [a-zA-Z0-9._-]+
    • hostname — hostname or IPv4 (no scheme, no special chars)
    • port — SSH port on the remote host, 0-65535
    • =/path/to/key — path to the private key for THIS connection; must exist on disk or the tool refuses to start (FATAL at load time).
  • Tunnel lines — one or more per block, every line until the next blank line or EOF: direction local-interface:local-port:remote-interface:remote-port
    • direction is literally forward or reverse, nothing else.
    • all four of interface/port/interface/port are required, colon-separated, no spaces.
    • reverse → ssh -R remote-interface:remote-port:local-interface:local-port (binds on the REMOTE host, forwards back to your LOCAL interface:port).
    • forward → ssh -L local-interface:local-port:remote-interface:remote-port (binds on your LOCAL interface, forwards to something reachable FROM the remote host).
  • Blank line = end of the current block / start of the next. Multiple blocks = multiple independent SSH connections, each supervised in its own background loop.
  • One host can carry any number of forward and reverse tunnel lines mixed together.

Example ruleset (forward + reverse, two hosts)

# Host 1: expose a local web app on the VPS (reverse), and reach the VPS's
# internal Postgres from your machine (forward).
deploy@vps1.example.com:22=/home/user/.ssh/deploy_vps1
reverse 0.0.0.0:8080:localhost:3000
forward localhost:15432:127.0.0.1:5432

# Host 2: reach an internal-only admin panel through a jump host (forward),
# and expose your local dev API back to that jump host (reverse).
opsuser@jump.example.com:22=/home/user/.ssh/deploy_jump
forward localhost:9090:10.0.5.20:9090
reverse 127.0.0.1:4000:localhost:4000

With the above: curl http://vps1.example.com:8080 hits your local localhost:3000; psql -h localhost -p 15432 reaches the VPS's internal Postgres; curl http://localhost:9090 on your machine reaches 10.0.5.20:9090 through the jump host; and the jump host's localhost:4000 reaches your local dev API on 4000.

Running it

No subcommands, no CLI flags — everything is env vars, one invocation runs the swarm in the foreground until killed:

RULES_FILE=/path/to/rules.txt \
LOG_ENABLED=1 \
LOG_FILE=/path/to/log/file \
LOG_LEVEL=DEBUG \
ssh-tunnel-swarm

Ctrl-C (SIGINT) or SIGTERM kills every tunnel connection cleanly and exits.

Install/build details, the full env var reference, and log-level semantics are in references/setup.md.

Related skills

Stores durable facts in a categorized, plain-markdown vault on disk, alongside your agent's built-in memory.

by Iván561 installs18 stars

Join a video meeting as an AI bot with voice, avatar, and screenshare across four operating modes.

by johnpatternai22 installs8 stars

Generate and edit Draw.io, Mermaid, and Excalidraw diagrams from natural language using a structured JSON spec.

by nssa.io1.0k installs47 stars

Find why your productivity system keeps failing, then apply the smallest fix — capacity math, bottleneck routing, durable local notes.

by Iván857 installs69 stars

Run Git operations — commits, branches, merges, rebases, conflict resolution, and recovery — with safety rules enforced.

by Iván539 installs31 stars

More from psyb0t

Browse all skills

Drive a user-deployed mt5-httpapi MetaTrader 5 bridge over HTTP, with per-action confirmation on every real-money call.

by psyb0t108 installs4 stars

Docker-packaged browser automation for QA against anti-bot stacks and authorized detection testing.

by psyb0t138 installs2 stars

Self-hosted OpenAI-compatible speech service — transcription, translation, and synthesis from one container.

by psyb0t13 installs

Run ffmpeg, sox, and ImageMagick jobs against your files in a fixed-allowlist SSH sandbox.

by psyb0t71 installs

Generate speech audio via Qwen3-TTS over SSH with preset voices, voice cloning, and voice design.

by psyb0t55 installs

Drive one or more IMAP/SMTP mailboxes through a single REST + MCP endpoint — read, search, send, mark-seen, and delete across accounts in parallel.

by psyb0t15 installs