This guide will walk you through the installation process for Heex Agent on your system.

​
Prerequisites

  • Heex Application requirements
  • USER_SECRET_KEY. Should be accessible on your personnal space on the heex cloud platform under the section Api Keys.
  • If you would like to deploy your own packaged Heex Agent, please ensure that you did this step.

​
Installation Steps

  1. Download the Installer: Download the latest release from your command line.
If your system is not yet supported, contact us and we will work with you to provide you an adequate installer. Ubuntu 20.04, 22.04 and 24.04 on arm64 and x86_64 are the ones we have tested the installer on. In your terminal, run the following (replace <USER_SECRET_KEY> by your personnal user secret key): 
curl --fail -X GET "https://api.app.heex.io/v1/installer/download?operating_system=$(. /etc/os-release && echo ${ID}_${VERSION_ID}_$(uname -m))" \
     -H "secret_key: <USER_SECRET_KEY>" -o heex-installer && chmod +x heex-installer
Once the download is complete, install Heex on your system. To do so, you can either create a new system directly using the heex-installer, or you can install an existing system that has already been set up:
  • create a new system before installing it
./heex-installer --api-key <USER_SECRET_KEY> --name <system_display_name> --system-category <category_value>
  • install an existing system
./heex-installer --api-key <USER_SECRET_KEY> --system-id <ID of system>

​
What will the Installer do ?

The installer will check if a system with the specified name already exists; if not, it will create a new system with the provided name. It will attempt to fetch your custom Heex Agent, or install the default Heex Agent, which includes only the Heex Kernel and our builtin implementations (ie RDA). The installer will then install the runtime environment and download the associated configuration file, if defined. The installation status will be reported on the web platform.
⚠️ Warning: system name with special characters If your system name contains special characters (i.e ’), use double quotes before and after your names. For example, for a system called test’s system, provide that as --name “test’s system”.
📝 Note: You can call ./heex-installer --help to list the different --system-category possible values, and more.

​
Heex Installer Command Line Options

OptionDescription
--help, -hShow this help message and exit.
--version, -vShows the version of the heex-installer.
--system-id, -si[optional] System ID. If not given, you will create a new system.
--api-key, -kAdd your user api secret_key which can be found on the cloud.
--execution-mode, -x[optional] Execution mode: ‘background’ for background process or ‘service’ (default).
--name, -n[mandatory if no system-id provided] System code name (name display for your system in the UI). If the name of your system contains special characters such as ’, enclose with double quotes "". For example, —name “John’s dev station”.
--system-middleware, -mid[optional] System middleware. To see available options, please run ./heex-installer --help.
--system-category, -cat[mandatory if no —system-id given] System category. To see available options, please run ./heex-installer --help.
--installed-version, -iv[optional] Forces the installed agent version to given one. Example: --installed-version 2025.7.1

​
Verification

To confirm that Heex is correctly installed, navigate to the status page of your system on Heex Cloud while selecting the appropriate system. You should see the Agent runtime version that was installed in your system. installer_system_status

​
Using a PROXY

You can configure and use Proxies with the heex-installer the same way as with the CLI. If you intend to do so, please take a look at how to use a Proxy with the CLI.