Install collectors

You install a server fleet's collectors from its Deploy Groups tab, or with telflo fleet install from the CLI. 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. The server bundle installs on this page run configurations on OpenTelemetry Collector Contrib: the Server: All In One bundle downloads the Contrib collector binary, while the Server and Server: Import Configuration bundles download only the supervisor and use the collector binary already on the host. The configuration environment variable inputs apply to Contrib configurations. A ClickStack configuration, available in private preview, deploys through a Kubernetes supervisor fleet; on a server fleet, only the container image option runs Telflo's ClickStack collector image. See ClickStack configurations.

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) — pull and run is selected by default and works on both architectures, unless a server platform was saved by an earlier Download on this fleet, in which case that platform is reselected. 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.

Configuration environment variables

If the deploy group's assigned configuration reads environment variables with ${env:NAME} and no default, the dialog lists them under Configuration environment variables (optional). The list is loaded when the dialog opens, before any credential is revealed. Each variable has a checkbox; all start unchecked and marked set on the host. Check a variable to enter its value here, or leave it unchecked to set it on the host before the collector starts. Variables the install already sets, such as OPAMP_TOKEN and COLLECTOR_GROUP_ID, and references with a :-default fallback are not listed.

Included values are composed into the artifact for the selected platform: -e NAME='value' lines in the container run command, or export NAME='value' lines in the start script of a downloaded bundle or a Quick Deploy bundle. Values in the run command and in a downloaded bundle are not stored by Telflo. A Quick Deploy link is different: the values you included are saved with the link so the host can fetch the bundle, and the link's View button under Install Links on the Tokens tab opens a Deployment options dialog that shows them, including after the link expires or is revoked. When a value is a secret, leave the variable unchecked and set it on the host, or use Download. The inputs apply to configurations on OpenTelemetry Collector Contrib.

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, the deploy group's identifier, and the group's volume mounts, 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, followed by any volume mounts declared on the deploy group. 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.

Each variable you included under Configuration environment variables becomes a -e NAME='value' line after the token line. A variable included without a value appears as -e NAME='<value>', and the dialog asks you to replace each <value> placeholder before running the command.

Volume mounts for container installs

A collector in a container sees only the paths mounted into it. When the deploy group's configuration reads host files with a filelog receiver, or keeps checkpoints with a file_storage extension, and no mount on the group covers the path, the container image section shows This config reads paths the container won't see above the Run command. Each path is listed with what happens without a mount, for example filelog reads /var/log/app, but no volume mounts it — the container will see an empty directory. or file_storage writes /var/lib/otelcol, but no writable volume mounts it — checkpoints are lost on restart. The notice cannot add mounts here, because a mount belongs to the deploy group and would change every other install for it: close the dialog, add the paths as volume mounts on the group, then reveal the command again, as the notice's last line says.

Each mount the group declares becomes a -v <host path>:<mount path> line in the run command, with :ro appended for a read-only mount, after the -v telflo-opamp:/app/opamp line and before the -e lines. The Quick Deploy and Download installs ignore the group's mounts: a collector installed on the host reads its paths directly. A mount whose path contains characters other than letters, digits, ., _, -, and /, or a .. segment, is dropped from the command. The command produced by telflo fleet install <fleet-id> --platform docker and by POST /fleets/{id}/install includes the same mounts.

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.

For the All In One and Server targets, each variable you included with a value under Configuration environment variables is written into the bundle's start_supervisor.sh as an export NAME='value' line, for Quick Deploy and Download alike. Variables you left unchecked must be exported on the host before the start script runs.

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 with --OPAMP_SERVER_NAME='name'; left unset, the host's hostname is used, and the collector can be renamed in the fleet later.

Follow the README in the bundle for the exact steps.

Install from the CLI or API

The run command and the Quick Deploy command can be produced without the dialog, for example from a provisioning script. telflo fleet install <fleet-id> --platform docker prints the container run command for the fleet's Default deploy group, or the group named by --deployment <id>; --server-name <name> sets the collector display name. telflo fleet install <fleet-id> --platform linux prints the Server: All In One Quick Deploy command for amd64, or arm64 with --arch arm64, installing into /etc/otelcol unless --root-path says otherwise; it installs the systemd service unless you pass --no-systemd, which runs the supervisor in the foreground instead. The link inside the command expires after 24 hours, the same as a Quick Deploy link from the dialog. The Server, Server: Import Configuration, and Download targets are not available this way.

--env NAME=value, repeatable, supplies a configuration environment variable the same way the dialog does. A variable the configuration reads but you did not supply appears as a <value> placeholder in the run command, and is left out of the Linux bundle for you to set on the host; the notes printed with the command name each one. The command goes to standard output and the notes to standard error, so telflo fleet install ... > install.sh captures only the command. The output embeds the fleet's install token, so treat it like a revealed command; each call is recorded in the fleet's token audit log. POST /fleets/{id}/install returns the same command with the parts it was composed from. See CLI commands and API endpoints.

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.