Skip to main content

Installation

Stealthium is designed to run on groups of machines and report on them, including their GPUs, and introspecting down into the KVM guests that are running on the system. Different customer setups require different configuration but generally speaking they result in the same basic configuration: A Stealthium Client running on a machine that sends data to Stealthium Cloud for analysis. This makes the client light and unobtrusive while providing deep insight into the events in the overall cluster.

Debian (Ubuntu) Package​

A common setup for deploying on bare metal machines is to create a "golden image" with all the utilities needed in those machines. Stealthium supports this setup by providing a Debian package repository that can be used to preinstall Stealthium on those images.

Install the Stealthium Repo​

For easy management of dependencies and getting the latest version of the Stealthium Client you can use Apt to download the latest version.

curl https://packages.stealthium.io/stealthium.key | sudo apt-key add -
echo "deb https://packages.stealthium.io/ubuntu/noble noble main" | sudo tee /etc/apt/sources.list.d/stealthium.list
sudo apt-get update
sudo apt-get install -y stealthium
One package at a time

The stealthium client and the stand-alone stealthium-agent package conflict — installing one removes the other. Use stealthium for hosts reporting to Stealthium Cloud, and stealthium-agent only for stand-alone evaluation.

Configure Stealthium​

The Stealthium Client requires an API key from Stealthium Cloud. The key is a plain UUID — the client validates the format and refuses to start with anything else. To add it to your golden image:

echo "[orion]" | sudo tee /etc/stealthium/config.toml
echo 'api_key = "YOUR-KEY-HERE"' | sudo tee -a /etc/stealthium/config.toml

A per-machine ID will also be generated once the image is deployed by the Stealthium Client. It is not critical that these are saved, but they may change if a machine is reimaged.

Docker​

Stealthium's collector can be installed as a Docker container either downloaded or pointing to Stealthium's Docker registry.

Pull the image​

To get the image locally you first need to configure your login to the repository:

docker login registry.backend.stealthium.io \
  -u '<your username>' \
  -p '<your password>'

This will save your credentials for Docker and allow you to get the current image, as well as updates as we add features and fix bugs. Next you can pull the image.

docker pull registry.backend.stealthium.io/stealthium/release:latest

You now have the image in your local repo.

Running the image​

To run the Stealthium image you'll need to set it up as a privledged container, so that it can connect to the kernel, and with various volume mappings to get information from the host system. We strongly recommend you configure your Stealthium collector the same as this example.

docker run -d \
  --name stealthium-agent \
  -e STEALTHIUM_API_KEY="YOUR_API_KEY" \
  -e LD_LIBRARY_PATH="/host-usr/lib:/host-usr/local/lib:/home/kubernetes/bin/nvidia/lib64" \
  --restart always \
  --privileged \
  --cap-add NET_ADMIN \
  --pid host \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /lib/modules:/lib/modules:ro \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /sys/kernel/tracing:/sys/kernel/tracing \
  -v /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:rw \
  -v /etc/stealthium:/etc/stealthium:rw \
  -v /usr:/host-usr:ro \
  registry.backend.stealthium.io/stealthium/release:latest

You should now be able to see the Stealthium agent running on your system

docker ps

Helm​

For Kubernetes installs that use Helm we provide a chart that can install the Docker container (same as above). The Helm charts are stored in the same repository as the containers.

helm upgrade --install stealthium-agent \
  oci://registry.backend.stealthium.io/stealthium/release/stealthium-agent \
  --namespace stealthium \
  --create-namespace \
  --set stealthium.apiKey=API-KEY \
  --set registryCredentials.registry=registry.backend.stealthium.io \
  --set registryCredentials.create=true \
  --set registryCredentials.username='registry-user' \
  --set registryCredentials.password='registry-password'

Without --version, Helm installs the latest published chart. Chart versions follow Stealthium release versions with no v prefix; to inspect the latest before installing:

helm show chart oci://registry.backend.stealthium.io/stealthium/release/stealthium-agent

Repository Setup​

You can configure your login to the Stealthium repository using the login command:

helm registry login registry.backend.stealthium.io