Device gRPC API
A small agent on every enrolled device talks to this API - not the operator. It registers the device, heartbeats for liveness and desired state, reports update progress, and uploads requested logs. It's a separate surface from the operator REST API: gRPC, served over mutual TLS only.
You never call it yourself. It's documented so you can confirm exactly what the agent does on your devices - and that it does no more.
Identity comes from the certificate, never the request
A device's identity is derived from its verified mTLS client certificate, not from the request body - so it can only ever register, heartbeat, or report as itself. Each device gets that certificate at enrollment; see Device identity.
What the agent does
Over this channel the agent does a small, fixed set of things, and nothing else:
- Registers itself - idempotently, so the same certificate always maps to the same device record; re-registering only refreshes the hardware profile, agent version, and tags.
- Reports in for liveness and receives its desired state - the artifact assignments it should converge on - along with any pending log request.
- Reports progress of an assignment as it moves through its lifecycle.
- Uploads a requested log bundle, collected only from an allowlisted source, when the operator has asked for one.
Desired state and convergence
When the agent reports in, it receives the artifacts the device should be running and converges its installed state toward that. Before applying anything, it verifies the target against its pinned trust anchor and cross-checks the expected digest - nothing unverified is ever applied. See How it works and The Update Framework.
Models and config swap atomically as a file; containers arrive as a signed, digest-pinned image reference run via the device's 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
An assignment moves through these per-device states:
downloading → verifying → applying → healthy
↘ rolled_back
↘ failed
These states 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 an allowlisted source (its own service journal) - no arbitrary-path read, no remote shell. Exec probes and config-reload actions are allowlisted on the device, which re-validates every instruction rather than trusting the control plane. Once a device is offboarded, the next heartbeat tells the agent to self-clean its key material and exit.