Device gRPC API
A small agent runs on every enrolled device. It is the agent — not the operator — that talks to this API. It registers the device, heartbeats for liveness and desired state, reports the progress of each update, and uploads requested logs. This is a separate surface from the operator REST API: it is gRPC, and it is served over mutual TLS only.
You normally never call this API yourself. It is documented here so you can reason about exactly what the agent does on your devices, and confirm it does no more than that.
Identity comes from the certificate, never the request
The service is served over mTLS with client-certificate verification. The device's identity is derived from its verified client certificate — not from anything in the request body. A device can therefore only ever register, heartbeat, or report as itself; it cannot impersonate another device by changing a field.
Each device receives its certificate at enrollment, carrying a stable identity bound to its name and fleet. See Device identity for how that certificate is issued and what it asserts.
The four calls
| Call | Purpose |
|---|---|
Register | Idempotent. The same certificate always maps to the same device record; re-registering refreshes the hardware profile, agent version, and tags. |
Heartbeat | Reports liveness and returns the device's desired state — the artifact assignments it should converge on — plus any pending log requests. |
ReportArtifactStatus | Reports progress of an assignment as it moves through its lifecycle. |
UploadLogs | Delivers a compressed log bundle the operator requested via a heartbeat, collected only from an allowlisted source. |
Desired state and convergence
Heartbeat returns the artifacts the device should be running. The agent reconciles
this desired state against what is installed and converges toward it. Every
assignment is protected by update-signing metadata: the agent resolves and verifies
the target against its pinned trust anchor, and cross-checks the expected digest as
defense in depth, before applying anything. Nothing unverified is ever applied. See
How it works and The Update Framework.
Artifact kinds the agent handles include models and config (swapped atomically as a file) and containers (delivered as a signed, digest-pinned image reference the device runs via its local runtime).
Health probes and rollback
Each assignment carries a post-swap health-probe contract. After the agent swaps in a new artifact, it runs the probe; if the probe fails, the agent automatically rolls back to the previous version. Probes are one of:
- exec — run an allowlisted health-check binary; exit 0 means healthy. There is no shell; the target is an absolute path on the device's allowlist.
- http — an HTTP GET, where a 2xx response means healthy.
- file — a readiness file exists and is non-empty.
A probe defines its timeout, number of attempts, and an initial delay before the first check.
Status lifecycle
ReportArtifactStatus reports an assignment as it moves through:
downloading → verifying → applying → healthy
↘ rolled_back
↘ failed
These per-device states are what surface in the rollout detail view and feed the audit trail.
Constrained, allowlisted behaviour
The agent's reach is deliberately narrow. Log collection reads only from an allowlisted source (the agent's own service journal) — there is no arbitrary-path read and no remote shell. Exec probes and any config reload actions are likewise allowlisted on the device, and the device re-validates every instruction it receives rather than trusting the control plane. If a device has been offboarded, the heartbeat tells the agent, which self-cleans its key material and exits.