# Checks and named actions

A **check** collects an observation. A **named action** runs a persisted command
when an operator requests it. Both belong to a node, but adding endpoint details
alone does not create either one.

## Where work runs

Desktop runs collectors from your computer. Team runs them from the daemon
host, using that host's tools, credentials, network access, and OS account.
Local shell means the Reticle host, not the machine drawn on the node.

HTTP checks require system `curl`; a jq predicate also requires `jq`. Remote
checks require `ssh` and non-interactive authentication. See
[installation](installation.md#tools-for-live-checks).

## Add a fixed check

Open a node's Inspector and use **Checks → + add**:

| Choice | What it does | Configure |
|---|---|---|
| HTTP | GET a URL and evaluate its status; optionally evaluate JSON with `jq -e` | URL, status, optional jq predicate |
| SSH uptime | Run `uptime` on the SSH target | Node host, SSH port, user |
| SSH service | Run `systemctl is-active -- UNIT` | SSH target and systemd service name |

Save endpoint changes with **Save details**, then save the check with **Save
operations**. Fixed checks do not require privileged mode. Use **Check** for
fresh evidence or the toolbar refresh for the map. The node's Check button
requests a whole-graph collection, not an isolated single probe.

HTTP follows redirects and accepts 2xx by default. Status can be `200`, `2xx`,
`200-204`, or a comma-separated list. In YAML, quote an exact numeric status:
`status: "200"`. A successful jq predicate must pass `jq -e`, not merely produce
valid JSON.

## Read health and freshness

- `ok`: a check succeeded.
- `err`: a check failed. Inspect its detail for the cause.
- `unknown`: there is no health signal for that node.
- `warn`: supported by the graph and display; current built-in checks produce
  `ok` or `err`, not a separate warning threshold.

A node shows its worst signal. Groups roll up their own and descendant health
in the UI: error takes priority over warning, OK, and unknown. That rollup does
not create a synthetic graph signal.

The Desktop window requests a graph on startup and every 30 seconds. Team has
one background collector on a 30-second schedule and recollects after config
changes. Slow checks can delay results; observation timestamps matter more than
the nominal interval. Team viewers read the cache and cannot force a refresh.

## Enable custom commands

Use **Secure shell** for a remote `ssh.command` check, or **Local shell** for a
Unix `shell.command` check. These commands can change systems; their purpose as
a check does not make them read-only.

- **Desktop:** choose **Enable privileged mode** in the bottom status bar and
  confirm trust for all persisted commands in that workspace for this app
  session. Enabled checks may run immediately and on subsequent refreshes.
- **Team:** the operator starts the daemon with `--allow-custom-commands`.
  Editors can then manage definitions. Filesystem writers can also change the
  YAML directly.

New custom checks in the UI start with **Enabled** and **Publish bounded output
to viewers** selected. In handwritten YAML, omitted `enabled` means **false for
custom checks** and **true for fixed checks**; omitted `publishOutput` means
**false**. Set both explicitly when writing custom YAML.

Commands are limited to 2,048 bytes. Timeouts range from 1 to 120 seconds
(default 10 for checks). Local commands run in non-interactive Bash with
`pipefail`; SSH commands use the remote login shell, so local Bash pipeline
semantics should not be assumed remotely.

Command definitions are omitted from graph responses. If output publishing is
enabled, bounded output is part of the signal and is visible to viewers, API/MCP
clients, and optional chat. Output is not automatically scrubbed for secrets.
With output publishing off, the signal reports the exit code instead.

## Define and run a named action

With command policy enabled, use **Named actions → + add** in the Inspector.
Choose **Secure shell** or **Local shell**, enter a name and command, then choose
**Save operations**.

Actions have a default 20-second timeout and require approval by default. You
can reference a collector ID in **Requires signal**, with an expected state.
When the state is omitted, the expected state is `err`. The referenced check is
collected again before execution; an unsatisfied precondition refuses the action.

Select the action's **Run** control and confirm approval if requested. Team also
checks the reviewed configuration revision. If the config changed, refresh and
review the action again. Callers submit an action ID and approval, never
one-off command text.

Reticle does not run actions automatically on a failed check. An action timeout
bounds the wait and output capture; a deliberately detached workload may outlive
the command session. Use restricted SSH accounts and OS-side supervision where
you need stronger execution guarantees.

## Change or remove definitions

Use **Edit** or **Remove** beside a check/action. Removing a check also removes
actions that require its signal, after confirmation. Operational edits are not
part of visual undo history. Keep a YAML backup or Git revision.

See [the YAML reference](topology-reference.md) for field definitions and
[troubleshooting](troubleshooting.md) for unavailable checks or actions.
