Trails & steps

A trail is a device's configuration history: an append-only sequence of steps, each one a numbered revision of the device's complete state. The trail is the heart of how Hub manages devices — it lets you do asynchronous configuration management of devices that may be offline for long stretches.

API: the trails service — request flows, plus the /trails endpoint reference to try calls live.

Revisions

Each step carries a revision number. Revision 0 is the device's factory state, posted by the device on its first boot. Every later step must be exactly one greater than the current HEAD — this +1 rule lets the trail service reject concurrent/conflicting updates ("first come, first served").

• HEAD / goal — the latest revision in the trail; the state you want the device to reach.
• Current — the revision the device reports it is actually running.

When current == goal the device is in sync. When current < goal the device is in transit, walking the steps between them.

Step status lifecycle

A device walks the trail one step at a time and reports status back as it goes:

NEW ─▶ QUEUED ─▶ INPROGRESS ─▶ DONE
                      │
                      ├─▶ ERROR     (apply/health-check failed → previous state preserved)
                      └─▶ WONTGO    (skipped: can't be applied as a +1 step)

Status	Meaning
NEW	Step exists in the cloud; device hasn't committed to it yet.
QUEUED	Device has accepted the step and intends to apply it.
INPROGRESS	Device is applying it (reports a progress 0–100 and notes).
DONE	Applied successfully; device advanced to this revision.
ERROR	Apply or health check failed; device rolled back and stops here.
WONTGO	Step can't be applied incrementally; skipped.

A device only advances if the next step is a clean +1 from its current revision. If a step fails, the previous state is preserved and the trail halts at ERROR until you clear it.

Operating on a stuck trail

When a step ends in ERROR, you have a few moves:

• Retry — re-set the failed step to NEW so the device tries it again (useful for transient failures like a power loss mid-upgrade). A retry counter increments so tooling can build smart backoff.
• Reroute — delete the ERROR/WONTGO steps and append a corrected step in their place. The device then proceeds as if the bad steps never existed.
• Abort — flag a step to stop it. If the device hasn't applied it yet, it stops and stays on the previous state. If it already finished, the step moves to DONE but keeps an abort flag, signalling that a manual backout (e.g. a reverse step appended to the trail) is needed.

Factory reset

If a device boots thinking it's brand new but a trail already exists, that's either an error or a deliberate factory reset. To allow a reset, delete the trail first; the device can then post a fresh factory state at revision 0.

What a step contains

A step references the objects that make up the state — typically a kernel, system, and platform/app entries — each pointing at an object by its prn (Pantahub resource name) plus an access token. Steps are expressed as RFC 7386 merge patches against the previous revision, so a step that only changes the kernel only needs to carry the kernel entry.