---
title: Create a Telegraf configuration
description: Use Telegraf Controller to create Telegraf TOML configuration files. Upload existing configurations, write raw TOML in the Code Editor, or use the Telegraf Builder visual interface to manage and configure plugins.
url: https://docs.influxdata.com/telegraf/controller/configs/create/
estimated_tokens: 976
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/configs/create/
date: '2026-09-25T09:41:40-06:00'
lastmod: '2026-09-25T09:41:40-06:00'
---

Create a configuration to define how Telegraf collects, processes, and writes
metrics. Telegraf Controller stores the configuration as TOML that you can use
across agents. Upload existing configurations, write raw TOML in the Code
Editor, or use the Telegraf Builder visual interface to manage and configure
plugins.

## Create a configuration

1. In the Telegraf Controller web interface, select **Configurations** in the
   navigation bar.
2. Click  **Add Config**.
3. Enter a configuration name and optional description.
4. *(Optional)* To assign[aliases](/telegraf/controller/configs/aliases/) to the configuration,
   click  **Add Alias** and enter an alias that
   follows the[naming rules](/telegraf/controller/configs/aliases/#alias-naming-rules).
5. Use the Telegraf Controller [Code Editor](#use-the-code-editor) or[Telegraf Builder](#use-the-telegraf-builder) to provide or build the
   Telegraf configuration TOML.
6. Click **Create Configuration**.

When you create a configuration, Telegraf Controller records it as the first
version in the configuration’s[version history](/telegraf/controller/configs/versions/).

### Use the Code Editor

The Telegraf Controller **Code Editor** is an in-browser TOML editor that lets
you upload or manually write Telegraf configuration TOML.

*For detailed information about using the Code Editor, see[Use the Code Editor](/telegraf/controller/configs/ui/code-editor/).*

<img width="948" src="/img/telegraf/controller-code-editor.png" alt="Telegraf Controller Code Editor">

### Use the Telegraf Builder

The **Telegraf Builder** is a visual interface for adding and configuring
Telegraf plugins in a Telegraf configuration. The Telegraf Builder is
currently a beta feature.

*For detailed information about using the Telegraf Builder, see[Use the Telegraf Builder](/telegraf/controller/configs/ui/telegraf-builder/).*

<img src="/img/telegraf/controller-telegraf-builder.png" alt="Telegraf Builder in Telegraf Controller" width="948">

> [!Warning]
> #### The Telegraf Builder does not support all Telegraf plugins
>
> We are in the process of adding support for more Telegraf plugins in the
> Telegraf Builder. You can use plugins that are not currently supported by the
> builder, but you must add and edit them with the Code Editor.

## Heartbeat output plugin

When adding a configuration, Telegraf Controller prepopulates the
configuration with a [Telegraf heartbeat output plugin](/telegraf/v1/output-plugins/heartbeat/).
This plugin reports agent information back to the Telegraf Controller heartbeat
API and lets you monitor the health of your deployed Telegraf agents.

```toml
[[outputs.heartbeat]]
url = "http://localhost:8000/agents/heartbeat"
instance_id = "&{agent_id}"
interval = "1m"
include = ["hostname", "statistics", "configs"]
token = "${TELEGRAF_CONTROLLER_TOKEN}"
```

To monitor agents with Telegraf Controller, include a heartbeat plugin in
your Telegraf configurations.

> [!Important]
> #### Authorize heartbeats using an API token
>
> If Telegraf Controller requires authorization on the **Heartbeat** API,
> include the `token` option in your heartbeat plugin configuration.
> Provide a Telegraf Controller token with **write** permissions on the**Heartbeat** API.
>
> We recommend defining the `TELEGRAF_CONTROLLER_TOKEN` environment variable
> when starting Telegraf and using it to define the token in your heartbeat
> plugin. On **Telegraf 1.38.x or earlier**, use `INFLUX_TOKEN` instead. For
> details, see [Use API tokens](/telegraf/controller/tokens/use/#for-heartbeat-requests).

## Next steps

* [Substitute values](/telegraf/controller/configs/substitute-values/)to keep configurations portable across environments.
* [Apply the configuration](/telegraf/controller/configs/use/) to your
  Telegraf agents.

#### Related

* [Substitute values in configurations](/telegraf/controller/configs/substitute-values/)