Menu

Caution

Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.

This is documentation for the next version of Agent. For the latest stable release, go to the latest version.

Open source

Run Grafana Agent Flow as a standalone binary

If you downloaded the standalone binary, you must run Grafana Agent Flow from a terminal or command window.

Start Grafana Agent Flow on Linux, macOS, or FreeBSD

To start Grafana Agent Flow on Linux, macOS, or FreeBSD, run the following command in a terminal window:

shell
AGENT_MODE=flow <BINARY_PATH> run <CONFIG_PATH>

Replace the following:

  • <BINARY_PATH>: The path to the Grafana Agent Flow binary file.
  • <CONFIG_PATH>: The path to the Grafana Agent Flow configuration file.

Start Grafana Agent Flow on Windows

To start Grafana Agent Flow on Windows, run the following commands in a command prompt:

cmd
set AGENT_MODE=flow
<BINARY_PATH> run <CONFIG_PATH>

Replace the following:

  • <BINARY_PATH>: The path to the Grafana Agent Flow binary file.
  • <CONFIG_PATH>: The path to the Grafana Agent Flow configuration file.

Set up Grafana Agent Flow as a Linux systemd service

You can set up and manage the standalone binary for Grafana Agent Flow as a Linux systemd service.

Note

These steps assume you have a default systemd and Grafana Agent Flow configuration.
  1. To create a new user called grafana-agent-flow run the following command in a terminal window:

    shell
    sudo useradd --no-create-home --shell /bin/false grafana-agent-flow
  2. Create a service file in /etc/systemd/system called grafana-agent-flow.service with the following contents:

    systemd
    [Unit]
    Description=Vendor-neutral programmable observability pipelines.
    Documentation=https://grafana.com/docs/agent/latest/flow/
    Wants=network-online.target
    After=network-online.target
    
    [Service]
    Restart=always
    User=grafana-agent-flow
    Environment=HOSTNAME=%H
    EnvironmentFile=/etc/default/grafana-agent-flow
    WorkingDirectory=<WORKING_DIRECTORY>
    ExecStart=<BINARY_PATH> run $CUSTOM_ARGS --storage.path=<WORKING_DIRECTORY> $CONFIG_FILE
    ExecReload=/usr/bin/env kill -HUP $MAINPID
    TimeoutStopSec=20s
    SendSIGKILL=no
    
    [Install]
    WantedBy=multi-user.target

    Replace the following:

    • <BINARY_PATH>: The path to the Grafana Agent Flow binary file.
    • <WORKING_DIRECTORY>: The path to a working directory, for example /var/lib/grafana-agent-flow.
  3. Create an environment file in /etc/default/ called grafana-agent-flow with the following contents:

    shell
    ## Path:
    ## Description: Grafana Agent Flow settings
    ## Type:        string
    ## Default:     ""
    ## ServiceRestart: grafana-agent-flow
    #
    # Command line options for grafana-agent
    #
    # The configuration file holding the Grafana Agent Flow configuration.
    CONFIG_FILE="<CONFIG_PATH>"
    
    # User-defined arguments to pass to the run command.
    CUSTOM_ARGS=""
    
    # Restart on system upgrade. Defaults to true.
    RESTART_ON_UPGRADE=true

    Replace the following:

    • <CONFIG_PATH>: The path to the Grafana Agent Flow configuration file.
  4. To reload the service files, run the following command in a terminal window:

    shell
    sudo systemctl daemon-reload
  5. Use the Linux systemd commands to manage your standalone Linux installation of Grafana Agent Flow.