Build provenance
How the agent reports what build it is running, and what the Official, Source, and Modified badges mean.
Starting with agent 1.5.0, every heartbeat carries a build block
that describes where the running code came from. The dashboard
renders it as a badge next to the agent's version.
The three channels#
| Badge | Meaning |
|---|---|
| Official | The process runs the published container image, and its source hash matches the hash published for that release. |
| Source build | The process runs from a source checkout (bun src/index.ts). Normal during development and for operators who build their own deployment. |
| Modified build | The process claims the official image but its source hash differs from the published one. The code inside the image has been changed. |
Agents older than 1.5.0 report nothing and show no badge.
How the hash works#
The hash is a SHA-256 digest over the agent's src/ tree: every
.ts, .js, and .json file, visited in sorted path order, path
and contents both included. The release pipeline computes it with
the same function the agent uses at boot, so the two values can
only agree when the code is identical.
- Official images carry a
build-info.jsonstamped at build time with the channel, git commit, and the hash of the exact tree the image was built from. - Source runs compute the hash live at startup.
- Each release publishes its hash as a
build-info.jsonasset on the GitHub release, which is what the dashboard compares against.
What this is, and what it is not#
The build block is self-reported telemetry. The agent is open
source; a fork can send any value it likes, including a copied
official hash. The badge answers the practical question ("is this
deployment running the code we published, or something else?") for
operators acting in good faith. It is not an integrity control and
does not change what the agent is allowed to do.
If you maintain a private fork on purpose, the Modified or Source badge is expected and harmless. It exists so that an unexpected modification, or a stale patched image someone forgot about, is visible instead of silent.