---
title: Use Telegraf configurations
description: Use Telegraf configuration files managed with Telegraf Controller to configure your running Telegraf agents.
url: https://docs.influxdata.com/telegraf/controller/configs/use/
estimated_tokens: 1938
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/configs/use/
date: '2026-09-21T14:28:25-06:00'
lastmod: '2026-09-21T14:28:25-06:00'
---
Use Telegraf Controller to centralize management of your Telegraf configurations
and keep your agents consistent across environments.
Apply the configuration by pointing your agents to the configuration URL.
* [Apply a configuration to an agent](#apply-a-configuration-to-an-agent)
* [Set substitution values](#set-substitution-values)
* [Set parameter values](#set-parameter-values)
* [Set environment variables](#set-environment-variables)
* [Auto-update agents](#auto-update-agents)
* [Use Telegraf Controller to build commands](#use-telegraf-controller-to-build-commands)
## Apply a configuration to an agent
When starting a Telegraf agent, use a `--config` flag with the
Telegraf Controller configuration TOML API URL—for example:
```bash
telegraf \
--config "http://localhost:8888/api/configs/xxxxxx/toml"
```
If the configuration has an[alias](/telegraf/controller/configs/aliases/), you can use the shorter
alias-based URL instead:
```bash
telegraf \
--config "http://localhost:8888/c/my-config-alias"
```
Agents can also retrieve multiple configurations bundled as a[configuration group](/telegraf/controller/config-groups/use/) with a
single `--config` URL.
> [!Note]
> A single Telegraf agent can use multiple configurations.
> Provide each with a distinct `--config` flag.
> Telegraf merges the configurations at runtime.
Telegraf retrieves and validates the configuration from Telegraf Controller
and then starts the `telegraf` process using the loaded configuration.
> [!Note]
> If Telegraf Controller serves over HTTPS, use an `https://` configuration URL
> and make sure the agent trusts the certificate. For details, see[Secure Telegraf Controller with TLS](/telegraf/controller/admin/secure-tls/).
### Retrieve a configuration with authorization enabled
If Telegraf Controller is configured to require authentication on the **Configs**API, define the `TELEGRAF_CONTROLLER_TOKEN` environment variable to authorize
Telegraf to retrieve a configuration:
```bash
export TELEGRAF_CONTROLLER_TOKEN=YOUR_TC_API_TOKEN
telegraf \
--config "http://telegraf_controller.example.com/api/configs/xxxxxx/toml"
```
Replace `YOUR_TC_API_TOKEN`with your Telegraf Controller API token. This token must have **read**permissions on the **Configs** API.
> [!Important]
> `TELEGRAF_CONTROLLER_TOKEN` requires **Telegraf 1.39+**. On earlier versions,
> use `INFLUX_TOKEN` instead. For details, see[Use API tokens with Telegraf agents](/telegraf/controller/tokens/use/#with-telegraf-agents).
## Set substitution values
Telegraf and Telegraf Controller let you[substitute values in your configuration files](/telegraf/controller/configs/substitute-values/)using parameters, constants, environment variables, and secrets.
* [Set parameter values](#set-parameter-values)
* [Set environment variables](#set-environment-variables)
[Constants](/telegraf/controller/configs/constants/) require no setup when
using a configuration; Telegraf Controller substitutes them automatically
when serving the TOML.
### Set parameter values
[Configuration parameters](/telegraf/controller/configs/substitute-values/#parameters)use the `&{param_name[:default_value]}` syntax in TOML configurations. Use
URL-encoded query parameters in your configuration URL to define parameter
values—for example:
##### Configuration TOML with a parameter
```toml
[[outputs.heartbeat]]
instance_id = "&{agent_id}"
# ...
```
##### Set the parameter value in the configuration URL
```bash
telegraf \
--config "http://localhost:8888/api/configs/xxxxxx/toml?agent_id=my-agent-123"
```
> [!Important]
> If you request a configuration without providing values for required
> parameters, Telegraf Controller returns an error.
### Set environment variables
[Telegraf environment variables](/telegraf/controller/configs/substitute-values/#environment-variables)use the `${VAR_NAME[:-default_value]}` syntax in TOML configurations. Set
environment variable values in the Telegraf agent’s environment before
starting Telegraf—for example:
##### Configuration TOML with an environment variable
```toml
[[inputs.http]]
urls = ["http://localhost:8080/metrics"]
[inputs.http.headers]
Authorization = "Bearer ${AUTH_TOKEN}"
```
##### Set the environment variable before starting Telegraf
```bash
AUTH_TOKEN=x00x0xx00xxxX0xXXx0000xxxX000x00XXxXx
telegraf \
--config "http://localhost:8888/api/configs/xxxxxx/toml"
```
## Auto-update agents
For agents to automatically recognize and load updates to their
configuration, include the `--config-url-watch-interval` with a duration value
that specifies how often the agent should check for updates—for example:
```bash
telegraf \
--config https://locahost:8888/api/configs/xxxxxx/toml \
--config-url-watch-interval 1h
```
In this example, the agent will check for configuration changes every hour and
automatically reload the configuration if the configuration has been updated.
## Use Telegraf Controller to build commands
Telegraf Controller provides a tool for building `telegraf` commands using
parameters, environment variables, auto-update functionality, and Telegraf[label selectors](/telegraf/v1/configuration/labels-selectors/).
To use this tool:
1. In the Telegraf Controller web interface, select **Configurations** in the
navigation bar.
2. Click the name of the configuration you want to use.
3. Click **Use this Configuration** to open the modal window.
4. *Optional*: To download a configuration and run it from your local filesystem
rather than having Telegraf retrieve it directly from Telegraf Controller,
enable the **Use local configuration file** option.
See more information [below](#download-a-configuration-to-your-local-filesystem).
5. Define substitution values and select options for your command:
* Set environment variable values
* Set parameter values
* Enable automatic configuration updates and specify the check interval
* Add label selectors to run certain plugins based on configuration labels
6. Click **Copy Commands** to copy the contents of the codeblock to your clipboard.
The tool provides commands for Linux, macOS, and Windows (PowerShell).
#### Some browsers restrict copying to clipboard ####
Your browser may not allow the **Copy Commands** button to copy to your
clipboard under the following conditions:
* You’re using an IP or domain name other than `0.0.0.0` or `localhost` and
* You’re using HTTP, not HTTPS
### Download a configuration to your local filesystem
With the **Use local configuration file** option enabled in the command builder,
Telegraf Controller lets you configure the directory path and file name to use
for the configuration.
1. Define substitution values and select options for your command:
* Set file details
* Set environment variable values
* Set parameter values
* Enable automatic configuration updates and specify the check strategy
* Add label selectors to run certain plugins based on configuration labels
2. Click **Download Config** to download the configuration to your local machine.
The downloaded TOML files uses the file name specified in the**File Details** tab and includes all the specified parameter replacements.
3. Click **Copy Commands** to copy the contents of the codeblock to your clipboard.
The tool provides commands for Linux, macOS, and Windows (PowerShell).
See [information about copying to your clipboard](#some-browsers-restrict-copying-to-clipboard).
