Dataplicity agent

The Dataplicity agent is the software that runs on each managed Linux device. It keeps an outbound connection to Dataplicity, presents the device identity, and carries remote access, diagnostics, and connected-product workflows that your organisation enables for that device.

Install it with the one-line command from Add device in your account. That command is organisation-scoped provisioning material. Do not publish it, commit it to a public repository, or reuse a command copied from another organisation.

Two install modes

The installer has two modes. Choose by what the device must do in the field.

Mode	What it installs	When to use it
Remote access only (rescue)	The rescue agent that maintains the outbound connection	Shell, Wormhole, files, and the same remote-access job as the classic agent
Rescue plus supervisor	Rescue agent plus the optional management supervisor	Class Software / container management, the local stream broker, and other connected-product on-device functions

The supervisor is optional. Devices that only need remote access can stay on rescue-only indefinitely. Assign those units to product definitions that do not require supervisor features, and no Class Software or broker stack is pulled down.

When the management-plane installer is used and you want rescue-only, append --rescue-only to the install command:

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

Use the exact URL from Add device. Do not invent or share another organisation's install URL.

What the agent provides

Capability	Rescue only	With supervisor
Device identity	Yes	Yes
Remote Shell	Yes	Yes
Wormhole	Yes	Yes
File retrieval	Yes	Yes
Logs and monitors (device evidence)	Yes	Yes
Fleet jobs through the agent path	Yes	Yes
Class Software (OCI application images)	No	Yes
Local stream broker for product streams	No	Yes

Availability of Class Software, Device Class UI, and the Customer Portal also depends on your organisation's feature access and the agent release you qualify. See Production limits.

Agent compared with workstation tools

Tool	Where it runs	Purpose
Dataplicity agent	Each managed Linux device	Device connection, identity, remote access, and optional on-device product runtime
Dataplicity CLI	Operator or developer workstation	Local terminal automation against your organisation
Web CLI	Inside the Dataplicity app	Browser commands with your signed-in role and device context

The workstation CLI does not replace the agent. See Command-line tools.

Architecture on the device

Both modes share one device identity. State lives under /var/lib/dataplicity.

Plane	Linux user	Typical service	Required?	Responsibility
Remote access (rescue)	dataplicity	dataplicity-rescue	Always for a managed device	Outbound connection, Remote Shell, Wormhole, remote files
Supervisor	dpagent	dataplicity-supervisor	Optional	Manifest reconcile, Class Software, local stream broker, feature health

Remote-access sessions inherit the permissions of the dataplicity account. Class Software and container work run under the supervisor identity and any groups you grant that account (for example a container runtime group).

Older single-service installations may differ. Inspect the units and process owners on the image you ship before treating any path as universal.

Requirements

Every managed Linux device needs:

• Outbound HTTPS to the hosts in Firewall requirements
• Accurate system time (NTP on boards without an RTC)
• Writable paths for agent state and configuration

Field devices are Linux. The workstation Dataplicity CLI is a separate tool.

Remote access only (rescue)

Rescue is the remote-access agent: Remote Shell, Wormhole, file retrieval, and device identity on the same outbound connection model used across Dataplicity fleets. It is built for mixed-age Linux estates, including long-lived field images that still ship old system Python.

Python: rescue packages require Python 2.7 or newer. The current build and test matrix covers:

Python	Status
2.7	Supported floor; still built for field images that only have Python 2
3.5, 3.6, 3.7	Supported on older 3.x images still common in the field
3.9, 3.10, 3.11, 3.12	Supported modern 3.x, including Ubuntu 24.04 / Python 3.12

That coverage is why one Dataplicity organisation can run decade-old gateways and current build images under the same inventory. Qualify the exact OS image you ship; unusual boards and custom distributions are assessed case by case. See Keep one ops layer across ancient and brand-new images.

Host layout for rescue:

• Linux with a system python or python3 in the matrix above
• Writable /var/lib/dataplicity, /etc/dataplicity, and /home/dataplicity

Rescue plus supervisor

Install the supervisor when the device needs Class Software, the local stream broker, or other management-plane functions.

Python and OS:

• Python 3.8 or newer, with pip and venv
• Debian / Raspberry Pi OS 11+, Ubuntu 20.04+, or a current Arch, Alpine, or Fedora image with equivalent tooling
• Architecture x86_64, aarch64, or armv7 for the published management package

Host layout for supervisor:

• Writable /opt/dataplicity, /var/log/dataplicity, and /usr/local/bin in addition to the rescue paths above

Class Software runtime:

• docker, podman, or nerdctl on PATH
• Where container support is enabled for the install path and none of those CLIs is present, the installer can install containerd and nerdctl
• Dataplicity manages containers named dp-*; other host containers stay inventory-only

Qualify the exact OS image, architecture, agent release, runtime, and product hardware together before a production batch. See Linux compatibility.

Install

1. Confirm outbound HTTPS and NTP on the target image.
2. In Dataplicity, open Add device and copy the generated command.
3. Run that exact command with administrator privileges on the device. Add --rescue-only when you are on the management-plane installer and only need remote access.
4. Confirm the device appears online in the inventory.
5. Open Remote Shell. When you use connected-product features, confirm the supervisor is present and verify the local broker and any Class Software path you intend to ship.

For factory imaging and first-boot automation, see Installing for mass production and Device preparation.

Layout after install

Item	Rescue only	With supervisor
Shared state and identity	/var/lib/dataplicity	/var/lib/dataplicity
Remote-access home	/home/dataplicity	/home/dataplicity
Python environment	Host / rescue runtime	/opt/dataplicity/venv
On-device commands	dataplicity	dataplicity, prelude-agent, dp-provision
Services	dataplicity-rescue	dataplicity-rescue, dataplicity-supervisor

Package delivery for the management-plane installer uses published agent releases, not PyPI. Prefer the dashboard install command over assembling packages by hand.

On-device checks

From a console or Remote Shell on the device:

dataplicity doctor
dataplicity status

When the supervisor is installed, also run:

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

Use these before imaging a production batch, after an OS change, and when a unit fails to enrol or reconnect.

prelude-agent support builds and uploads a support bundle and returns a short code you can give to Dataplicity support. Include the device hash, OS image, architecture, install mode (rescue-only or with supervisor), and agent version reported in the OEM workspace.

Product data path

When Device Class streams are enabled, a product process on the device publishes to the agent-local broker on loopback. That broker ships with the supervisor:

POST http://127.0.0.1:18765/v1/streams/{binding_id}

The agent authenticates cloud delivery with the device identity. Keep Dataplicity credentials out of application images. Implementation details, response codes, retry behaviour, and non-guarantees are documented in Device data and control contract.

Software and firmware ownership

Class Software rollouts version OCI application images selected for a Device Class. They require the supervisor and do not replace OS image update, bootloader update, modem firmware, or a board vendor's update tool.

On image-managed fleets that use RAUC, RAUC owns OS and firmware updates, including cases where Dataplicity is baked into the rootfs. The agent reports firmware inventory so the control plane can see what is running. See Software and firmware boundaries.

Related

• Connect your first device
• Agent upgrade and removal
• Firewall requirements
• How it works
• Security model
• Build a class container
• Device data and control contract
• Keep one ops layer across ancient and brand-new images