Install collectors

You install a server fleet's collectors from its Deploy Groups tab. Every install option is preconfigured with the fleet's connection endpoint, so a collector connects to the right fleet and joins the deploy group it was deployed from.

Collectors run on Linux, on arm64 or amd64 (x86_64), as a container or directly on a host. To manage collectors inside a Kubernetes cluster, use a Kubernetes fleet instead; this page covers server fleets.

Open the install dialog

Open the fleet, select the Deploy Groups tab, and select Install on the group to install into. The Install collectors dialog opens, titled with the group's name. The fleet header's Install collector button and the setup checklist's Install step open the same dialog for the Default group. Select the Platform that matches how you run the collector:

Container image (GHCR) is selected by default and works on both architectures. The server targets combine an architecture, arm64 or amd64 (x86_64), with the target. The Server: Import Configuration targets appear when the group has no assigned configuration yet, for adopting an existing collector; the other targets appear once the group has a configuration to deploy.

Except for the import targets, every install starts with a placeholder configuration and pulls the group's assigned configuration once the collector connects. An import install instead reads the collector's existing configuration and reports it to Telflo, which adopts it into the fleet's Default deploy group. Import installs are available from the Default group only: a group without an assigned configuration shows Missing configuration, and its Install button is disabled until a configuration is assigned.

Container image

The container image target runs Telflo's prebuilt collector image, published for each supported collector version on both architectures. There is nothing to build or download: the dialog shows a run command for the group.

1. Optionally enter a Collector display name. It is shown in Fleet management; left empty, a name is generated.
2. Select Reveal & copy command. The command is completed with the fleet's endpoint, its install token, and the deploy group's identifier, and copied to your clipboard. Each reveal is recorded in the fleet's token audit log, the same as viewing a token.
3. Run the command on a host with Docker.

The command mounts a named volume that preserves the collector's identity across restarts and upgrades. Without the volume, every time the container is re-created, including upgrades to a new image tag, the collector enrolls as a new instance and the old entry goes stale. No ports are published by default; add port mappings to the command when a receiver listens on a port your applications need to reach.

To upgrade, reveal the command again once the group's configuration targets a new collector version, and re-run it: the image tag follows the configuration's collector version, and the volume keeps the collector's identity. If the configuration's collector version is deprecated, the command is refused; select a supported collector version in the editor and publish again.

Quick Deploy

For the server targets, Quick Deploy generates a single command, unique to the deploy group, that you paste on the target host. It downloads the bundle, sets the fleet's token, and starts the collector in one step. Copy the command from the dialog: the token is masked on screen, and the copied command contains the real value, so treat the whole command as a secret.

The Install as a systemd service (starts on boot) option is selected by default. With it selected, the Quick Deploy command registers a telflo-supervisor.service unit that starts the collector on boot and restarts it after a crash. The systemd install is available through Quick Deploy only; clear the option to download the raw bundle and run it yourself.

The Quick Deploy URL inside the command expires after 24 hours, so generate a fresh command for each host. Active Quick Deploy links can be extended or revoked from the Install Links section of the fleet's Tokens tab. See Tokens & security.

Download

For the server targets, Download generates a zip with the minimal set of files to run the collector and a README. The bundle itself contains no token. After the download, the dialog shows a Set the fleet token, then deploy step: on the target host, set the OPAMP_TOKEN environment variable to the value the dialog provides before running the bundle's start script. The start script stores the token in an opamp.env file next to it, readable by root only, so restarts pick it up automatically; re-run the script with a new OPAMP_TOKEN value to replace it. The start script also accepts an optional display name for the collector; left unset, a name is generated, and the collector can be renamed in the fleet later.

Follow the README in the bundle for the exact steps.

After installation

A collector connects to Telflo and appears on the fleet's Collectors tab, usually within a minute. It joins the deploy group it was deployed from, pulls its assigned configuration, and applies it. Track its progress on the fleet detail page.