Health endpoints

On this page

The endpoints
Settings
Examples
Troubleshooting

The agent serves three small read-only HTTP endpoints, so that you — or Docker, Kubernetes, a container platform, your own supervision — can check it from its machine without opening Onagre.

The endpoints#

Endpoint	Answers	Use it as
`GET /health`	`200` `{"status":"Healthy"}` while the process runs.	Liveness probe.
`GET /ready`	`200` `{"status":"Ready"}` when the agent is connected to the Hub; otherwise `503` with a `reason`.	Readiness probe, post-install check.
`GET /status`	Version, uptime, connection and activity.	Diagnosis.

Terminal

curl -s http://127.0.0.1:8080/ready

JSON

{ "status": "NotReady", "reason": "Hub stream not established: Another agent is already connected with this token" }

/status returns, for example:

JSON

{
  "status": "Running",
  "version": "2.8.4.112",
  "startedAt": "2026-10-12T06:02:11Z",
  "uptimeSeconds": 13412,
  "ready": true,
  "configurationLoaded": true,
  "hubConnected": true,
  "mode": "advanced",
  "lastHubCommunication": "2026-10-12T09:45:41Z",
  "lastSensorExecution": "2026-10-12T09:45:38Z",
  "sensorExecutions": 4127
}

Field	Meaning
`mode`	`advanced` for an Advanced agent, `standard` for a Core agent.
`hubConnected`	The connection with the Hub is up.
`lastHubCommunication`	Last exchange with the Hub.
`lastSensorExecution`, `sensorExecutions`	Last check run, and number of checks since startup.

The endpoints return no token, no address and no configuration. Calling them often costs nothing: they never contact the Hub.

Settings#

Variable	Default	Purpose
`PORT`	`8080`	Listening port.
`HTTP_API_BIND`	`loopback`	`loopback`: only from the machine itself (127.0.0.1). `any`: from everywhere — needed for probes from outside a container. Or a specific IP address.
`HTTP_API`	on	`0` turns the endpoints off.

By default, nothing is exposed to the network. With HTTP_API_BIND=any, keep the port closed to the outside: the endpoints are for supervision only.

The endpoints start once the agent has authenticated with Onagre. Before that — API unreachable, wrong token — they do not answer: read the agent's log instead. If the port is already taken, the agent logs a warning and keeps monitoring.

Examples#

Terminal

docker run -d --name onagre-agent --restart=always \
  --env-file ./onagre-agent.env \
  --health-cmd "curl -fsS http://127.0.0.1:8080/health || exit 1" \
  --health-interval 30s \
  onagreio/agent

YAML

env:
  - name: HTTP_API_BIND
    value: "any"
livenessProbe:
  httpGet: { path: /health, port: 8080 }
  periodSeconds: 30
readinessProbe:
  httpGet: { path: /ready, port: 8080 }
  periodSeconds: 30

Terminal

curl -s http://127.0.0.1:8080/status

Troubleshooting#

Symptom	Likely cause
Connection refused	The agent is not started yet, is still waiting for the API, or its token was refused — read its log. Or the endpoints are off (`HTTP_API`) or on another `PORT`.
`/ready` stays `503` — `Hub stream not established`	The Hub cannot be reached on port 443 (firewall, proxy), or another agent already uses this token.
`lastHubCommunication` is old	The connection dropped: the agent reconnects on its own; check the network path.