Integrate the modern agent into a Linux product

The integration is complete when a production-equivalent unit can be provisioned once, reconnect after a cold boot, preserve its identity, expose only the intended privileges, and recover through the same support path your field team will use.

1. Decide the install mode from the operating need

Choose rescue-only when the device needs remote access, file retrieval and support but will not use product streams, settings, actions or Class Software.

Choose rescue plus supervisor when the device needs the modern product runtime. Do not install a container runtime merely because the supervisor is present; containers are optional.

Use the exact organisation-scoped command shown by Add device. For a management-plane installer that should remain rescue-only:

curl -fsSL <your-account-install-url> | sudo bash -s -- --rescue-only

Treat the URL as provisioning material. Do not put it in a public image, ticket or repository.

2. Qualify the exact image

For the supervisor path, start with a systemd-based Linux image with Python 3.8 or newer, pip and venv. Published management packages cover x86_64, aarch64 and armv7; qualify the exact package and image you intend to ship.

Custom Yocto, unusual service managers and heavily reduced images are valid product choices, but they are integration work rather than a generic one-line-install promise. Validate:

• CA certificates, DNS, outbound HTTPS and an accurate clock;
• required users, writable state paths and systemd unit behaviour;
• boot ordering and reconnect after power loss;
• architecture and Python ABI;
• the container CLI and permissions only if Class Software is used.

See Linux compatibility and firewall requirements.

3. Give state an explicit home

The standard state root is /var/lib/dataplicity. Preserve it across package upgrades.

If the product uses A/B root filesystems, mount the persistent data partition there. Identity, config/current, caches and any managed container storage that must survive a slot change belong on persistent storage. Agent binaries belong in each signed rootfs slot under /opt/dataplicity.

Do not move binaries with a data-root setting. Do not assume a writable overlay is durable merely because a test reboot succeeded.

4. Keep privileges narrow

The rescue plane runs as dataplicity. The supervisor runs as dpagent. Grant a container-runtime group only when the product actually uses that runtime.

For managed RAUC, the only supported privileged path is the fixed dp-converge helper for RAUC install, mark-good and reboot. Do not replace this with blanket passwordless sudo.

5. Connect the product only where needed

A host process or container publishes to the loopback broker. It should not contain device credentials. Managed containers receive the current settings snapshot read-only.

Use Connect your product application for streams, settings and actions. Use Device data and controls for response, retry and delivery contracts.

6. Prove the production handoff

On the device:

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

Run only the commands present for the selected mode. Then prove:

1. the device returns online after a cold boot and network delay;
2. its identity does not change;
3. Remote Shell works with the intended Linux permissions;
4. the supervisor and broker recover without manual intervention;
5. a product value and one safe control complete the round trip, when used;
6. removing cloud connectivity does not break the product's local safety behaviour;
7. an agent or image upgrade preserves state and provides a tested recovery path.

For RAUC, also run dataplicity rauc-ready. That is an informational readiness check, not an installation requirement. Physical failed-boot testing remains mandatory before managed delivery.