Skip to main content

Installing and Configuring Grafana Alloy

Now that you understand what Grafana Alloy is and how its component-based architecture works, it's time to install Alloy and run your first configuration.

By the end of this lesson, you will be able to:

  • Install Grafana Alloy on Linux, macOS, or Windows.
  • Create a basic configuration file that starts the agent.
  • Run Alloy and validate its configuration.
  • Understand the structure of a minimal Alloy configuration.

Installation Methods​

Grafana Alloy can be installed using several methods. We'll cover the most common ones: using a pre-built binary and using Docker.

Method 1: Using the Install Script (Linux/macOS)​

The simplest way to install Alloy on Linux or macOS is via the official install script. It downloads the latest stable binary, verifies its checksum, and places it in your system's PATH.

Install via script
curl -o - https://raw.githubusercontent.com/grafana/alloy/main/scripts/install.sh | sh

After running the script, verify the installation:

alloy --version
tip

The install script defaults to installing Alloy for the current user. To install it system-wide (e.g., in /usr/local/bin), you may need to run it with sudo. The script will prompt you if it needs elevated privileges.

Method 2: Using Docker​

For containerized environments, you can use the official Alloy Docker image.

Run Alloy with Docker
docker run --rm -p 12345:12345 \
  -v $(pwd)/config.alloy:/etc/alloy/config.alloy \
  grafana/alloy:latest run /etc/alloy/config.alloy

