Operate and support the modern agent

Start with the customer or fleet symptom, not by restarting every service. The modern split gives you a useful diagnostic question: is the device unreachable, or is the optional management plane unhealthy while rescue access still works?

What healthy looks like

A healthy full installation has:

• one stable device identity;
• the rescue path online;
• an active dataplicity-supervisor.service;
• a current desired-state manifest;
• a responsive loopback broker when product bindings are used;
• Class Software either reconciled or explicitly skipped with a reason;
• no unexplained growth in state, cache or logs.

A rescue-only device is healthy without the supervisor or broker.

Triage in this order

Symptom	First question	Evidence
Device offline	Can it resolve, keep time and reach Dataplicity over HTTPS?	Device Check, local network tests, rescue logs
Shell unavailable but device online	Is the rescue service healthy and permitted?	dataplicity status, service status, agent log
Streams or settings stale	Is rescue online but the supervisor/broker unhealthy?	prelude-agent status, connectivity, broker response
Class Software not running	Is there a supported runtime and a valid desired release?	supervisor status, runtime inventory, feature health
Change did not survive reboot	Is /var/lib/dataplicity actually persistent?	mounts, current config, identity and boot history
RAUC rollout stopped	Did compatibility, persistence, signature or rollback readiness fail closed?	RAUC readiness and rollout evidence

Useful local checks:

dataplicity doctor
dataplicity status
prelude-agent doctor
prelude-agent status
prelude-agent connectivity

Do not treat a missing prelude-agent command as proof of corruption until you have confirmed that the unit was meant to have the supervisor.

Change one layer at a time

A product container restart, supervisor restart, rescue restart and host reboot are different interventions. Record which layer you are changing and what evidence should improve.

Use a staging tag or small cohort before fleet-wide agent, container or image changes. Verify recovery through presence, logs, product data and customer-visible behaviour - not exit status alone.

Build a useful support bundle

prelude-agent support builds and uploads a support bundle and returns a short code. When escalating, include:

• device hash and organisation;
• agent generation and install mode;
• OS image, architecture and agent version;
• when the symptom began;
• the last known-good change;
• whether rescue, supervisor, broker and product application are each healthy;
• the support-bundle code.

Avoid these shortcuts

• Do not re-provision a device merely to repair a service; it can create a new identity and strand the old record.
• Do not install Docker, Podman or containerd as a generic response to an unhealthy feature.
• Do not grant broad sudo or socket access to make a permission error disappear.
• Do not mark a RAUC slot good until the product's defined validation has passed.
• Do not apply a classic-agent supervisorctl tuxtunnel runbook to the modern Dataplicity supervisor.

For fleet evidence and action, continue with Device Class Pulse, logs and diagnostics, and fleet jobs.