Architecture
flowchart LR
src["hosts.toml<br>or flake"] --> sw[sshwarm]
sw -- "ssh, every --refresh:<br>probe.sh on stdin" --> m["each machine"]
m -- "### sections:<br>OS, usage, units, stacks" --> sw
sw --> ui["browser,<br>or status"]
ui -. "logs, describe,<br>shell, actions" .-> m
- sshwarm reads the machines from a hosts file or a flake.
- It pipes
probe.shto every machine over ssh, in parallel, and waits for all. The browser does it again--refreshafter the last round ended. - The probe only reads: OS, uptime, usage, pending reboot,
systemctl showof every service,docker psanddocker inspectof compose containers. It prints### <name>sections; a command that fails prints### error <name>. - sshwarm parses each machine’s output into a report, and rates what’s in it: idle,
fine, warning or broken. A machine’s problems are what’s broken, what restarted on
its own in the last 10 minutes, a disk 90% full, and the probe’s errors.
statusexits 1 on any. - Logs, descriptions, shells and actions each run their own ssh command, on demand.
In time
A refresh, a unit’s logs, then a container’s restart:
sequenceDiagram
actor You
participant UI as browser
participant SW as swarm
participant M as each machine
loop every --refresh, from the end of the last round
UI->>SW: probe
SW->>M: ssh: bash, probe.sh on stdin, to all at once
M-->>SW: OS, usage, units, containers, in sections
SW-->>UI: a report per machine, rated
end
You->>UI: l, on a unit
UI->>M: ssh: journalctl -u unit -n 300
M-->>UI: its last lines
Note over UI,M: s follows them: journalctl -f, with a terminal
You->>UI: R, on a container
UI-->>You: restart container web-1 on app-1? y/N
You->>UI: y
UI->>M: ssh: docker restart web-1
UI->>SW: probe again
Code
main.go | flags, commands |
internal/inventory | hosts file, flake |
internal/remote | ssh: to the end, as a stream, or with the terminal; shared connections |
internal/swarm | the probe and its parsing, the report, the commands for logs, descriptions and actions |
internal/ui | the browser: screens, tables, cards, keys; status’s table and JSON |
Choices
- Agentless. A bash script over the user’s own ssh: nothing to install, and their ssh config, keys and agent just work.
- Read-only probe. Actions ask first, and
--read-onlyturns them off. - The machine’s clock. Ages are computed with the machine’s time, not yours.
- Bounded waits. The probe stops itself on the machine before sshwarm gives up
on it, and gives
df2 s, as a hung mount would hang it.