Edge Agent
Learn how to create, deploy and use Native Agents (also called Edge Connectors).
Edge Agents are secure, industrial-grade bridges that run as system services (daemons) within your private network. They tunnel data from local protocols (S7, Modbus, OPC UA) to your cloud workspace, ensuring connectivity that persists through system restarts and power cycles.
Native Agent
The Native Agent is a fully installable package. When installed, it registers itself as a background service (a Windows Service or Linux Daemon), ensuring 24/7 availability without requiring a user to be logged in.
How It works
Persistence: The Agent is managed by the OS (Systemd on Linux, Service Manager on Windows). If the machine reboots, the Agent starts automatically.
Security: Established via an outbound-only MQTTS connection (Port 8883). No inbound firewall rules or VPNs are required.
Compatibility: Available for Windows, macOS, Linux (Standard & Alpine), and ARM64 (for Industrial PCs).
Installing the Native Agent
Configure and build
In the Functions Library, click the create Agent icon ().
Connectors: Select the specific tools (e.g., S7, SQL) you want this Agent to carry.
Target OS: Choose the operating system of the machine where the Agent will live.
Prefix (optional): Enter a prefix if you plan to deploy this exact file to multiple machines (e.g.,
milling-machine-). Each instance will then automatically generate its own unique ID (e.g.,milling-machine-abc123).Click Prepare for Download to compile and download your installer package.
Lost your file?
All agents you've built are backed up in the file server under the edge-connectors folder.
Run the installer
Move the package to the target machine, unzip, and run the installer.
Windows: Run the
.exeinstaller. It handles service registration and starts the Agent automatically.Linux/macOS: Run the provided install script. You will likely need
sudoprivileges to allow the Agent to register as a system daemon.
Automatic discovery
Once installed, the service starts immediately. The Agent and its selected connectors will appear in your library. You can now drag these functions onto the Flow Builder canvas. When using the production apps, they will execute locally on the computer the Agent is running (edge device).
Troubleshooting: Check Port 8883
The Agent requires port 8883 to be open for outbound traffic. If the Agent runs but does not appear in your Library, speak with your IT administrator to ensure this port is not blocked by a firewall.
Managing the Agent Service
Since the Agent runs as a service, it does not have a user interface window. To manage its state, use the standard OS tools:
Windows: Open the Services app (
services.msc), find the Heisenware Agent, and use the Start, Stop, or Restart controls.Linux: Use the command line to manage the daemon:
sudo systemctl status heisenware-agentsudo systemctl restart heisenware-agent
Using a prefix for fleet deployment
The prefix option changes how an Agent identifies itself, which is extremely useful for managing a fleet of similar machines or devices.
Without a prefix (default): The Agent has a built-in, unique ID. This means you can only run one instance of this installer at a time. You can move the installer to different computers, but they will all be recognized as the same single Agent in your library.
With a prefix: The Agent generates a new, unique ID upon its first launch in a specific directory. This allows you to deploy the exact same installer on multiple machines. Each one will run simultaneously, connecting as a separate entity in your Functions Library (e.g.,
milling-machine-abc123,milling-machine-xyz789), making it easy to manage entire fleets of identical endpoints.
Do not move an Agent folder that was created with a prefix after it has been run for the first time. It relies on a hidden ID file in its directory to maintain its unique identity.
Docker Agent
The Docker Agent provides the same core functionality as the Native Agent but is designed for containerized environments. It is the ideal choice for edge gateways or servers where you already manage your infrastructure using Docker.
Key Differences
Containerized execution: It runs within an isolated Docker container rather than directly on the host operating system.
Environment configuration: Unlike the Native Agent, credentials are not "baked in." You must provide them via environmental variables during startup.
Hardware & network access: To reach local networks, USB devices, or persist data, you use standard Docker features (like host networking or volume mounting).
Platform independent: It runs on any platform that supports Docker, providing a consistent deployment model across different hardware.
Where to get it?
Our Docker agent is available as a publicly downloadable image:
You can find a list of all available versions on Docker Hub.
How to use it
Setting up the Docker Agent is straightforward. You simply need to configure the following environment variables when running the container:
Retrieving Credentials
To get your HW_USERNAME and HW_PASSWORD, you must first add a VRPC Integration in the App Manager.
Example
For an account named my-company, an integration with the username agentRunner, and the password secret, the command would look like this:
Once the connection is successfully established, your console will show a confirmation screen (see below) indicating the agent is online and connected to the workspace.
Persisting Data
To ensure your data and configurations (such as created instances) persist across container restarts or updates, you must mount the /shared volume to a persistent location on your host machine.
Last updated
Was this helpful?