English | 简体中文

⚡ Run commands across all your servers in parallel — from a single, dependency-free CLI.

Install · Quick Start · Commands · Config

SSH Fleet is a lightweight Node.js CLI for managing and operating on a fleet of SSH hosts. Define your servers once in a YAML or JSON file, then execute shell commands across all (or a subset) of them in parallel, stream results, push or pull files, and get machine-readable JSON output for scripting.

• 🚀 Parallel execution with configurable concurrency
• 📜 Multi-line scripts sent directly from a local file
• 🏷️ Tag-based host selection (--hosts tag:prod)
• 📊 Multiple output formats — grouped, combined, JSON, silent
• 🔑 SSH key + password auth, agent forwarding support
• 📦 Zero runtime deps for the CLI itself — ships as a single bundled file
• 📝 YAML or JSON config — your fleet as code
• 🔄 File transfer — push/pull via SFTP
• ❤️ MIT licensed, TypeScript, thoroughly tested

npm install -g ssh-fleet

Or run ad-hoc with npx:

npx ssh-fleet exec 'uptime'

ssh-fleet init

This creates ssh-fleet.yml in the current directory:

defaultUser: root
defaultPort: 22
defaultPrivateKeyPath: /Users/you/.ssh/id_rsa

hosts:
  - name: web-1
    host: 192.168.1.10
    tags: [web, prod]
  - name: web-2
    host: 192.168.1.11
    tags: [web, prod]
  - name: db-1
    host: 192.168.1.20
    user: postgres
    tags: [db, prod]

ssh-fleet list

Fleet hosts: 3 host(s)
Config: /path/to/ssh-fleet.yml
Tags: db, prod, web

web-1  root@192.168.1.10:22  ✓  [web,prod]
web-2  root@192.168.1.11:22  ✓  [web,prod]
db-1   postgres@192.168.1.20:22  ✓  [db,prod]

ssh-fleet exec 'uptime'

 OK  web-1 192.168.1.10 45ms
 11:51:05 up 142 days, 21:36,  2 users,  load average: 0.08, 0.02, 0.01

 OK  web-2 192.168.1.11 42ms
 11:51:05 up 142 days, 21:36,  0 user,  load average: 0.06, 0.02, 0.00

Summary:  2 ok  2 hosts  87ms total

ssh-fleet status

 OK  web-1 192.168.1.10 1352ms
=== HOSTNAME ===
web-1
=== UPTIME ===
 11:51:05 up 142 days, 21:36,  2 users,  load average: 0.08, 0.02, 0.01
=== LOAD ===
0.08 0.02 0.01 1/377 964834

 OK  web-2 192.168.1.11 1320ms
=== HOSTNAME ===
web-2
=== UPTIME ===
 11:51:05 up 142 days, 21:36,  0 user,  load average: 0.06, 0.02, 0.00
=== LOAD ===
0.06 0.02 0.00 1/197 1452300

Summary:  2 ok  2 hosts  2672ms total

# By name
ssh-fleet exec 'df -h' --hosts web-1,web-2

# By tag
ssh-fleet exec 'sudo systemctl restart nginx' --hosts tag:web

# All hosts
ssh-fleet exec 'free -m' --hosts all

# Push a config file to all web servers
ssh-fleet copy push ./nginx.conf /etc/nginx/nginx.conf --hosts tag:web

# Pull logs from a single host (saved with .hostname suffix)
ssh-fleet copy pull /var/log/syslog ./syslog --hosts web-1

The Docker demo starts two disposable SSH hosts on your machine, so the complete workflow can be judged without cloud credentials or existing infrastructure.

For the automated walkthrough:

npm install
npm run judge

This builds the CLI, starts the hosts, waits for SSH, exercises commands, scripts, JSON output, targeting, SFTP push/pull, and then removes the containers.

npm install && npm run build
docker compose -f examples/docker-demo/compose.yml up -d --build
node dist/cli.js list --config examples/docker-demo/ssh-fleet.yml
node dist/cli.js exec 'hostname && uptime' --config examples/docker-demo/ssh-fleet.yml
node dist/cli.js run examples/docker-demo/health-check.sh --config examples/docker-demo/ssh-fleet.yml
docker compose -f examples/docker-demo/compose.yml down

Run a shell command on selected hosts.

# JSON output for piping into jq
ssh-fleet exec 'hostname' -o json | jq '.[] | select(.exitCode==0) | .name'

Run a local multi-line shell script on the selected hosts. The script does not need to be copied to the remote machines first and accepts the same execution flags as exec.

cat > deploy.sh <<'EOF'
set -e
cd /srv/my-app
git pull --ff-only
npm ci --omit=dev
sudo systemctl restart my-app
EOF

ssh-fleet run ./deploy.sh --hosts tag:web --concurrency 4 --fail-fast

List hosts in the fleet. Flags: --verbose, --json, --tags.

Create a starter config. Flags: --force, --json, --path <dir>.

Quick health check — runs hostname && uptime on every host.

SSH Fleet searches these locations (first match wins):

1. ./ssh-fleet.yml / .ssh-fleet.yml
2. ./ssh-fleet.yaml / .ssh-fleet.yaml
3. ./ssh-fleet.json / .ssh-fleet.json
4. Parent directories (up to home)
5. ~/.ssh-fleet.{yml,yaml,json}

defaultUser: root
defaultPort: 22
defaultPrivateKeyPath: ~/.ssh/id_rsa

Any host-level field overrides the default.

Managing 5, 50, or 500 servers shouldn't mean 500 terminal tabs. Tools like Ansible are powerful but heavy; SSH Fleet aims to be the fast, zero-config layer below that — the thing you reach for when you just need to run one command everywhere, right now.

• run command for multi-line scripts from a file
• Diff mode: show only hosts where output differs
• Interactive host picker (fzf-style)
• Docker image for CI pipelines
• Shell completions (bash, zsh, fish)
• top command for live resource monitoring

git clone https://github.com/flantofun/ssh-fleet
cd ssh-fleet
npm install
npm run dev -- list          # run via tsx
npm run build                # compile to dist/
node dist/cli.js exec 'uptime'

SSH Fleet was created from scratch through an AI-native vibe coding workflow with Codex using GPT-5.6. The builder supplied the product idea, requirements, iterative feedback, testing, and final decisions; Codex generated and refined the TypeScript implementation, tests, Docker judge environment, documentation, and submission assets. See CODEX_BUILD_LOG.md for the implementation record and verification evidence.

MIT © 2026 flantofun