Runtimes: container & standalone
The agent applies different kinds of payload, and not every device has — or wants — a container runtime. This page covers the two modes the agent supports and how each one applies, health-checks, and rolls back an update.
Container mode
When a device has a container runtime, the agent runs your application images
through it. It prefers podman and falls back to docker, or you can name a
runtime explicitly; setting the runtime to none disables container payloads
entirely.
Images are referenced by digest only. The agent re-validates the image descriptor on-device, pulls the digest-pinned image, and starts it under a managed name with a restart policy. Because the reference is content-addressed, the registry is untrusted transport: a registry that lies can only fail the pull, never hand back different content. The runtime is always invoked with a fixed argument list, never through a shell.
On a new version the agent stops and replaces the managed container but keeps the previous image in the local store. If the post-swap health probe fails, that retained image is what the agent rolls back to — across an agent restart, because the current and previous specs are persisted on disk.
Standalone mode
Constrained devices can run with no container runtime at all. In standalone mode the agent manages raw artifacts directly: it places a verified payload into its data directory and swaps it atomically, retaining the previous version so a failed health probe reverts cleanly. This is the path for raw model files and for devices where a container runtime is undesirable.
Configuration delivery
Configuration files are delivered as a verified payload with a small declarative descriptor: a destination path, a file mode, and an optional reload action. This capability is off by default — the agent only places a file outside its own data directory when an operator has allowlisted the destination prefix, and only fires a reload that names an allowlisted systemd unit or binary. Before writing, the agent checks the content against its declared digest and backs up any existing file, so a failed health probe restores the prior configuration and re-runs the reload. Writes are atomic: the file is staged and then renamed into place.
Health probes and rollback
Every update type carries a health probe that the agent runs after the swap. Three probe types are supported:
| Type | What it checks |
|---|---|
| HTTP | a GET to a URL returns a 2xx status |
| File | a path exists and is non-empty |
| Exec | an allowlisted binary exits successfully |
Probes support an initial delay, a per-attempt timeout, and multiple attempts. Exec probes run only an absolute, operator-allowlisted binary, directly with no shell, and are told where the active artifact lives through an environment variable. If the probe never passes, the agent rolls back automatically — the previous container image, raw artifact, or configuration file is restored without operator action.