Skip to main content
This section covers Agent roles and a streamlined approach to creating, installing, and optimizing them for your specific robotics deployment.

Heex Agent

Create your Agent

Install your Agent

Update your Agent

​
Heex Agent

​
Overview

The Heex Agent is an out-of-the-box solution for deploying and running the Heex runtime on production systems. It installs the Kernel executables together with your packaged implementations (i.e., Monitors and Recorders) and ensures they run reliably on the target machine. While the Heex SDK focuses on developing implementations on a Dev Station (to monitor and record relevant events), the Heex Agent and its installation tools are designed to deploy, update, and operate Heex on customer production systems. In practice, the Heex Agent is delivered as a self-extracting installer that deploys the Kernel plus the packaged Monitors and Recorders, then runs them on the target system.

​
How it’s installed

The recommended tool to retrieve and install the Agent on production systems is heex-installer.
  • Linux (default): installs the Agent as a service.
  • Fallback options: alternative deployment modes are available when services are not supported, such as:
    • running as a process
    • deploying a Docker image
After the initial installation, subsequent installations will update the executables to the latest available versions. Updates can be performed manually or via scripting, but are typically delivered Over-The-Air (OTA) from any Dev Station. See Remote update.

​
Default vs custom

​
Default Agent (no-code)

When you register a new system, a default Heex Agent is automatically assigned based on its operating system. This default Agent includes a set of built-in implementations covering common no-code use cases (e.g., RDA Monitor/Recorder for ROS 2, weather conditions, log analysis) without requiring custom development or publishing a custom Agent. Not all packaged implementations run by default: the Kernel starts only the implementations required by the system configuration.

​
Custom Agent (advanced use cases)

If you need capabilities beyond the default no-code experience (e.g., custom monitoring/recording logic or advanced configuration), you can build your own implementations and Agent package using the Heex SDK on your Dev Station. Once developed, cross-compiled, tested, and ready for release, you can publish the installer with the Heex CLI and remotely roll it out to your systems. The published Agent replaces the default Agent assigned to the system or fleet.

​
Create your Heex Agent

How do I create and associate a custom Heex Agent with my production system?
Creating a custom Agent is required only if you need custom implementations or want to ship specific Heex Agent configuration to a system or fleet.
We recommend installing the default (no-code) Agent first to confirm it meets your needs: see Install your Heex Agent.

​
Prerequisites

  • Heex SDK installed on your Dev Station
  • Your implementation binaries (Monitors and Recorders)
  • Heex CLI
  • (Optional) a system configuration file for your production environment
You will create and publish a Heex Agent installer by packaging your custom implementations, the Kernel executables, and any required configuration.
The unpacked installer contains:
  • The Kernel binaries
  • Heex SDK runtime libraries
  • Your custom implementation binaries (Monitors and Recorders)
  • Configuration files (e.g., Core.json, systemConf.json)

​
Three-step creation process

In this example, we create an Agent using only the implementations from the get-started folder.
1

Evaluate need for custom configuration

First, determine whether your production deployment requires specific configuration.
Review Agent configuration, Agent configuration for ROS2, and Kernel configuration.For the get-started implementations, no additional configuration is required.
2

Copy your implementations

Copy your implementation binaries into the Heex SDK implementations directory:
cd ~/Heex_SDK_<version>/get-started/cpp
cp GetStartedMonitor ../../implementations
cp GetStartedRecorder ../../implementations
3

Create your installer using the HeexCLI

  1. Retrieve the SYSTEM_ID of your production system (not your Dev Station).
  2. From the SDK root, create and upload the Agent installer:
cd ~/Heex_SDK_<version>/
heex agent upload --system-id <SYSTEM_ID>
Additional options (e.g., using an external path) are documented here.

Congratulations

You have created and published your first Heex Agent.

​
Install your Heex Agent

How do I quickly install the Heex Agent on my production system?
These steps apply to both the default (no-code) Agent and any custom Agent you have published for an existing Heex system.
1

Retrieve your production system ID

Retrieve the SYSTEM_ID of your production system (not your Dev Station).
2

Retrieve your workspace API key

Retrieve your workspace API_KEY from the Heex Web Interface (Workspace → API Keys).
3

Install the heex-installer tool on the production system

Install heex-installer on the production system by following either:
4

Install the Agent associated with your system

Install the latest Agent associated with your system:
heex-installer --api-key <API_KEY> --system-id <SYSTEM_ID>

Execution mode

By default, the installer runs the Kernel and implementations as user services when systemctl is available.
If you prefer background processes (or services are not supported), add --execution-mode background.Note: in background process mode, a reboot will not automatically restart the Kernel (and therefore the implementations).
You should see logs listing the deployed Kernel and implementation names/IDs. When the installation completes, the Kernel and required implementations will be running.
For less streamlined or more complex robotics deployments, see Agent manual installation.

Congratulations

You have installed the Heex Agent on your production system.

​
Update your Heex Agent

How do I update the Heex Agent on my production system?
After installing the Agent, you have two options to update it (e.g., add/remove implementations, or update the Kernel):
  1. (Recommended) Automatically deploy and install updates Over-The-Air.
  2. Run the same installation procedure using the most recent Agent version associated with your system.

​
Uninstall the Heex Agent

How do I uninstall the Heex Agent from my production system?
You can uninstall the Agent using the installer’s --uninstall option. See Agent configuration for installer configuration and uninstall details.
You can also uninstall using the Heex CLI. See the CLI documentation: Agent uninstall.