Beatbox Setup

Integration-level management tasks are only available to users with the correct permissions. See the Users documentation for more details.

Beatbox is a software version of the flow-server that is installed on-premises behind your own firewall. Flows can be deployed to Beatbox, but there are no Heartbeat features (like monitoring) available directly on Beatbox. However, Beatbox connects securely to the centralized flow-server, so any Beatbox-deployed flows can still be viewed and monitored in the same Heartbeat interface that you’ve always used.

System Requirements

Beatbox can only be installed on a 64-bit version of Linux. This can be on a dedicated server or virtual machine but must meet the following criteria:

Hardware Minimum requirements


Dual 64-bit processors. More processors allow for increased, simultaneous flow executions.


4 GB of RAM. More RAM allows for increased, simultaneous flow executions and might be required to process large data payloads.

Hard disk

500 MB for run-time and configuration, 10 GB for logs and data storage. SSD based storage is recommended for the best performance.

You will also need to install Docker (with Docker Compose), version 20.10.0 or higher.

Creating an ID

To get started with Beatbox, first create an ID in Heartbeat. Select Beatbox from the left-hand navigation menu, which will display the following page:

The list of beatbox instances includes a name, auto-generated ID, and status.

Select the Create button in the top-right corner and enter a name. An ID is automatically created afterwards. This is the ID that you will add to your Beatbox environment variables in the next step.

Beatbox IDs cannot be deleted. Contact Utilihive Support if you need to delete an ID.

Installing Beatbox

Utilihive Support will provide two things you need to install Beatbox: an archive of the Beatbox setup files and credentials to log into the private Docker registry. On your Linux machine, extract the setup files in the directory where you want the data to be stored. In a terminal window, navigate to the setup directory and execute the following command:


This script creates the needed directories for local data (e.g., data/beatbox/logs) and confirms that you can log into Docker. Note that you might need to run the script with sudo if permissions are an issue.

The only other file you should touch at this time is the beatbox.env file. Open this file and fill in the following properties:

Property Description


The ID that was generated in Heartbeat.


The ownerId of your organization.


The remote API endpoint that logs and metrics are sent to. Provided by Utilihive Support.


The environment that logs and metrics are sent to. Normally set to development, test, stage, or production.


The index that logs are sent to. Provided by Utilihive Support.


The username for sending logs. Provided by Utilihive Support.


The password for sending logs. Provided by Utilihive Support.


The username for sending metrics. Provided by Utilihive Support.


The password for sending metrics. Provided by Utilihive Support.


The decryption key for any credentials stored in the config/ file.


The password to use when initializing the local database. This is a password of your choosing but should not be changed after the first installation.


The username of the Agent user for sending flow details.


The password of the Agent user for sending flow details.

Afterwards, run the following command to download and start the necessary containers:

docker compose up -d

You can verify that Beatbox is running by making an HTTP request on the Beatbox machine to http://localhost:8090/actuator/health. In Heartbeat, the Beatbox status will display a green checkmark if the metrics endpoints are successfully connected.

If you plan to expose any HTTP-based services in your flows, the firewall on the Beatbox machine needs to have port 8080 open. You can accomplish this with a command such as ufw allow 8080.

Managing Beatbox

Beatbox flows and resources are deployed differently than using the SDK. See the Beatbox Deployments documentation for specifics.

After you deploy a flow to Beatbox, its flow traces will appear in Heartbeat alongside your other flows. See the Flow Traces documentation for information on filtering Beatbox data. If Agent user credentials were provided, deployed flows will also appear in the Flows page in Heartbeat.