# node-healthcheck Public Source Note - 2026-09-06

This source note supports the Greyforge Chronicle "node-healthcheck: One Script, Three Exit Codes."

Chronicle URL: https://greyforge.tech/chronicles/node-healthcheck-single-script-host-health

OpenForge URL: https://greyforge.tech/open-source

GitHub repository: https://github.com/GreyforgeLabs/node-healthcheck

GitHub release: https://github.com/GreyforgeLabs/node-healthcheck/releases/tag/v1.0.0

## Public Claims

- `node-healthcheck` is a single bash script requiring bash 4 or newer, coreutils, and awk. Each check probes with the standard tool for the job and reports `skip` when that tool is absent.
- It runs eighteen checks: system, load, memory, swap, disk, inodes, network, gateway, dns, services, user_services, ports, peers, failed_units, time_sync, reboot_required, sessions, and zombies.
- Exit codes are 0 healthy, 1 warning, 2 critical, 3 usage or runtime error.
- `--json` emits one document with per-check status, summary, and numeric metrics, generated without `jq`.
- `--config` files are `key=value` and are parsed line by line; they are never sourced.
- `--host` streams the script over SSH standard input and aggregates results. Nothing is installed on the remote host.

## Validation Summary

Before publication, the release path passed:

- shellcheck at style level on the script, the setup script, and the test harness
- The fixture-driven test suite (94 assertions against a fake proc tree and shimmed system commands, including config-injection, JSON-escaping, and multi-node aggregation cases)
- A live smoke run on the development host and in CI
- OpenForge readiness status with zero scrub findings

## Privacy Boundary

The internal script this tool replaced is not published. No hostname, address, interface, tunnel, or service name from it appears in the repository. The example configuration uses documentation address ranges (RFC 5737). The public artifact is the tool, its repository, its release, and this note.