---
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: 4680
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/install/
date: '2026-09-23T16:27:16-06:00'
lastmod: '2026-09-23T16:27:16-06:00'
---

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)
* [Apply a Telegraf Enterprise license (optional)](#apply-a-telegraf-enterprise-license-optional)
* [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 and API), 8000 (heartbeat service).
  Optionally, serve the web interface on a separate[`ui-port`](/telegraf/controller/reference/config-options/#ui-port).

## 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**.

   #### 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`.

   [Linux](#linux-2)[macOS](#macos-2)[Windows](#windows-2)

   ### 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 ####

   To run Telegraf Controller as a systemd service, see[Run Telegraf Controller as a service](/telegraf/controller/admin/run-as-a-service/#linux-systemd).

   ### 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 ####

   To run Telegraf Controller as a LaunchDaemon, see[Run Telegraf Controller as a service](/telegraf/controller/admin/run-as-a-service/#macos-launchdaemon).

   ### 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 ####

   To run Telegraf Controller as a Windows service, see[Run Telegraf Controller as a service](/telegraf/controller/admin/run-as-a-service/#windows-nssm).

## Set up your database

Telegraf Controller supports **SQLite** (default), **PostgreSQL**, or**PostgreSQL-compatible** databases as its data backend.
To back up, restore, or troubleshoot the database after installation, see[Manage the database](/telegraf/controller/admin/database/).

### 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.

#### Connect to PostgreSQL over TLS

To encrypt the connection to a PostgreSQL or PostgreSQL-compatible server,
add the `sslmode` query parameter to the database URL. To verify the server
certificate, use `sslmode=verify-full` and provide a CA certificate with`sslrootcert`:

```sh
./telegraf_controller \
  --database="postgresql://user:password@db.example.com:5432/telegraf_controller?sslmode=verify-full&sslrootcert=/etc/ssl/certs/ca.pem"
```

For all PostgreSQL TLS options, including supported `sslmode` values and the`DATABASE_CA_CERT` and `DATABASE_SSL_NO_VERIFY` environment variables, see[Database TLS](/telegraf/controller/reference/config-options/#database-tls).

## 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`       |
|       `--ui-port`        |        `UI_PORT`         |    Optional separate web interface port    | Served on API port |
|    `--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`       |     `SSL_CERT_PATH`      |PEM SSL/TLS certificate file (enables HTTPS)|        None        |
|       `--ssl-key`        |      `SSL_KEY_PATH`      |PEM SSL/TLS private key file (enables HTTPS)|        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/).*

> [!Note]
> #### Enabling HTTPS also requires agent-side trust
>
> Setting `--ssl-cert`/`--ssl-key` enables HTTPS on the server, but agents must
> also trust the certificate to fetch configurations and send heartbeats. For the
> full server and agent setup, see[Secure Telegraf Controller with TLS](/telegraf/controller/admin/secure-tls/).

#### Examples

[Use Command Flags](#use-command-flags)[Use Environment Variables](#use-environment-variables)

[Linux/macOS](#linuxmacos)[Windows (Powershell)](#windows-powershell)

```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](#linuxmacos-2)[Windows (Powershell)](#windows-powershell-2)

```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 src="/img/telegraf/controller-setup-owner-account.png" alt="Owner account setup page" width="495">

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

## Apply a Telegraf Enterprise license (optional)

If you have a [Telegraf Enterprise](/telegraf/enterprise/)license, you can apply it at startup by setting the `LICENSE_FILE_PATH`environment variable to the path of your license file.

```bash
export LICENSE_FILE_PATH=/etc/telegraf-controller/license.jwt
```

You can also apply a license through the Telegraf Controller UI after the
application is running. For full details on both methods, including systemd
and Docker examples, see[Apply a license](/telegraf/controller/telegraf-enterprise/apply-license/).

Without a license, Telegraf Controller runs in a free tier with reduced
scale limits and enterprise features disabled. See[Telegraf Enterprise](/telegraf/enterprise/) for a
comparison.

## Access Telegraf Controller

Once started, access the Telegraf Controller web interface at[http://localhost:8888](http://localhost:8888) *(or using your custom port)*. If you set[`ui-port`](/telegraf/controller/reference/config-options/#ui-port) to serve the
web interface on a separate port, use that port instead.

If the server does not start or you cannot access the web interface, see[Troubleshoot Telegraf Controller](/telegraf/controller/admin/troubleshoot/).

#### Related

* [Upgrade Telegraf Controller](/telegraf/controller/install/upgrade/)
* [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 |
| --ui-port | UI_PORT | Optional separate web interface port | Served on API port |
| --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 | SSL_CERT_PATH | PEM SSL/TLS certificate file (enables HTTPS) | None |
| --ssl-key | SSL_KEY_PATH | PEM SSL/TLS private key file (enables HTTPS) | 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 |