Linux · macOS · Windows · Kubernetes · Docker

Install the Tracix Collector

5 min read · Updated Oct 16, 2026View as Markdown

The Tracix Collector is an OpenTelemetry Collector distribution. Install it on each host or cluster you want to monitor. It enrolls with your workspace, pulls the configuration of the policy it belongs to, and starts sending telemetry.

The fastest way to install is to open Collectors in your workspace, select Deploy collector and copy the command it shows: it carries your installer host, the current stable version and the enrollment token of the policy you choose. This page explains each part of that command, so you can run it with confidence or script it.

Before you begin

You need three things

A Tracix workspace, an enrollment token for the policy the collector should join, and outbound HTTPS on port 443 from the host to the release host and your workspace. To get a token, open Collectors › Policies in your workspace, select the policy, then the Settings tab, and under Enrollment tokens use Show on an active token or Create token. See Enroll and manage collectors with policies.

Requirement	Supported
Operating system	Linux with systemd (Ubuntu 20.04+, Debian 11+, RHEL or CentOS 8+, Amazon Linux 2), macOS 12+, Windows Server 2016+ or Windows 10+
Architecture	x86_64 (amd64) or arm64
Privileges	`sudo` on Linux and macOS; an elevated (Administrator) PowerShell on Windows
Network	Outbound HTTPS (TCP 443), directly or through an HTTP proxy. Inbound only for what your policy listens on, such as syslog, NetFlow or SNMP traps

Your workspace IDThe eight characters that end your workspace's address: in acme-prod-a7k3p2q9.app.tracix.io it is a7k3p2q9. Paste the address to fill it in. Every command on this page uses it.

Install

Save the token to a file
Save the enrollment token in a file only root can read, such as /root/tracix-token. A file keeps the token out of your shell history and the process list. If you leave out --token-file, the installer prompts for the token with the input hidden.
2
Run the installer
bash
```
curl -fsSL https://charts.tracix.io/install.sh | sudo bash -s -- \
--endpoint https://agents-<workspace>.app.tracix.io \
--token-file /root/tracix-token
```
The installer checks that the host reaches the release host and your workspace, downloads the binary for your architecture, installs the systemd service and waits up to 90 seconds for the collector to enroll.
3
Check the result
Expected output
```
==> Installation complete!
==>   agent id:      <agent id>
==>   control plane: agents-<workspace>.app.tracix.io
```
If enrollment does not finish, the installer shows the collector's recent log and the likely cause, and exits with an error.

Save the token to a file
Save the enrollment token in a file only root can read, such as /var/root/tracix-token, or leave out --token-file to be prompted for it.

Run the installer

bash

curl -fsSL https://charts.tracix.io/install.sh | sudo bash -s -- \
--endpoint https://agents-<workspace>.app.tracix.io \
--token-file /var/root/tracix-token

The collector runs under launchd as a system daemon.

Check the result
The installer prints Installation complete! with the agent ID once the collector has enrolled.

Open an elevated PowerShell
Run PowerShell as Administrator. Windows PowerShell 5.1 and PowerShell 7 both work.

Run the installer

powershell

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072
$installer = Join-Path $env:TEMP 'tracix-install.ps1'
iwr https://charts.tracix.io/install.ps1 -UseBasicParsing -OutFile $installer
powershell -NoProfile -ExecutionPolicy Bypass -File $installer -Endpoint https://agents-<workspace>.app.tracix.io -TokenFile C:\tracix-token

The installer registers the TracixCollector Windows service and a firewall rule for the ports your policy listens on.

Add the chart repository

bash

helm repo add tracix https://charts.tracix.io && helm repo update

Store the credentials in a secret

bash

kubectl create namespace tracix
kubectl create secret generic tracix-collector-credentials \
--namespace tracix \
--from-literal=otlp-endpoint=https://otlp-http-<workspace>.app.tracix.io \
--from-literal=otlp-token="$TRACIX_ENROLLMENT_TOKEN" \
--from-literal=control-plane-url=https://agents-<workspace>.app.tracix.io \
--from-literal=agent-token="$TRACIX_ENROLLMENT_TOKEN"

Install the collector

bash

helm install tracix-collector tracix/tracix-collector \
--namespace tracix \
--version <version from the console> \
--set existingSecret=tracix-collector-credentials \
--set controlPlane.enabled=true \
--set clusterName=<cluster name>

The collector runs as a DaemonSet. The console's command also pins the image by digest and adds the settings your policy needs, such as pod logs.

Run the container

bash

docker volume create tracix-agent-state
docker run -d --name tracix-agent --restart unless-stopped \
-v tracix-agent-state:/var/lib/tracix-collector \
-v /proc:/hostfs/proc:ro -v /sys:/hostfs/sys:ro -v /:/hostfs/root:ro \
-e CONTROL_PLANE_URL=https://agents-<workspace>.app.tracix.io \
-e AGENT_TOKEN="$TRACIX_ENROLLMENT_TOKEN" \
-e OTLP_ENDPOINT=https://otlp-http-<workspace>.app.tracix.io \
-e OTLP_TOKEN="$TRACIX_ENROLLMENT_TOKEN" \
-e TRACIX_INSTALL_MODE=docker \
-e TRACIX_AGENT_NAME="$(hostname)" \
<collector image from the console>

The volume keeps the collector's identity across restarts. When your policy updates collectors automatically, the console's command also mounts the Docker socket so the collector can replace its own container.

Treat the enrollment token like a password

It enrolls collectors into your workspace. Do not paste it into chat or commit it to Git. The installer stores it in a file only the collector can read, and the collector deletes that file once it has enrolled. Revoking the token later stops new enrollments; collectors that already enrolled keep running.

Optional installer flags

Linux and macOS	Windows	What it does
`--token-file PATH`	`-TokenFile PATH`	Reads the token from a file instead of the command line.
`--proxy URL`	`-Proxy URL`	Sends the installer's downloads and the collector's traffic through an HTTP proxy. Pass it again on every re-run.
`--no-proxy LIST`	`-NoProxy LIST`	Hosts that bypass the proxy. Defaults to `localhost,127.0.0.1,::1`.
`--version VERSION`	`-Version VERSION`	Installs a specific release instead of the one the console promotes.
`--enable-obi`		Adds the eBPF permissions for zero-code tracing. Linux only.
`TRACIX_SKIP_PREFLIGHT=1`	`-SkipPreflight`	Skips the connectivity check.

Running the installer again upgrades the binary in place and enrolls again. The previous configuration is kept as a timestamped backup.

Confirm the collector enrolled

Check the service: systemctl status tracix-collector on Linux, sudo launchctl print system/com.tracix.collector on macOS, or Get-Service -Name TracixCollector on Windows.
In your workspace, open Collectors. The new collector appears with its policy and health once it has enrolled.
If nothing appears within a few minutes, see Troubleshoot the collector.

Next steps

Manage collectors with policiesPush configuration to groups of collectors Add an integrationConnect a package from the catalog Send application tracesPoint OpenTelemetry SDKs at Tracix

Report a problem with this page