Running commands
Declared commands across one server or the whole fleet, without a shell.
A command is a named, declared operation an agent will perform. It is not a shell.
Why declared commands
| Terminal | Declared command | |
|---|---|---|
| Needs profile | full | operate |
| Reviewable before it runs | ✗ | ✓ |
| Repeatable identically | ✗ | ✓ |
| Across many servers | ✗ | ✓ |
| In the audit log as one thing | ✗ | ✓ |
Anything you do more than twice should be a command.
Declaring one
Fleet → Commands & checks. A command has a name, what it runs, the identity it runs as, and which servers it is available on.
Commands are on an allow-list. A guarded raw mode exists for cases the allow-list cannot express; it is separately permitted and separately audited.
Running across the fleet
Fleet → Run a command. Choose the command, choose the servers — by tag, environment or individually — and run.
Results come back per server: exit code, output, duration. A partial failure is shown as a partial failure, with the servers that failed named.
Read the target list before you press run. "All production" is a selection that is very easy to make and very hard to undo.
Checks
A check is a command whose output is interpreted — a health probe rather than an action. Checks run on a schedule and their results feed rules.
Actions from rules
A rule can run a command in response to a condition — restart a unit, clear a cache. Three guardrails apply, and the give-up condition is checked first:
- Give up after N attempts. Checked before anything else, so a loop cannot outrun its own limit.
- Cooldown between attempts.
- Capped by profile.
observeruns nothing.
Auto-remediation that retries forever turns one failing unit into a restart loop that looks like flapping and hides the real cause. The give-up counter is the most important of the three.
Audit
Every execution is audited: who, what, where, as whom, exit code, when. See Audit log.
Where this behaviour lives: frontend/src/app/agents/fleet/, frontend/src/app/agents/commands/. If the code and this page disagree, the code is right — please fix the page.
Part of Fleet — The agent on each server: what it collects and what it may be asked to do.