Skip to main content
Version: 3.6.0

Agent Integration

In the following section we describe in detail how to setup and link an Tributech Agent with an existing Tributech Node. We will show how to gain access to the Tributech Docker Registry and startup an Tributech Agent with a Tributech Simulated Source.


First we need to setup an environment for the execution of the Tributech Software components. We will use Docker Compose to run a Tributech Agent and Tributech Simulated Source in the Docker Containers. If you want to use any other container runtime (e.g. containerd) please talk to your contact person at Tributech or send an email to our Customer Advisory Team.


The environment must meet the following hardware and software requirements:

Hardware Requirements

TypeMinimum RequirementRecommend Requirement
CPU1 Core (x86-64 / ARM32 )2 Cores
RAM1 GB Ram2 GB Ram

The Tributech Agent itself does not actually consume that much RAM, these are the requirements for the whole system. Keep in mind that these requirements strongly depend on the overall setup and the actual workload of the Tributech Agent. The stated Hardware Requirements are recommendations for small and medium workloads (based on volume of data processed). If you have any questions regarding infrastructure requirements, please talk to your contact person at Tributech or send an email to our Customer Advisory Team.

Software Requirements

OSAny current Linux DistributionUbuntu 18.04 LTS or later
RuntimeDocker Engine (≥20) + Docker-Compose (≥1.26)Docker Engine + Docker-Compose

Docker-Compose Setup

The Tributech Agent Services can be run using Docker Engine as a container runtime. We use Docker Compose for management/orchestration of the Docker services.

sudo apt-get update
sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg \
curl -fsSL | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo \
"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli
sudo apt-get install docker-compose

If you want to enable non-root users to execute docker commands visit Post-install.


After completing the installation process for our environment we now need to retrieve the Tributech Docker Images and configure the Docker-Compose environment as follows:


In order to gain access to the Tributech Agent docker image we need to provide docker with the credentials to access the private Tributech Docker Registry. The authentication information can be found in the Secrets section of the Tributech Node.

**"Tributech Node Secrets area**

The following command provides docker with the required permissions to access the private Tributech Docker Registry. For more information on docker authentication visit docker login.

echo <Client Secret> | docker login --username <Client ID> --password-stdin <Endpoint>

Docker-Compose environment

We have a docker-compose.yml prepared for an quick and easy setup with a Tributech Simulated Source:

version: "3.6"

image: ${}tributech-source-simulated:${SOURCE_TAG:-latest}
- mosquitto-server-simulated
- tributech-agent-simulated
- MqttOptions__MQTTHost=mosquitto-server-simulated
- Logging__LogLevel__Default=Debug
- simulated-net
restart: unless-stopped
driver: "json-file"
max-size: "2m"
max-file: "5"

image: ${}tributech-agent:${AGENT_TAG:-latest}
- mosquitto-server-simulated
- Logging__LogLevel__Default=Debug
- Logging__Console__FormatterName=simple
- MqttOptions__MQTTHost=mosquitto-server-simulated
- EdgeDeviceOptions__AgentID=${AGENT_ID:?"The variable AGENT_ID needs to be configured in the .env file."}
- "5000:80"
- simulated-net
- ./volumes/simulated/agent/:/app/data # volume mapping for permanent storage of keys and datatwin file
restart: unless-stopped
driver: "json-file"
max-size: "2m"
max-file: "5"

image: eclipse-mosquitto:${MQTT_TAG:-1.6}
- simulated-net
# ports:
# - '1883:1883' # MQTT
# - "" # web-socket
restart: unless-stopped


The docker-compose.yml can be used without any changes. However, we also need to create a .env file which contains the configuration details, for our docker-compose environment. The content of the file contains all relevant information about the docker image tags and the AGENT_ID. The AGENT_ID is a GUID that can be freely chosen, for easy recognition we use 00000000-0000-0000-0000-000000000007. We will use the AGENT_ID later on in the linking process to validate that we link the correct Tributech Agent with our Tributech Node. In our example the .env file looks as follows:


We can now Startup the environment by running the following command:

docker-compose up -d

Validate that all containers are running. The output should return that every container is in the state Up

docker-compose ps

If you encounter problems with starting the containers please consult the official docker documentation docker login and docker compose CLI.

After successfully starting the docker compose setup, in the previous step, we can now link the agent with the Tributech Node. Without completing the linking process the Tributech Node will not be able to receive any data from the Tributech Agent. In the agent overview we can click LINK NEW AGENT to initialize this process.

***Agent Linking***

Our prepared docker-compose.yml from the previous step exposes the port 5000 of the Agent to interact with the Tributech Node. The port of you environment must be reachable from the Tributech Node. If you are running the Tributech Node on a virtual machine you can use the following command to forward the port to your local machine:

ssh <vm-user>@<vm-ip> -L <local-port>:localhost:5000
# e.g.
ssh root@ -L 5000:localhost:5000

After the port forwarding is established we can start the linking process by clicking Connect:

***Agent Connect***

After pressing connect, we can see the AGENT_ID 00000000-0000-0000-0000-000000000007 we previously defined in our .env file for the docker environment. If the AGENT_ID is correct we can click Link/Relink Agent to continue the linking process:

***Linking Connect link***

Now we can finish the linking process by clicking Link/Relink Agent:

***Connect link***

After the successfully completed linking process, we can configure our desired Tributech Agent Source for the Agent.

***Connect link configuration***


In order to detect data tampering we provide the possibility to audit each stream individually and quickly find failed validations. We can either use graph a to visually find problems or a table to filter proofs with predefined filters. We will describe both options in the following sections.

Validation Graph

The Validation Graph can be displayed by clicking Display Audit Result and contains three different colors:

  • gray - validation is pending
  • green - validation was successful
  • red - validation was not successful

***Audit Graph***

Validation Table

In Order to view every created proof with its validation history in table format we can use the AUDIT RESULTS button from the stream overview:

***Select audit***

The audit results table view provides the possibility to filter the audit results based on the validation result. We can use the filter to quickly find failed validations and inspect the validation history for a given proof. We want to highlight some features to quickly get started with the audit:

  • Overview - Display all created proofs in timespan sorted by Proof Timestamp ***Audit overview***

  • Filter - Limit the displayed audit results based on the validation result Alt text

    Alt text

  • Retrigger - Validation can be triggered manually and the table view will always display the latest validation result for any proof.

    ***Audit retrigger***

  • History - By selecting a proof row we can inspect the validation history for each proof.

    ***Audit retrigger history***