Docs The addons agent Install

Install

One command on a fresh Linux box, after you have verified what you are about to run.

Get a release and verify it
Download the tarball and the SHA256SUMS and SHA256SUMS.sig beside it from the addons download table. Get the release public key, addons-release.pub, and check the sums file was signed by this project, then that your tarball matches it. Skipping either lets a tampered tarball and a tampered checksum file agree with each other.
```
printf '[email protected] namespaces="pingtower-addons-release" %s\n' \
  "$(cut -d' ' -f1,2 addons-release.pub)" > allowed_signers
ssh-keygen -Y verify -f allowed_signers -I [email protected] \
  -n pingtower-addons-release -s SHA256SUMS.sig < SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
```
Addons signatures live in their own pingtower-addons-release namespace, so an addons signature can never pass as a daemon release or vice versa. Needs stock OpenSSH 8.2 or later.
Unpack and run the installer
```
tar xzf addons_<version>_linux_<arch>.tar.gz
cd addons_<version>_linux_<arch>
sudo ./install.sh --dry-run   # prints the exact action list, changes nothing
sudo ./install.sh
```
This creates an unprivileged addons system user and group, installs the binary to /usr/local/bin/addons, creates /etc/addons and /var/lib/addons/spool, writes the example config to /etc/addons/agent.yaml and a token stub to /etc/addons/agent.env (only if they do not already exist), and installs and enables the addons.service systemd unit.
Every tarball carries a signed MANIFEST.sha256 covering its own files. The installer verifies that signature and every file’s hash before it creates the user or writes anything, and refuses outright on any mismatch.

Provision the agent’s source token

Each agent is one source on the tower. Create it under the project it should report to; the response carries the pti_ token, shown once.

curl -s -X POST https://api.pingtower.com/v1/projects/<project>/sources \
  -H "Authorization: Bearer ptk_…" \
  -d '{"name": "probe-fra-01"}'
# → {"name":"probe-fra-01","token":"pti_<tenant>_…"}

sudo $EDITOR /etc/addons/agent.env
# PINGTOWER_INGEST_TOKEN=pti_<tenant>_…

Edit the config
/etc/addons/agent.yaml starts as the example: a made-up agent id and one httpcheck against example.com. Replace them with the real identity and the checks this box should run. See Configure.
Start it and confirm events arrive
```
sudo systemctl enable --now addons
journalctl -u addons -f
```
Within one sample interval the checks show up as events on the project. Within one heartbeat interval, five minutes by default, the agent’s own heartbeat does too.

Try one check before installing anything

addons check runs a single check once and prints the event it would send. Add --report to send it. The token comes from the environment, never a flag, so it stays out of shell history.

export PINGTOWER_INGEST_TOKEN=pti_<tenant>_…
export PINGTOWER_URL=https://api.pingtower.com   # or your own box
addons check httpcheck --param url=https://example.com --report
# UP in 101ms — sent, template f5b97ca2801d, alerted

Upgrading

Same installer, newer tarball. It replaces only the binary and the unit file, restarts the service if it was running, and leaves the config, the token and the spool exactly as they were. A partial spool from before the upgrade drains normally once the new binary starts.

Container

There is no published image yet. The repository’s Dockerfile builds one from a distroless base, running as an unprivileged user; mount the config and the env file and give it a writable volume for the spool. Privileged addons and kernel-attached sensors need the matching mounts and capabilities.