Blog / How-to guides

Look after your node: health, version, status, utilisation and its disks

12 October 2026 · Semurg · 3 min read · Markdown

Verified: every command below ran on a fresh node of r11.78.20261012.bc0d94f (how)

operationsmonitoringinstallhow-to

A node you run should be able to tell you how it is doing without anyone logging in to it. These calls do that. Each answers JSON; with your API token you get the operator detail, and without it a caller from elsewhere gets only a coarse summary, so a networked node never hands its internals to a stranger.

Health and version answer anyone; with the token, status says what the node is and holds, licence its licence state, util how hard it works, conveyor what memory serves, customs whether its disks are in order, and nodes which nodes it knows.No tokenWith your tokenYour monitoringIs it up?Which release?What is it, what doesit hold?Licence stateHow hard is itworking?Served from memory ordisk?Are its disks inorder?Which nodes are there?Health and version answer anyone; with the token, status says what the node is and holds, licence its licence state, util how hard it works, conveyor what memory serves, customs whether its disks are in order, and nodes which nodes it knows.No tokenWith your tokenYour monitoringIs it up?Which release?What is it, what doesit hold?Licence stateHow hard is itworking?Served from memory ordisk?Are its disks inorder?Which nodes are there?

Is it up, and which release is it?

bash
curl -sS http://localhost:4000/api/health

Expected: the node's health as JSON

bash
curl -sS http://localhost:4000/api/version

Expected: the release the node runs, with its commit

The version is the one to quote when you report a problem, and the one the update command compares with the latest published release.

What is it, and what does it hold?

/v1/status describes the node: its identity, its licence state, what it can do and what its store holds.

bash
export SEMURG_API_TOKEN=<your token>
curl -sS http://localhost:4000/v1/status -H "Authorization: Bearer $SEMURG_API_TOKEN"

Expected: the node's identity, capabilities and store counts

/v1/licence reports the licence state. A single node runs the full engine with no licence key: on a node of its own nothing needs licensing, and a key matters only when a node joins a cluster.

bash
export SEMURG_API_TOKEN=<your token>
curl -sS http://localhost:4000/v1/licence -H "Authorization: Bearer $SEMURG_API_TOKEN"

Expected: the licence state

How hard is it working?

/v1/cluster/util is a live snapshot of the machine while it works: each disk's throughput, each core's load and the memory bandwidth in use, per node and in total. It is the same measurement Semurg publishes beside its own benchmark figures, so you can read your node the way we read ours. One caveat: the memory-bandwidth figure in it is being re-proven after our 2026-10-11 control audit, which found that it reads only part of the engine's own traffic, so for now treat it as a lower bound.

bash
export SEMURG_API_TOKEN=<your token>
curl -sS http://localhost:4000/v1/cluster/util -H "Authorization: Bearer $SEMURG_API_TOKEN"

Expected: a utilisation snapshot for the node

/v1/cluster/conveyor shows the counters of the machinery that decides what is in memory: how much the memory tier is serving, how far ahead the prefetch is reading, and how much the janitor has packed together. Read it before and after a workload, and the difference says whether that workload was served from memory or went to disk.

bash
export SEMURG_API_TOKEN=<your token>
curl -sS http://localhost:4000/v1/cluster/conveyor -H "Authorization: Bearer $SEMURG_API_TOKEN"

Expected: the memory tier, prefetch and janitor counters

Are its disks in order?

Each data disk is split into a landing area, where data arriving in a foreign format waits to be converted, and the store itself. /v1/cluster/customs checks that split on every disk and answers with one verdict, green, red or could_not_judge, and, for the operator, each disk's state.

Each data disk holds a landing area, where data in a foreign format waits to be converted, and the store itself; the customs check reads that split on every disk and answers green, red or could not judge.Data in a foreignformatThe landing area oneach diskConverted into thenode's recordsThe storeThe customs checkGreen, red or couldnot judge
bash
export SEMURG_API_TOKEN=<your token>
curl -sS http://localhost:4000/v1/cluster/customs -H "Authorization: Bearer $SEMURG_API_TOKEN"

Expected: the landing area and store check, with its verdict

Which nodes are there?

/v1/cluster/nodes lists the nodes the cluster knows; on a node of its own, that is itself. /v1/cluster/nodes/<fingerprint> gives one node's status in detail.

bash
export SEMURG_API_TOKEN=<your token>
curl -sS http://localhost:4000/v1/cluster/nodes -H "Authorization: Bearer $SEMURG_API_TOKEN"

Expected: the list of nodes this node knows

Next

  • Keep the node current with the update guide.
  • Adding a second node is not covered here yet; it will be, once it works from a published release.

How these commands were checked

Our test farm ran each of the 8 command blocks marked runnable, exactly as written, with the answer checked against the expectation printed under it, against a fresh node of the published release r11.78.20261012.bc0d94f. A post is published only when every one of them passed there.

Related