ssh-fleet-commander

v1.0.0 MIT devops updated 2026-09-26

Run commands across many servers at once over SSH — define hosts once in a YAML inventory, then exec in parallel and copy files. No agent software needed.

$ skillbank install ssh-fleet-commander@1.0.0
# pins exactly 1.0.0 · README + changelog included

Overview

You have 3, 10, 50 servers and no desire to install a control plane on any of them. SSH Fleet Commander reads a small YAML inventory and runs commands across matching hosts in parallel over plain SSH. No daemon, no inbound ports, no dependencies beyond Python and the ssh/scp binaries you already have.

Installation

  1. Copy the ssh-fleet-commander/ directory anywhere convenient.
  2. Make the script executable (Unix):

``bash chmod +x scripts/fleet.py ``

  1. Create your inventory at ~/.fleet/hosts.yaml (see Configuration).

No pip install needed — standard library only.

Configuration

Inventory file: ~/.fleet/hosts.yaml (override with --inventory <path>).

hosts:
  web1:
    host: 203.0.113.10
    user: deploy
    key: ~/.ssh/id_ed25519
  web2:
    host: 203.0.113.11
    user: deploy
    key: ~/.ssh/id_ed25519
  db-primary:
    host: db.internal.example.com
    user: admin
    port: 2222
    proxy: "ssh -W %h:%p bastion.example.com"   # optional ProxyCommand
FieldRequiredDescription
hostyesHostname or IP.
usernoSSH user (default: current user).
keynoIdentity file (default: ssh-agent / default keys).
portnoSSH port (default: 22).
proxynoFull ProxyCommand string for jump-host setups.

The parser understands exactly this schema (nested maps, scalar values) — keep the file to documented fields. Keys are referenced by path, never embedded; nothing is uploaded anywhere.

Inputs

CommandArgumentsReturns
list—Host aliases with host/user/port.
exec<pattern> "<command>" [--timeout SECS]Per-host stdout/stderr + exit code.
cp<pattern> <local-path> <remote-path>Per-host copy result.

<pattern> is a glob over host aliases (web*, db-primary, *). exec runs hosts in parallel threads and prints results grouped by host, with a summary line (3 ok, 1 failed). Default timeout 60s per host.

Worked example

$ ./scripts/fleet.py list
web1         deploy@203.0.113.10:22
web2         deploy@203.0.113.11:22
db-primary   admin@db.internal.example.com:2222

$ ./scripts/fleet.py exec 'web*' 'uptime'
[web1] exit=0 (0.8s)
 12:01:11 up 45 days,  3:12,  1 user,  load average: 0.12, 0.08, 0.05
[web2] exit=0 (0.9s)
 12:01:12 up 45 days,  3:10,  1 user,  load average: 0.31, 0.22, 0.18
summary: 2 ok, 0 failed

$ ./scripts/fleet.py cp 'web*' ./app.tar.gz /opt/app/app.tar.gz
[web1] copied ./app.tar.gz -> /opt/app/app.tar.gz
[web2] copied ./app.tar.gz -> /opt/app/app.tar.gz
summary: 2 ok, 0 failed

Safety notes

exec runs whatever you give it, on every matched host, with your SSH privileges — a bad glob (*) plus rm -rf is exactly as dangerous as it sounds. The tool always prints the matched host list before executing so you can abort (Ctrl-C) if the pattern is wider than intended. Prefer read-only commands for discovery; test destructive ones against one host first.

Version history

  1. v1.0.02026-09-26
    • Initial public release.
    • Commands: list, exec <pattern> "<command>" (parallel, per-host results + summary), cp <pattern> <local> <remote>.
    • Glob target patterns, per-host user/key/port/ProxyCommand, configurable timeouts.
    • Zero dependencies; tested live against real servers over SSH.

← back to catalog