Reticle/ Docs Get Desktop
Documentation/Connect and operate
On this page

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.

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 for field definitions and troubleshooting for unavailable checks or actions.

View Markdown Report a docs issue
Reticle documentationDraw intentionally. Operate with context.

↑ ↓ to move · Enter to open · Esc to close