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.
  • If you would like to deploy your own 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, 24.04, and Debian 12 on arm64 and x86_64 are the one 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

​
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.

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”.

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>

📝 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.
--system-id, -si[optional] System Identification Number. If not given, you will create a new system.
--api-key, -k[mandatory] User secret API key.
--execution-mode, -x[optional] Execution mode: background or service (defaults to service).
--name, -n[mandatory if no system_id provided] System display name (name of your system in the UI).
--system-middleware, -mid[optional] System middleware: value should be an integer. You can use ./heex-installer --help to list all the available middlewares.
--system-category, -cat[mandatory if no system_id provided] System category: value should be an integer. Example for RAIL: --system-category 5. You can use ./heex-installer --help to list all available categories.

​
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.

​
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.