The Red Hat Edge Manager agent is a process running on each managed device that periodically communicates with the Red Hat Edge Manager service.

The Red Hat Edge Manager agent is responsible for the following tasks:

• Enrolling its device into the service.
• Checking with the service at regular intervals for changes in the device specification, such as updates to the operating system, settings, and applications.
• Applying any updates independently from the service.
• Enforcing workload user separation: applications run as root by default when runAs is not set. When set, runAs enables rootless (non-root) execution or privileged execution with elevated capabilities.
• Validating that the required user exists on the device before starting rootless workloads.
• Reporting status of the device and the applications.

The Red Hat Edge Manager service is the control plane that connects administrators and automation to the device fleet. It manages each device from enrollment through ongoing health and activity monitoring.

The service uses a database that stores the device inventory and the target device settings. The agent polls the service for changes in the settings. If the agent detects that the current settings differ from the target, it attempts to apply the changes to the device.

Note

Because the agent continuously reconciles each device toward its target settings, do not make changes directly on a managed device. Manual changes to configuration files, Quadlet units, or virtual machines, including changes made with imperative tools such as virsh, are not supported and can be reverted by the agent. Apply all device and application configuration through the Red Hat Edge Manager service.

When the agent receives a new target configuration from the service, the agent does the following tasks:

1. Stage resources: The agent pre-downloads all required assets to local storage, including the operating system image and application container images. This step guards against network failure during the update.
2. Update operating system: The agent delegates the operating system update to bootc, ensuring a transactional image-based transition.
3. Apply configuration: The agent updates the local file system by overlaying configuration files provided by the service.
4. Finalize environment: If the update requires it, the agent triggers a system reboot. If no reboot is needed, it signals the relevant system services and applications to reload their settings.
5. Update workloads: The agent syncs and updates applications that run on Podman or MicroShift. Podman-based applications (quadlet, container) run on Podman. Helm applications are deployed to MicroShift on the device.

Note

On package-mode devices, the agent skips steps 1 and 2. The agent does not stage an OS image or invoke bootc. Instead, the agent applies configuration overlays and updates application workloads directly. If the new spec includes an OS image target, the agent rejects the entire spec atomically before any reconciler runs. For more information, see Package-mode capabilities and limitations in the Additional resources section.

If the update fails or the system does not come back online after a reboot, the agent rolls back to the previous operating system image and settings. Rollback to a previous OS image applies to image-mode devices only. On package-mode devices, the agent does not perform OS updates, so there is no OS image to roll back.

Note

You can store fleet definitions in a Git repository. The Red Hat Edge Manager service syncs Git-hosted definitions with the database at regular intervals so that changes you commit are applied to the fleet.