The osprey health --json Contract#
The exact shape of the document osprey health --json writes, the exit codes
that accompany it, and how to consume both from a CI job.
Overview#
osprey health --json runs the same suite as a plain osprey health and
writes the result as a single JSON document on stdout. The document is the
contract: the web dashboard and the agent’s MCP health tools serve the same
shape, so anything you write against this page works against all three.
osprey health --json
Everything the run produces for a human — the spinner, warnings, the failure
banner — goes to stderr. Stdout carries exactly one JSON document and a
trailing newline, so osprey health --json | jq ... never sees a stray line.
The report envelope#
The document always has these nine keys, in this order:
{
"summary": "2/5 checks passed (1 warning, 1 error, 1 skipped)",
"ok": 2,
"warnings": 1,
"errors": 1,
"skips": 1,
"total": 5,
"elapsed_ms": 194.8,
"deadline_hit": false,
"results": [
{
"name": "disk_space",
"category": "file_system",
"status": "ok",
"message": "Disk 6% full (6986.2 GB free)"
},
{
"name": "beam_current",
"category": "beamline_services",
"status": "ok",
"message": "SR:CURRENT = 401.2 mA",
"value": "401.2 mA",
"latency_ms": 12.4
},
{
"name": "archive_last_pass",
"category": "archive",
"status": "warning",
"message": "Archive unreadable: [Errno 13] Permission denied: '/srv/osprey/my-agent/var/archive/2026-10-31/MANIFEST.jsonl'",
"details": "Check the archive container with `osprey logs archive`."
},
{
"name": "config_file_exists",
"category": "configuration",
"status": "error",
"message": "config.yml not found at /srv/osprey/my-agent/config.yml",
"details": "Searched from: /srv/osprey/my-agent\nRun this from inside a deployment repository, or pass --project with the directory holding config.yml."
},
{
"name": "ollama",
"category": "providers",
"status": "skip",
"message": "embeddings only, no chat; reachability is reported by `osprey ariel status`"
}
]
}
Key |
Type |
Meaning |
|---|---|---|
|
string |
The same one-line summary the human report prints, e.g.
|
|
integer |
Number of rows with status |
|
integer |
Number of rows with status |
|
integer |
Number of rows with status |
|
integer |
Number of rows with status |
|
integer |
Number of rows in |
|
number |
Wall-clock time for the whole run in milliseconds, rounded to one decimal place. |
|
boolean |
|
|
array |
One object per check, in the order the suite produced them. See below. |
Check rows#
Every object in results carries four keys unconditionally:
Key |
Type |
Meaning |
|---|---|---|
|
string |
Machine-readable check identifier, e.g. |
|
string |
The category the check belongs to, e.g. |
|
string |
One of |
|
string |
Human-readable one-line result. |
Three further keys are optional — they appear only when the check produced them, and a consumer must treat a missing key as “not measured”, not as an error:
Key |
Type |
Present when |
|---|---|---|
|
string |
The check measured something worth reporting separately from the
message, e.g. |
|
number |
The check timed itself and the result was greater than zero, rounded to one decimal place. Omitted otherwise. Probe checks (HTTP, MCP, channel read, archiver freshness) set it; most local checks do not. |
|
string |
The check has extended diagnostic text — an exception string, a remedy hint, a searched-path list. Often multi-line. Omitted when empty. |
Note
Do not assume the three optional keys correlate with status. An ok row
may carry value and latency_ms; an error row may carry only
message. Guard every read of them, for example
jq -r '.results[] | .latency_ms // "n/a"'.
Check statuses#
Status |
Meaning |
|---|---|
|
The check ran and passed. |
|
The check ran and found something degraded but not broken — a missing optional file, a value outside its preferred range. |
|
The check ran and failed, or could not run because of a fault it
considers fatal (a failed |
|
The check was not run. The usual reasons are an |
Exit codes#
The exit code is derived from the counts, so it and the document always agree.
Code |
Meaning |
When it occurs |
|---|---|---|
|
Healthy |
|
|
Degraded |
|
|
Failing |
|
|
Command failure |
The command itself raised before it could finish. No JSON document is
written — the failure is reported on stderr instead. Add |
|
Interrupted |
The run was interrupted (Ctrl-C). No JSON document is written. |
Important
“Healthy”, “degraded”, and “failing” are names for the exit codes 0,
1, and 2 in this table only. They are not values in the payload:
the document carries counts and the four row statuses
(ok/warning/error/skip), and there is no top-level status
word anywhere in it. Derive the verdict from the exit code, or from
.errors and .warnings.
Codes 3 and 130 are added by the command, not by the report. A
consumer that reads stdout must therefore handle “no document at all”, not
just a document with errors in it.
Consuming it from CI#
Because osprey health exits non-zero on warnings, capture the exit code
before your shell’s errexit sees it:
set +e
report=$(osprey health --json)
code=$?
set -e
case "$code" in
0) echo "healthy" ;;
1) echo "degraded: $(echo "$report" | jq -r '.summary')" ;;
2) echo "failing: $(echo "$report" | jq -r '.summary')"; exit 1 ;;
*) echo "health check did not complete (exit $code)"; exit 1 ;;
esac
Fail a pipeline on errors while tolerating warnings:
osprey health --json | jq -e '.errors == 0' > /dev/null
List what actually broke, category-qualified:
osprey health --json \
| jq -r '.results[]
| select(.status == "error" or .status == "warning")
| "\(.status)\t\(.category)/\(.name)\t\(.message)"'
Pull the details block for one check:
osprey health --json \
| jq -r '.results[] | select(.name == "config_file_exists") | .details // "(none)"'
Watch for a truncated run — counts from a run that hit its deadline describe fewer checks than the suite intended:
osprey health --json | jq -e '.deadline_hit | not' > /dev/null \
|| echo "health suite hit its deadline; raise health.suite_timeout_s"
Scope a run to one category, which narrows both results and the counts:
osprey health --json --category providers | jq -r '.summary'
The same envelope from the agent#
The agent reaches health through two MCP tools rather than the CLI, and they serve the same nine-key envelope plus three keys of their own:
Key |
Type |
Meaning |
|---|---|---|
|
boolean |
The report came from the server’s process cache rather than a fresh run. |
|
number |
Age of the served snapshot in seconds. |
|
boolean |
A stale snapshot was served because a wedged worker thread blocked the refresh. |
For what those three fields mean when you are reading an agent’s answer, see the “Reading the freshness fields” section of Configure Health Checks.
See also
- Configure Health Checks
Add facility probe checks and plugins, and tune the suite’s cost classes and timeouts.
- Run the Agent from the Command Line
The other machine-readable verb — full agent runs for CI.
- CLI Reference
Full
osprey healthflag reference.