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