This command:

  • Runs the latest grafana/alloy image.
  • Maps port 12345 from the container to your host (Alloy's default HTTP port).
  • Mounts a local file called config.alloy into the container and runs it.

Method 3: Manual Download​

You can manually download the appropriate binary for your platform (Linux, macOS, Windows) from the Grafana Alloy releases page on GitHub. Extract the archive and place the alloy binary in a directory included in your system's PATH.

Download and extract for Linux
# Example for Linux AMD64
wget https://github.com/grafana/alloy/releases/latest/download/alloy-linux-amd64.zip
unzip alloy-linux-amd64.zip
sudo mv alloy-linux-amd64 /usr/local/bin/alloy

Managing Alloy Services​

Alloy services can be managed using systemd on Linux. The service definition file is typically automatically created at the following location: /usr/lib/systemd/system/alloy.service

[Unit]
Description=Grafana Alloy
Documentation=https://grafana.com/docs/alloy
Wants=network-online.target
After=network-online.target

[Service]
Restart=always
User=root

Environment=HOSTNAME=%H
Environment=ALLOY_DEPLOY_MODE=deb
# Pointing to the directory enables multi-file mode
Environment=CONFIG_FILE=/etc/alloy

EnvironmentFile=-/etc/default/alloy

WorkingDirectory=/var/lib/alloy

# Note: Arguments come before the $CONFIG_FILE path
ExecStart=/usr/bin/alloy run $CUSTOM_ARGS --storage.path=/var/lib/alloy/data $CONFIG_FILE
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process
TimeoutStopSec=20s

[Install]
WantedBy=multi-user.target

You can manage the service using the standard systemctl tool:

systemctl status alloy

Set credentials or other sensitive stuff as the environment variables​

You can set the credentials of other sensitive stuff at the following location /etc/systemd/system/alloy.service.d/env.conf

typical content of the file is

/etc/systemd/system/alloy.service.d/env.conf
[Service]
Environment=GCLOUD_RW_API_KEY=glc_eyJvIjoiM==
Environment=GCLOUD_FM_COLLECTOR_ID=vikasjha001
Environment=GITHUB_TOKEN=ghp_

these environment variables then can be referred as sys.env("GCLOUD_RW_API_KEY") in the alloy configuration file(s).

Creating Your First Configuration​

Alloy uses the River configuration language, and configuration files commonly use the .alloy extension.

Let's create a minimal configuration that scrapes Alloy's own metrics and sends them to a Prometheus remote_write endpoint:

config.alloy
logging {
  level = "info"
}

prometheus.exporter.self "self" {}

prometheus.scrape "self" {
  targets    = prometheus.exporter.self.self.targets
  forward_to = [prometheus.remote_write.default.receiver]
}

prometheus.remote_write "default" {
  endpoint {
    url = "http://localhost:9090/api/v1/write"
  }
}
note

Update the url to a real Prometheus-compatible remote_write endpoint (for example, Grafana Cloud Metrics). This lesson assumes you have a running receiver. In the next section, we'll use the course's Grafana Cloud example.

Course Example: Global Outputs and Auth​

The course examples are stored in docs/grafanaalloy/examples. Most lessons rely on a shared global configuration that defines outputs and auth. This is docs/grafanaalloy/examples/01-global.alloy:

docs/grafanaalloy/examples/01-global.alloy
livedebugging {
  enabled = true
}


// 01-global.alloy

remotecfg {
  url = "https://fleet-management-prod-008.grafana.net"
  id  = "vikasjha001"

  attributes = {
    "os"       = "linux",
    "env"      = "production",
    "hostname" = constants.hostname,
  }

  basic_auth {
    username = "1064633"
    password = sys.env("GCLOUD_RW_API_KEY")
  }
}

prometheus.remote_write "grafana_cloud" {
  endpoint {
    url = "http://localhost:9090/api/v1/write"
  }

  endpoint {
    url = "https://prometheus-prod-13-prod-us-east-0.grafana.net/api/prom/push"

    basic_auth {
      username = "1846252"
      // Use the API Key you provided
      password = sys.env("GCLOUD_RW_API_KEY")
    }
  }
}

// Update your relabeler to forward to the Cloud destination
prometheus.relabel "common_labels" {
  forward_to = [prometheus.remote_write.grafana_cloud.receiver]

  rule {
    target_label = "env"
    replacement  = "production"
  }
}

loki.write "grafana_cloud_loki" {
  endpoint {
    url = "https://logs-prod-006.grafana.net/loki/api/v1/push"

    basic_auth {
      username = "1022411"
      password = sys.env("GCLOUD_RW_API_KEY")
    }
  }
}


otelcol.auth.basic "grafana_cloud" {
  username = "1016726"
  password = sys.env("GCLOUD_RW_API_KEY")
}

otelcol.exporter.otlp "grafana_cloud" {
  client {
    endpoint = "tempo-prod-04-prod-us-east-0.grafana.net:443"
    auth     = otelcol.auth.basic.grafana_cloud.handler
  }
}
tip

This file expects the GCLOUD_RW_API_KEY environment variable to be set. If you're not using Grafana Cloud, update the endpoints and auth blocks accordingly.

Running Grafana Alloy​

Alloy commands accept either a file path or a directory. If you pass a directory, Alloy loads all *.alloy files in that folder (non-recursive) as a single configuration source.

Validate a config file
alloy validate config.alloy
Run a config file
alloy run config.alloy
Validate and run the course examples
alloy validate docs/grafanaalloy/examples
alloy run docs/grafanaalloy/examples
note

The docs/grafanaalloy/examples directory contains multiple optional integrations. If you only want to run a subset, create a new folder and copy 01-global.alloy plus the specific example files you want to test.

Verifying the Agent is Working​

  1. Check the logs: The terminal output shows the agent is running.
  2. Check the HTTP endpoint: By default, Alloy exposes metrics about itself on http://localhost:12345/metrics. 
    curl http://localhost:12345/metrics | head -5
  3. Check your backend: Confirm that your remote-write destination (Grafana Cloud or Prometheus) is receiving metrics.

To stop the agent, go back to the terminal and press Ctrl+C.

Common Pitfalls​

  • Missing config path: alloy run expects a file or directory path. If you omit it, Alloy exits with an error.
  • Wrong file extension: The examples use .alloy. If you used .river, update your tooling or rename the file.
  • Missing env vars: 01-global.alloy reads GCLOUD_RW_API_KEY from the environment. If it's missing, auth will fail.
  • Port already in use: If 127.0.0.1:12345 is occupied, set --server.http.listen-addr when running Alloy.

Summary​

In this lesson, you installed Grafana Alloy and created a minimal configuration. You also reviewed the shared 01-global.alloy file that powers the course examples. Next, we'll dive into the Alloy configuration language in depth.

Installing Grafana Alloy - Quick Check

What is the typical file extension for an Alloy configuration file?

Question 1/4