---
title: Install Telegraf Controller
description: Download and install Telegraf Controller on Linux, macOS, and Windows operating systems.
url: https://docs.influxdata.com/telegraf/controller/install/
estimated_tokens: 5204
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/install/
date: '2026-04-30T13:05:57-06:00'
lastmod: '2026-04-30T13:05:57-06:00'
---

#### Telegraf Controller is in Public Beta

Telegraf Controller is in public beta and will be part of the future Telegraf Enterprise offering.
While in beta, Telegraf Controller is **not meant for production use**.
The Telegraf Controller documentation is a work in progress, and we are actively
working to improve it. If you have any questions or suggestions, please[submit an issue](https://github.com/influxdata/docs-v2/issues/new?labels=Telegraf%20Controller).
We welcome any and all contributions.

Beta expectations

* **No configuration or agent limits**  
  While in beta, Telegraf Controller doesn't place any limits on the
  number of configurations you can store or the number of Telegraf
  agents you can track. However, upon being generally available,
  the free distribution of Telegraf Controller will have limits
  introduced, with the option to increase limits through a
  Telegraf Enterprise license.
* **Potential breaking changes**  
  While in beta, we will do our best to no longer make breaking
  changes to Telegraf Controller, however, they may be necessary.
  The majority of changes we make will be additive and non-breaking,
  and include any necessary migrations. When we do need to make
  breaking changes, we will do our best to communicate them clearly
  and in advance to minimize disruption.
* **Flexible release schedule**  
  While in beta, we will continue to create new releases of
  Telegraf Controller, but likely at irregular intervals. We will provide[Telegraf Controller release notes](/telegraf/controller/reference/release-notes/)to make it easy to track updates.

Provide beta feedback

* Use the **Feedback** feature in the Telegraf Controller UI.
* [Join the InfluxDB Community Slack](https://influxdata.com/slack) and post feedback in the **#telegraf-enterprise-alpha** channel.
* Post feedback in the [InfluxData Community](https://community.influxdata.com).

Join our public channels

* [InfluxDB Community Slack *(Preferred)*](https://influxdata.com/slack)
* [InfluxData Community](https://community.influxdata.com)
* [InfluxDB Subreddit](https://reddit.com/r/influxdb)

Telegraf Controller is a web-based configuration management system for Telegraf
agents. It provides a user-friendly interface for managing Telegraf
configurations, monitoring agents, and organizing plugins.

* [System Requirements](#system-requirements)
* [Review the EULA](#review-the-eula)
* [Download and install Telegraf Controller](#download-and-install-telegraf-controller)
* [Set up your database](#set-up-your-database)
* [Configure Telegraf Controller](#configure-telegraf-controller)
* [Set up the owner account](#set-up-the-owner-account)
* [Access Telegraf Controller](#access-telegraf-controller)

## System Requirements

* **Operating Systems**: Linux, macOS, Windows
* **Architecture**: x64 (Intel/AMD) or ARM64 (Apple Silicon/ARM)
* **Database**: SQLite (default), PostgreSQL, or PostgreSQL-compatible
* **Ports**: 8888 (web interface), 8000 (heartbeat service)

## Review the EULA

Review the [InfluxData End User Software License Agreement (EULA)](/telegraf/controller/reference/eula/)for Telegraf Controller before downloading and installing.

Telegraf Controller requires that you accept the EULA before the server can
start. When you first run Telegraf Controller in interactive mode (default), it
prompts you to accept the EULA.
Once accepted on a host machine, the EULA does not need to be accepted again
unless the EULA is updated or the Telegraf Controller local data directory is
removed.

### Accept in interactive mode

Run the executable in a terminal and follow the prompt.

```bash
telegraf_controller
```

Enter `v` to view the full text of the Telegraf Controller EULA.
Enter `accept` to accept the EULA and proceed.

### Accept non-interactively

Use the `--eula-accept` command option or set the `TELEGRAF_CONTROLLER_EULA`environment variable to `accept`.
This is required for non-interactive runs such as systemd, LaunchDaemons,
or CI—for example:

```bash
telegraf_controller --eula-accept --no-interactive
```

```bash
TELEGRAF_CONTROLLER_EULA=accept telegraf_controller --no-interactive
```

```powershell
$env:TELEGRAF_CONTROLLER_EULA="accept"
./telegraf_controller.exe --no-interactive
```

## Download and install Telegraf Controller

1. **Download the Telegraf Controller executable.**

   [Download Telegraf Controller]()

2. **Install Telegraf Controller**.

   > [!Important]
> #### Telegraf Controller executable name ####
> The downloaded Telegraf Controller executable includes platform-specific
> information in the file name. You can leave the information in the file
> name or you can rename the file to `telegraf_controller`. This
> documentation assumes the executable is named `telegraf_controller`.

   The downloaded Telegraf Controller executable includes platform-specific
   information in the file name. You can leave the information in the file
   name or you can rename the file to `telegraf_controller`. This
   documentation assumes the executable is named `telegraf_controller`.

   #### Linux ####

   ### Linux ###

   You can add the `telegraf_controller` executable to your system path or you can
   run it in place. You can also run Telegraf Controller as a service.

   * [Add the executable to your system path](#add-the-executable-to-your-system-path)
   * [Run the executable in place](#run-the-executable-in-place)
   * [Install the executable as a systemd service](#install-the-executable-as-a-systemd-service)

   #### Add the executable to your system path ####

   1. Add the following to your shell profile (for example `~/.bashrc`):

      ```
      export PATH="$PATH:$PWD/telegraf_controller"
      ```

   2. Reload the profile or open a new shell.

   #### Run the executable in place ####

   ```
   ./telegraf_controller
   ```

   #### Install the executable as a systemd service ####

   > [!Note]
> > [!Note]
> > [!Note]
> If this is the first run on the host, accept the EULA in a TTY or set`TELEGRAF_CONTROLLER_EULA=accept` in the service environment.

   1. Create a Telegraf Controller service file:

      ```
      sudo tee /etc/systemd/system/telegraf-controller.service > /dev/null <<EOF
      [Unit]
      Description=Telegraf Controller
      After=network.target

      [Service]
      Type=simple
      User=$USER
      WorkingDirectory=/opt/telegraf-controller
      ExecStart=/opt/telegraf-controller/telegraf_controller
      Restart=on-failure
      RestartSec=10

      [Install]
      WantedBy=multi-user.target
      EOF
      ```

   2. Move the executable to `/opt`:

      ```
      sudo mkdir -p /opt/telegraf-controller
      sudo mv telegraf_controller /opt/telegraf-controller/
      sudo chmod +x /opt/telegraf-controller/telegraf_controller
      ```

   3. Enable and start the service:

      ```
      sudo systemctl daemon-reload
      sudo systemctl enable telegraf-controller
      sudo systemctl start telegraf-controller
      ```

   ### macOS ###

   You can add the `telegraf_controller` executable to your system path or you can
   run it in place. You can also run Telegraf Controller as a LaunchDaemon service.

   * [Prepare the downloaded executable](#prepare-the-downloaded-executable)
   * [Add the executable to your system path](#macos-system-path)
   * [Run the executable in place](#macos-executable-in-place)
   * [Install as a LaunchDaemon](#install-as-a-launchdaemon)

   #### Prepare the downloaded executable ####

   1. Give `telegraf_controller` executable permissions:

      ```
      chmod +x telegraf_controller
      ```

   2. Remove the macOS quarantine attribute (if downloaded via browser):

      ```
      xattr -d com.apple.quarantine telegraf_controller
      ```

   #### Add the executable to your system path ####

   ```
   sudo mv telegraf_controller /usr/local/bin/
   export PATH="/usr/local/bin:$PATH"
   ```

   #### Run the executable in place ####

   ```
   ./telegraf_controller
   ```

   #### Install as a LaunchDaemon ####

   If this is the first run on the host, accept the EULA in a TTY or set`TELEGRAF_CONTROLLER_EULA=accept` in the service environment.

   1. Create a plist file:

      ```
      sudo tee /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist > /dev/null <<EOF
      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
      <plist version="1.0">
      <dict>
          <key>Label</key>
          <string>com.influxdata.telegraf-controller</string>
          <key>ProgramArguments</key>
          <array>
              <string>/usr/local/bin/telegraf_controller</string>
          </array>
          <key>RunAtLoad</key>
          <true/>
          <key>KeepAlive</key>
          <true/>
          <key>StandardOutPath</key>
          <string>/var/log/telegraf-controller.log</string>
          <key>StandardErrorPath</key>
          <string>/var/log/telegraf-controller.error.log</string>
      </dict>
      </plist>
      EOF
      ```

   2. Move the executable to `/usr/local/bin`:

      ```
      sudo mv telegraf_controller /usr/local/bin/
      ```

   3. Load the service:

      ```
      sudo launchctl load /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist
      ```

   ### Windows ###

   You can run the `telegraf_controller` executable in place or you can run
   Telegraf Controller as a Windows service.

   * [Run the application in place](#run-the-application-in-place)
   * [Install as a Windows Service](#install-as-a-windows-service)

   #### Run the application in place ####

   **Double-click the executable** or open **Command Prompt or PowerShell** and
   run:

   ```
   ./telegraf_controller.exe
   ```

   #### Install as a Windows Service ####

   Use NSSM (Non-Sucking Service Manager) to run Telegraf Controller as a Windows
   service.

   If this is the first run on the host, accept the EULA in a TTY or set`TELEGRAF_CONTROLLER_EULA=accept` in the service environment.

   1. [Download NSSM](https://nssm.cc/download)

   2. In **Command Prompt or PowerShell**, install the Telegraf Controller service:

      ```
      nssm install TelegrafController "C:\Program Files\TelegrafController\telegraf_controller.exe"
      nssm set TelegrafController DisplayName "Telegraf Controller"
      nssm set TelegrafController Description "Web-based Telegraf configuration manager"
      nssm set TelegrafController Start SERVICE_AUTO_START
      ```

   3. Start the service:

      ```
      nssm start TelegrafController
      ```

## Set up your database

Telegraf Controller supports **SQLite** (default), **PostgreSQL**, or**PostgreSQL-compatible** databases as its data backend.

### SQLite

With SQLite installed, no additional setup is required.
Telegraf Controller creates the database file automatically on first run.

#### Default SQLite data locations

Telegraf Controller stores its data in platform-specific locations:

|Platform|                  Default Database Location                  |
|--------|-------------------------------------------------------------|
| Linux  |       `~/.local/share/telegraf-controller/sqlite.db`        |
| macOS  |`~/Library/Application Support/telegraf-controller/sqlite.db`|
|Windows |       `%LOCALAPPDATA%\telegraf-controller\sqlite.db`        |

### PostgreSQL

The following steps assume you have a running PostgreSQL or
PostgreSQL-compatible server running.

1. Create a database named `telegraf_controller`:

   ```
   CREATE DATABASE telegraf_controller;
   ```

2. Run with PostgreSQL URL:

   ```
   ./telegraf_controller --database="postgresql://user:password@localhost:5432/telegraf_controller"
   ```

The application will automatically run migrations on first startup.

## Configure Telegraf Controller

Use the following command line options to configure Telegraf Controller.

### Configuration options

|       Command Flag       |   Environment Variable   |               Description                |      Default       |
|--------------------------|--------------------------|------------------------------------------|--------------------|
|         `--port`         |        `APP_PORT`        |        Web interface and API port        |       `8888`       |
|    `--heartbeat-port`    |     `HEARTBEAT_PORT`     |       Agent heartbeat service port       |       `8000`       |
|       `--database`       |      `DATABASE_URL`      |        Database connection string        |Auto-detected SQLite|
|       `--logs-dir`       |        `LOGS_DIR`        |       Absolute path for agent logs       |  System temp dir   |
|                          |     `SSL_CERT_PATH`      |        SSL certificate file path         |        None        |
|                          |      `SSL_KEY_PATH`      |        SSL private key file path         |        None        |
|     `--owner-email`      |      `OWNER_EMAIL`       |      Bootstrap owner email address       |        None        |
|    `--owner-username`    |     `OWNER_USERNAME`     |         Bootstrap owner username         |        None        |
|    `--owner-password`    |     `OWNER_PASSWORD`     |         Bootstrap owner password         |        None        |
|`--disable-auth-endpoints`|`DISABLED_AUTH_ENDPOINTS` |Endpoint groups to skip authentication for|        None        |
|    `--no-interactive`    |                          |      Skip prompts and use defaults       |        None        |
|     `--eula-accept`      |`TELEGRAF_CONTROLLER_EULA`|      Accept EULA non-interactively       |        None        |

*For a full list of options, see the[Telegraf Controller configuration options reference](/telegraf/controller/reference/config-options/).*

#### Examples

#### Use Command Flags ####

#### Linux/macOS ####

```bash
# Use custom ports
telegraf_controller --port=3000 --heartbeat-port=9000

# Use PostgreSQL database
telegraf_controller \
  --database="postgresql://user:password@localhost:5432/telegraf_db"

# Use custom SQLite database location
telegraf_controller \
  --database="/path/to/custom/database.db"

# Accept the EULA non-interactively
telegraf_controller \
  --no-interactive \
  --eula-accept
```

```powershell
# Use custom ports
./telegraf_controller.exe --port=3000 --heartbeat-port=9000

# Use PostgreSQL database
./telegraf_controller.exe `
  --database="postgresql://user:password@localhost:5432/telegraf_db"

# Use custom SQLite database location
./telegraf_controller.exe `
  --database="C:\path\to\custom\database.db"

# Accept the EULA non-interactively
./telegraf_controller.exe `
  --no-interactive `
  --eula-accept
```

#### Linux/macOS ####

```bash
# Use custom ports
APP_PORT=3000
HEARTBEAT_PORT=9000

# Use PostgreSQL database
DATABASE_URL=postgresql://user:password@localhost:5432/telegraf_db

# Use custom SQLite database location
DATABASE_URL=/path/to/custom/database.db

# Enable HTTPS
SSL_CERT_PATH=/path/to/cert.pem
SSL_KEY_PATH=/path/to/key.pem

# Accept the EULA
TELEGRAF_CONTROLLER_EULA=accept

telegraf_controller
```

```powershell
# Use custom ports
$env:APP_PORT=3000
$env:HEARTBEAT_PORT=9000

# Use PostgreSQL database
$env:DATABASE_URL=postgresql://user:password@localhost:5432/telegraf_db

# Use custom SQLite database location
$env:DATABASE_URL=C:\path\to\custom\database.db

# Enable HTTPS
$env:SSL_CERT_PATH=C:\path\to\cert.pem
$env:SSL_KEY_PATH=C:\path\to\key.pem

# Accept the EULA
$env:TELEGRAF_CONTROLLER_EULA=accept

./telegraf_controller.exe
```

## Set up the owner account

The first time you access Telegraf Controller, you need to create an owner account.
The owner has full administrative access to the application, including the
ability to manage users, configurations, and agents.

You can create the owner account using one of four methods:

* [Interactive CLI setup](#interactive-cli-setup) when starting the application
* [Environment variables](#environment-variable-setup) set before starting the application
* [Command line flags](#command-line-flag-setup) passed when starting the application
* [Web interface setup](#web-interface-setup) after starting the application

### Interactive CLI setup

When you start Telegraf Controller in interactive mode (default) and no owner
account exists, Telegraf Controller prompts you to provide owner username,
email address, and password.

### Environment variable setup

You can configure the owner account by setting environment variables before
starting Telegraf Controller.
This method is useful for automated deployments and containerized environments.

|Environment variable|    Description    |
|--------------------|-------------------|
|   `OWNER_EMAIL`    |Owner email address|
|  `OWNER_USERNAME`  |  Owner username   |
|  `OWNER_PASSWORD`  |  Owner password   |

*For detailed descriptions, see the[Owner account section in the configuration options reference](/telegraf/controller/reference/config-options/#owner-account).*

Set all three environment variables and then start the application:

```bash
export OWNER_EMAIL="admin@example.com"
export OWNER_USERNAME="admin"
export OWNER_PASSWORD="secure-password-here"

./telegraf-controller
```

> [!Note]
> If an owner account already exists, Telegraf Controller ignores these
> environment variables.

> [!Important]
> If an administrator account already exists with the specified username,
> that account is promoted to owner.

### Command line flag setup

You can also pass owner account details as command line flags when starting
Telegraf Controller.

|         Flag          |    Description    |
|-----------------------|-------------------|
| `--owner-email=EMAIL` |Owner email address|
|`--owner-username=NAME`|  Owner username   |
|`--owner-password=PASS`|  Owner password   |

Pass all three flags when starting the application:

```bash
./telegraf-controller \
  --owner-email="admin@example.com" \
  --owner-username="admin" \
  --owner-password="secure-password-here"
```

> [!Tip]
> Command line flags take precedence over environment variables.
> If you set both, Telegraf Controller uses the values from the command line flags.

### Web interface setup

If no owner account exists when you start Telegraf Controller in non-interactive
mode, the web interface displays a setup page where you can create one.

1. Navigate to the [Telegraf Controller URL](#access-telegraf-controller) in your browser.
2. Fill in the **Username**, **Email**, and **Password** fields.
3. Click **Create Account**.

<img alt="Owner account setup page" width="495" src="/img/telegraf/controller-setup-owner-account.png">

For more information about user roles and permissions, see[Authorization](/telegraf/controller/reference/authorization/).

## Access Telegraf Controller

Once started, access the Telegraf Controller web interface at[http://localhost:8888](http://localhost:8888) *(or using your custom port)*.

#### Related

* [Telegraf Controller configuration options](/telegraf/controller/reference/config-options/)
* [InfluxData End User Software License Agreement (EULA)](/telegraf/controller/reference/eula/)
| Platform | Default Database Location |
| --- | --- |
| Platform | Default Database Location |
| Linux | ~/.local/share/telegraf-controller/sqlite.db |
| macOS | ~/Library/Application Support/telegraf-controller/sqlite.db |
| Windows | %LOCALAPPDATA%\telegraf-controller\sqlite.db |

| Command Flag | Environment Variable | Description | Default |
| --- | --- | --- | --- |
| Command Flag | Environment Variable | Description | Default |
| --port | APP_PORT | Web interface and API port | 8888 |
| --heartbeat-port | HEARTBEAT_PORT | Agent heartbeat service port | 8000 |
| --database | DATABASE_URL | Database connection string | Auto-detected SQLite |
| --logs-dir | LOGS_DIR | Absolute path for agent logs | System temp dir |
|  | SSL_CERT_PATH | SSL certificate file path | None |
|  | SSL_KEY_PATH | SSL private key file path | None |
| --owner-email | OWNER_EMAIL | Bootstrap owner email address | None |
| --owner-username | OWNER_USERNAME | Bootstrap owner username | None |
| --owner-password | OWNER_PASSWORD | Bootstrap owner password | None |
| --disable-auth-endpoints | DISABLED_AUTH_ENDPOINTS | Endpoint groups to skip authentication for | None |
| --no-interactive |  | Skip prompts and use defaults | None |
| --eula-accept | TELEGRAF_CONTROLLER_EULA | Accept EULA non-interactively | None |

| Environment variable | Description |
| --- | --- |
| Environment variable | Description |
| OWNER_EMAIL | Owner email address |
| OWNER_USERNAME | Owner username |
| OWNER_PASSWORD | Owner password |

| Flag | Description |
| --- | --- |
| Flag | Description |
| --owner-email=EMAIL | Owner email address |
| --owner-username=NAME | Owner username |
| --owner-password=PASS | Owner password |