Linux · macOS · Windows · Kubernetes · Docker

Upgrade collectors

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

Tracix promotes one collector release at a time as the stable release. The Collectors page compares every collector with it, so you can upgrade collectors one at a time, in bulk, or let each policy keep its collectors current on its own.

How releases reach collectors

Every release is published for Linux, macOS and Windows on amd64 and arm64, and as a container image for Docker and Kubernetes. The console's install commands and every upgrade use an exact version, and containers an exact image digest, never a moving tag such as latest.

Upgrades are verified before anything changes:

A host collector downloads the new build over HTTPS, checks its SHA-256 checksum, and has the new binary validate the configuration it is running before it replaces the old one.
A container upgrade uses the image digest Tracix pinned for the release.
Tracix never moves a collector to an older version.

Check which collectors are out of date

Open Collectors. The Version column shows what each collector runs, and the Release column shows how it compares with the stable release:

Release column	Meaning
Upgrade	A newer stable release is available and Tracix can upgrade this collector.
Retry	The last upgrade failed. Select it to try again.
Updating	An upgrade is in progress.
manual	A legacy or unmanaged installation. Reinstall it once with the current installer or command to get managed upgrades.
current	The collector runs the stable release.
ahead	The collector runs a newer version than the stable release.
unknown	Tracix can't compare the collector's version with the stable release.

Upgrade from the console

Pick the collectors
To upgrade one collector, select Upgrade in its row, or open it and select Upgrade to with the version. To upgrade several, select them and choose upgrade above the list; collectors that are already current, already updating or managed by hand are skipped.
Watch the progress
The row shows Updating while the collector downloads, validates and applies the release. Host collectors restart onto the new binary; containers are replaced, as the table below explains.
Check the result
The Version column shows the new version and the Release column shows current. If the upgrade failed, the row offers Retry, which starts a new attempt.

Each upgrade request is attempted once, and a failure stays visible until you retry it. Policies that update their collectors automatically also retry failed upgrades on a schedule, described below.

Update collectors automatically

Each policy has an Automatically update managed collectors setting. It is on by default for new policies. Find it on the policy's Settings tab under Collector updates.

When it is on, Tracix upgrades every managed collector on the policy to each new stable release. Plan for that: a new release can reach all of the policy's managed collectors within about a minute. If you want to try releases on a few hosts first, keep those hosts on a separate policy and turn the setting off on the rest.

If an automatic upgrade fails, Tracix tries again 15 minutes, 1 hour and 4 hours after each failed attempt. After the fourth failure the upgrade stays failed until you select Retry, which starts over. Without automatic updates, failed upgrades wait for you to retry them.

What an upgrade does on each platform

Platform	Upgrade	If it fails
Linux	Swaps the binary in place and lets systemd restart the service. Keeps the old binary as `/opt/tracix-collector/bin/tracix-collector.previous`.	Restore the previous binary by hand. See below.
macOS	Swaps the binary in place and lets launchd restart the daemon. Keeps the old binary as `/usr/local/bin/tracix-collector.previous`.	Restore the previous binary by hand. See below.
Windows	Stops the service, replaces the binary and starts it again. Keeps the old binary as `tracix-collector.exe.previous`.	Puts the previous binary back if the service fails to start.
Kubernetes	Patches the collector's DaemonSet to the release's image digest. The rolling update replaces one node's pod at a time.	The rest of the fleet keeps running if a new pod never becomes ready.
Docker	Pulls the release's image by digest, checks the digest, then recreates the container with the same name, volumes and networks. Needs the Docker socket mounted.	The old container keeps running when the pull or the check fails.

Docker upgrades need the Docker socket

A Docker collector upgrades itself only when it was started with the Docker socket mounted, which the console's Docker command does while the policy updates collectors automatically. The socket gives root-equivalent access to the host. Without it, the collector shows manual: upgrade it by running the install command again, as described below.

On Kubernetes, Helm or your GitOps tool still owns the DaemonSet. If it is pinned to an older image digest, it can undo an upgrade the console started, so update the pinned values when you upgrade.

Restore the previous binary

If a new binary on Linux or macOS can't start, put the previous one back and restart the service. Turn off Automatically update managed collectors on the policy first if you want to keep the collector on the older version for now; otherwise Tracix retries the upgrade.

bash

sudo systemctl stop tracix-collector
sudo cp /opt/tracix-collector/bin/tracix-collector.previous /opt/tracix-collector/bin/tracix-collector
sudo systemctl start tracix-collector

bash

sudo cp /usr/local/bin/tracix-collector.previous /usr/local/bin/tracix-collector
sudo launchctl kickstart -k system/com.tracix.collector

Upgrade by hand

Use these when a collector shows manual, or when you install pinned versions yourself.

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.

Run the installer again, with the version the console shows for the stable release. It upgrades the binary in place and keeps the collector's identity, and the previous configuration is kept as a timestamped backup.

bash

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

Run the installer again, with the version the console shows for the stable release.

bash

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

Run the console's PowerShell install command again from an elevated PowerShell. It carries the stable version as -Version.

Upgrade the Helm release to the chart version and image digest of the stable release, which the console's Kubernetes install command shows.

bash

helm repo update
helm upgrade tracix-collector tracix/tracix-collector \
--namespace tracix \
--reuse-values \
--version <chart version from the console> \
--set-string image.digest=<image digest from the console>

Remove the old container, then run the console's Docker command again. It pins the new image by digest, and the tracix-agent-state volume keeps the collector's identity.

bash

docker rm -f tracix-agent
# then run the Docker command from Deploy collector on the Collectors page

Next steps

Manage collectors with policiesTurn automatic updates on or off per policy Troubleshoot the collectorFix a collector that fails after an upgrade Release notesWhat changed in each release

Report a problem with this page