---
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: 10774
product: Telegraf
version: v1
---

# Install Telegraf Controller

#### 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**.
    
    #### 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`.
    
    <!-- Tabbed content: Select one of the following options -->
    
    
    **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`):
        
        ```bash
        export PATH="$PATH:$PWD/telegraf_controller"
        ```
        
    2. Reload the profile or open a new shell.
        
    
    #### Run the executable in place
    
    ```sh
    ./telegraf_controller
    ```
    
    #### Install the executable as a systemd 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. Create a Telegraf Controller service file:
        
        ```bash
        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`:
        
        ```bash
        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:
        
        ```bash
        sudo systemctl daemon-reload
        sudo systemctl enable telegraf-controller
        sudo systemctl start telegraf-controller
        ```
    
    
    
    **macOS:**
    
    ### 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:
        
        ```bash
        chmod +x telegraf_controller
        ```
        
    2. Remove the macOS quarantine attribute (if downloaded via browser):
        
        ```bash
        xattr -d com.apple.quarantine telegraf_controller
        ```
        
    
    #### Add the executable to your system path
    
    ```bash
    sudo mv telegraf_controller /usr/local/bin/
    export PATH="/usr/local/bin:$PATH"
    ```
    
    #### Run the executable in place
    
    ```bash
    ./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:
        
        ```bash
        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`:
        
        ```bash
        sudo mv telegraf_controller /usr/local/bin/
        ```
        
    3. Load the service:
        
        ```bash
        sudo launchctl load /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist
        ```
    
    
    
    **Windows:**
    
    ### 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:
    
    ```powershell
    ./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:
        
        ```powershell
        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:
        
        ```powershell
        nssm start TelegrafController
        ```
    
    
    
    <!-- End tabbed content -->
    

## 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`:
    
    ```sql
    CREATE DATABASE telegraf_controller;
    ```
    
2. Run with PostgreSQL URL:
    
    ```sh
    ./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

<!-- Tabbed content: Select one of the following options -->

**Use Command Flags:**

<!-- Tabbed content: Select one of the following options -->

**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
```

**Windows (Powershell):**

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

<!-- End tabbed content -->

**Use Environment Variables:**

<!-- Tabbed content: Select one of the following options -->

**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
```

**Windows (Powershell):**

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

<!-- End tabbed content -->

<!-- End tabbed content -->

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

If an owner account already exists, Telegraf Controller ignores these environment variables.

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"
```

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

![Owner account setup page](/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/)