Install Grafana Alloy on Grafana Labs

Install Grafana Alloy on Linux

Mon, 30 Mar 2026 15:47:22 +0000

Install Grafana Alloy on Linux

Start your learning experience with Grafana Learning Paths

Grafana Learning Paths provide a clear, structured path that leads you from beginner concepts to advanced use cases. Learn about this Grafana feature on Monitor a Linux server in Grafana Cloud.

Start learning

You can install Alloy as a systemd service on Linux.

Before you begin

Some Debian-based cloud Virtual Machines don’t have GPG installed by default. To install GPG in your Linux Virtual Machine, run the following command in a terminal window.

sudo apt install gpg

Install

To install Alloy on Linux, run the following commands in a terminal window.

Import the GPG key and add the Grafana package repository.

sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/grafana.asc https://apt.grafana.com/gpg-full.key
sudo chmod 644 /etc/apt/keyrings/grafana.asc
echo "deb [signed-by=/etc/apt/keyrings/grafana.asc] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list

wget -q -O gpg.key https://rpm.grafana.com/gpg.key
sudo rpm --import gpg.key
echo -e '[grafana]\nname=grafana\nbaseurl=https://rpm.grafana.com\nrepo_gpgcheck=1\nenabled=1\ngpgcheck=1\ngpgkey=https://rpm.grafana.com/gpg.key\nsslverify=1\nsslcacert=/etc/pki/tls/certs/ca-bundle.crt' | sudo tee /etc/yum.repos.d/grafana.repo

wget -q -O gpg.key https://rpm.grafana.com/gpg.key
sudo rpm --import gpg.key
sudo zypper addrepo https://rpm.grafana.com grafana

Update the repositories.
Debian-Ubuntu
sudo apt-get update
RHEL-Fedora
yum update
SUSE-openSUSE
sudo zypper update
Install Alloy.
Debian-Ubuntu
sudo apt-get install alloy
RHEL-Fedora
sudo dnf install alloy
SUSE-openSUSE
sudo zypper -r grafana install alloy

Uninstall

To uninstall Alloy on Linux, run the following commands in a terminal window.

Stop the systemd service for Alloy.
All-distros
```
sudo systemctl stop alloy
```
Uninstall Alloy.
Debian-Ubuntu
sudo apt-get remove alloy
RHEL-Fedora
sudo dnf remove alloy
SUSE-openSUSE
sudo zypper remove alloy
Optional: Remove the Grafana repository.
Debian-Ubuntu
sudo rm -i /etc/apt/sources.list.d/grafana.list
RHEL-Fedora
sudo rm -i /etc/yum.repos.d/grafana.repo
SUSE-openSUSE
sudo zypper removerepo grafana

Next steps

Install Grafana Alloy on macOS

Mon, 30 Mar 2026 15:47:22 +0000

Install Grafana Alloy on macOS

Start your learning experience with Grafana Learning Paths

Grafana Learning Paths provide a clear, structured path that leads you from beginner concepts to advanced use cases. Learn about this Grafana feature on Monitor a macOS system in Grafana Cloud.

Start learning

You can install Alloy on macOS with Homebrew.

Note
The default prefix for Homebrew on Intel is /usr/local. The default prefix for Homebrew on Apple Silicon is /opt/Homebrew.

To verify the default prefix for Homebrew on your computer, open a terminal window and type brew --prefix.

Before you begin

Install Homebrew on your computer.

Install

To install Alloy on macOS, run the following commands in a terminal window.

Add the Grafana Homebrew tap:
shell
```
brew tap grafana/grafana
```
Install Alloy:
shell
```
brew install grafana/grafana/alloy
```

Upgrade

To upgrade Alloy on macOS, run the following commands in a terminal window.

Upgrade Alloy:
shell
```
brew upgrade grafana/grafana/alloy
```

Restart Alloy:

brew services restart grafana/grafana/alloy

Uninstall

To uninstall Alloy on macOS, run the following command in a terminal window:

brew uninstall grafana/grafana/alloy

Next steps

Install Grafana Alloy on Windows

Mon, 30 Mar 2026 15:47:22 +0000

Install Grafana Alloy on Windows

You can install Alloy on Windows as a standard graphical install, a WinGet install, or a silent install.

Standard graphical install

To do a standard graphical install of Alloy on Windows, perform the following steps.

Navigate to the releases page on GitHub.
Scroll down to the Assets section.
Download alloy-installer-windows-amd64.exe or download and extract alloy-installer-windows-amd64.exe.zip.
Double-click on alloy-installer-windows-amd64.exe to install Alloy.

The installer places Alloy in the default directory %PROGRAMFILES%\GrafanaLabs\Alloy.

WinGet install

To install Alloy with WinGet, perform the following steps.

Make sure that the WinGet package manager is installed.

Run the following command.

winget install GrafanaLabs.Alloy

winget install GrafanaLabs.Alloy

Silent install

To do a silent install of Alloy on Windows, perform the following steps.

Navigate to the releases page on GitHub.
Scroll down to the Assets section.
Download alloy-installer-windows-amd64.exe or download and extract alloy-installer-windows-amd64.exe.zip.
Run the following command as Administrator.
cmd
<PATH>\alloy-installer-windows-amd64.exe /S
powershell
& <PATH>\alloy-installer-windows-amd64.exe /S
Replace the following:
- <PATH_TO_INSTALLER>: The path to the uncompressed installer executable.

Silent install options

/CONFIG=<path> Path to the configuration file. Default: $INSTDIR\config.alloy
/DISABLEREPORTING=<yes|no> Disable data collection. Default: no
/DISABLEPROFILING=<yes|no> Disable profiling endpoint. Default: no
/ENVIRONMENT="KEY=VALUE\0KEY2=VALUE2" Define environment variables for Windows Service. Default: ``
/FORCEREGISTRY=yes At the start of installation, delete all Alloy registry keys and then run the rest of the install as normal so that install options such as /STABILITY and /DISABLEREPORTING are written fresh. By default, the installer preserves existing registry values on upgrade; use this flag to reset them and apply the options passed on the command line, and to remove any old or unused registry keys from previous versions.
/RUNTIMEPRIORITY="normal|below_normal|above_normal|high|idle|realtime" Set the runtime priority of the Alloy process. Default: normal
/STABILITY="generally-available|public-preview|experimental" Set the stability level of Alloy. Default: generally-available
/USERNAME="<username>" Set the fully qualified user that Windows uses to run the service. Default: NT AUTHORITY\LocalSystem
/PASSWORD="<password>" Set the password of the user that Windows uses to run the service. This isn’t required for standard Windows Service Accounts like LocalSystem. Default: ``

Note
The --windows.priority flag is in public preview and isn’t covered by Grafana Alloy backward compatibility guarantees. The /RUNTIMEPRIORITY installation option sets this flag, and if Alloy isn’t running with an appropriate stability level, it fails to start.

Service configuration

Alloy uses the Windows registry key HKLM\Software\GrafanaLabs\Alloy for service configuration.

Arguments: Type REG_MULTI_SZ. Each value represents a binary argument for the Alloy binary.
Environment: Type REG_MULTI_SZ. Each value represents an environment value KEY=VALUE for the Alloy binary.

Uninstall

Uninstalling Alloy stops the service and removes it from disk. This includes any configuration files in the installation directory.

Standard graphical uninstall

To uninstall Alloy, use Add or Remove Programs or run the following command as Administrator.

%PROGRAMFILES%\GrafanaLabs\Alloy\uninstall.exe

& ${env:PROGRAMFILES}\GrafanaLabs\Alloy\uninstall.exe

Uninstall with WinGet

To uninstall Alloy with WinGet, run the following command.

winget uninstall GrafanaLabs.Alloy

winget uninstall GrafanaLabs.Alloy

Silent uninstall

To silently uninstall Alloy, run the following command as Administrator.

%PROGRAMFILES%\GrafanaLabs\Alloy\uninstall.exe /S

& ${env:PROGRAMFILES}\GrafanaLabs\Alloy\uninstall.exe /S

Next steps

Run Grafana Alloy in a Docker container

Mon, 30 Mar 2026 15:47:22 +0000

Run Grafana Alloy in a Docker container

Alloy is available as a Docker container image on the following platforms:

Linux containers for AMD64 and ARM64.
macOS for AMD64 (Intel) and ARM64 (Apple Silicon) using Docker Desktop.
Windows containers for AMD64.

Note
On macOS, Docker Desktop manages a Linux virtual machine transparently, so the Linux container commands work without modification.

Before you begin

Install Docker or Docker Desktop on your computer.
Create and save an Alloy configuration file on your computer, for example:
Alloy
```
logging {
  level  = "info"
  format = "logfmt"
}
```

Run a Linux Docker container

To run Alloy as a Linux Docker container, run the following command in a terminal window:

docker run \
  -v <CONFIG_FILE_PATH>:/etc/alloy/config.alloy \
  -p 12345:12345 \
  grafana/alloy:latest \
    run --server.http.listen-addr=0.0.0.0:12345 --storage.path=/var/lib/alloy/data \
    /etc/alloy/config.alloy

Replace the following:

<CONFIG_FILE_PATH>: The path of the configuration file on your host system.

You can modify the last line to change the arguments passed to the Alloy binary. Refer to the documentation for run for more information about the options available to the run command.

Note
Make sure you pass --server.http.listen-addr=0.0.0.0:12345 as an argument as shown in the example. If you don’t pass this argument, the debugging UI won’t be available outside of the Docker container.

BoringCrypto images

Note
BoringCrypto support is in Public preview and is only available on AMD64 and ARM64 platforms.

BoringCrypto images are published with every release starting with version 1.1:

The current BoringCrypto image is published as grafana/alloy:boringcrypto.
A specific version of the BoringCrypto image is published as grafana/alloy:<VERSION>-boringcrypto, such as grafana/alloy:v1.1.0-boringcrypto.

Run a Windows Docker container

To run Alloy as a Windows Docker container, run the following command in a terminal window:

docker run \
  -v "<CONFIG_FILE_PATH>:C:\Program Files\GrafanaLabs\Alloy\config.alloy" \
  -p 12345:12345 \
  grafana/alloy:windowsservercore-ltsc2022 \
    run --server.http.listen-addr=0.0.0.0:12345 "--storage.path=C:\ProgramData\GrafanaLabs\Alloy\data" \
    "C:\Program Files\GrafanaLabs\Alloy\config.alloy"

Replace the following:

<CONFIG_FILE_PATH>: The path of the configuration file on your host system.

You can modify the last line to change the arguments passed to the Alloy binary. Refer to the documentation for run for more information about the options available to the run command.

Note
Make sure you pass --server.http.listen-addr=0.0.0.0:12345 as an argument as shown in the example above. If you don’t pass this argument, the debugging UI won’t be available outside of the Docker container.

Verify

To verify that Alloy is running successfully, navigate to http://localhost:12345 and make sure the Alloy UI loads without error.

Deploy Grafana Alloy on Kubernetes

Mon, 30 Mar 2026 15:47:22 +0000

Deploy Grafana Alloy on Kubernetes

Start your learning experience with Grafana Learning Paths

Grafana Learning Paths provide a clear, structured path that leads you from beginner concepts to advanced use cases. Learn about this Grafana feature on Monitor Kubernetes cluster infrastructure in Grafana Cloud.

Start learning

Alloy can be deployed on Kubernetes by using the Helm chart for Alloy.

Before you begin

Install Helm on your computer.
Configure a Kubernetes cluster that you can use for Alloy.
Configure your local Kubernetes context to point at the cluster.

Deploy

To deploy Alloy on Kubernetes using Helm, run the following commands in a terminal window:

Add the Grafana Helm chart repository:

helm repo add grafana https://grafana.github.io/helm-charts

Update the Grafana Helm chart repository:
shell
```
helm repo update
```
Create a namespace for Alloy:
shell
```
kubectl create namespace <NAMESPACE>
```
Replace the following:
- <NAMESPACE>: The namespace to use for your Alloy installation, such as alloy.
Install Alloy:
shell
```
helm install --namespace <NAMESPACE> <RELEASE_NAME> grafana/alloy
```
Replace the following:
- <NAMESPACE>: The namespace created in the previous step.
- <RELEASE_NAME>: The name to use for your Alloy installation, such as alloy.
Verify that the Alloy pods are running:
shell
```
kubectl get pods --namespace <NAMESPACE>
```
Replace the following:
- <NAMESPACE>: The namespace used in the previous step.

You have successfully deployed Alloy on Kubernetes, using default Helm settings.

Next steps

Configure Alloy

Install Grafana Alloy as a standalone binary

Mon, 30 Mar 2026 15:47:22 +0000

Install Grafana Alloy as a standalone binary

Alloy is distributed as a standalone binary for the following operating systems and architectures:

Linux: AMD64, ARM64
Windows: AMD64
macOS: AMD64 on Intel, ARM64 on Apple Silicon
FreeBSD: AMD64

Download Alloy

To download Alloy as a standalone binary, perform the following steps.

Navigate to the current Alloy release page.
Scroll down to the Assets section.
Download the alloy file that matches your operating system and machine’s architecture.
Extract the package contents into a directory.
If you are installing Alloy on Linux, macOS, or FreeBSD, run the following command in a terminal:
shell
```
chmod +x <BINARY_PATH>
```
Replace the following:
- <BINARY_PATH>: The path to the extracted binary.

BoringCrypto binaries

Note
BoringCrypto support is in Public preview and is only available for Linux with the AMD64 or ARM64 architecture.

BoringCrypto binaries are published for Linux on AMD64 and ARM64 platforms. To retrieve them, follow the steps above but search for the alloy-boringcrypto file that matches your Linux architecture.

Next steps

Run Alloy

Install Grafana Alloy with Ansible

Mon, 30 Mar 2026 15:47:22 +0000

Install or uninstall Grafana Alloy using Ansible

You can use the Grafana Ansible Collection to install and manage Alloy on Linux hosts.

Before you begin

These steps assume you already have a working Ansible setup and an inventory.
You can add the tasks below to any role.

Steps

To add Alloy to a host:

Create a file named alloy.yml and add the following:

- name: Install Alloy
  hosts: all
  become: true

  tasks:
    - name: Install Alloy
      ansible.builtin.include_role:
        name: grafana.grafana.alloy
      vars:
        alloy_config: |
          prometheus.scrape "default" {
            targets = [{"__address__" = "localhost:12345"}]
            forward_to = [prometheus.remote_write.prom.receiver]
          }
          prometheus.remote_write "prom" {
            endpoint {
                url = "<YOUR_PROMETHEUS_PUSH_ENDPOINT>"
            }
          }

This snippet has a sample configuration to collect and send Alloy metrics to Prometheus

Replace the following:

<YOUR_PROMETHEUS_PUSH_ENDPOINT>: The Remote write endpoint of your Prometheus Instance.

Run the Ansible playbook. Open a terminal window and run the following command from the Ansible playbook directory.
shell
```
ansible-playbook alloy.yml
```

Validate

To verify that the Alloy service on the target machine is active and running, open a terminal window and run the following command:

sudo systemctl status alloy.service

If the service is active and running, the output should look similar to this:

alloy.service - Grafana Alloy
  Loaded: loaded (/etc/systemd/system/alloy.service; enabled; vendor preset: enabled)
  Active: active (running) since Wed 2022-07-20 09:56:15 UTC; 36s ago
Main PID: 3176 (alloy-linux-amd)
  Tasks: 8 (limit: 515)
  Memory: 92.5M
    CPU: 380ms
  CGroup: /system.slice/alloy.service
    └─3176 /usr/local/bin/alloy-linux-amd64 --config.file=/etc/grafana-cloud/alloy-config.yaml

Next steps

Configure Alloy

Install Grafana Alloy with Chef

Mon, 30 Mar 2026 15:47:22 +0000

Install Grafana Alloy with Chef

You can use Chef to install and manage Alloy.

Before you begin

These steps assume you already have a working Chef setup.
You can add the following resources to any recipe.
These tasks install Alloy from the package repositories. The tasks target Linux systems from the following families:
- Debian, including Ubuntu
- RedHat Enterprise Linux, including Fedora
- Amazon Linux

Steps

To add Alloy to a host:

Add the following resources to your Chef recipe to add the Grafana package repositories to your system:

if platform_family?('debian', 'rhel', 'amazon', 'fedora')
  if platform_family?('debian')
    remote_file '/etc/apt/keyrings/grafana.gpg' do
      source 'https://apt.grafana.com/gpg.key'
      mode '0644'
      action :create
      end

    file '/etc/apt/sources.list.d/grafana.list' do
      content "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com/ stable main"
      mode '0644'
      notifies :update, 'apt_update[update apt cache]', :immediately
    end

    apt_update 'update apt cache' do
      action :nothing
    end
  elsif platform_family?('rhel', 'amazon', 'fedora')
    yum_repository 'grafana' do
      description 'grafana'
      baseurl 'https://rpm.grafana.com'
      gpgcheck true
      gpgkey 'https://rpm.grafana.com/gpg.key'
      enabled true
      action :create
      notifies :run, 'execute[add-rhel-key]', :immediately
    end

    execute 'add-rhel-key' do
      command "rpm --import https://rpm.grafana.com/gpg.key"
      action :nothing
    end
  end
else
    fail "The #{node['platform_family']} platform is not supported."
end

Add the following resources to install and enable the alloy service:

package 'alloy' do
  action :install
  flush_cache [ :before ] if platform_family?('amazon', 'rhel', 'fedora')
  notifies :restart, 'service[alloy]', :delayed
end

service 'alloy' do
  service_name 'alloy'
  action [:enable, :start]
end

Configuration

The alloy package installs a default configuration file that doesn’t send telemetry anywhere.

The default configuration file location is /etc/alloy/config.alloy. You can replace this file with your own configuration or create a configuration file for the service to use.

Next steps

Configure Alloy

Deploy Grafana Alloy on OpenShift

Mon, 30 Mar 2026 15:47:22 +0000

Deploy Grafana Alloy on OpenShift

You can deploy Alloy on the Red Hat OpenShift Container Platform (OCP).

Before you begin

These steps assume you have a working OCP environment.
You can adapt the suggested policies and configuration to meet your specific needs and security policies.

Configure RBAC

You must configure Role-Based Access Control (RBAC) to allow secure access to Kubernetes and OCP resources.

Download the rbac.yaml configuration file. This configuration file defines the OCP verbs and permissions for Alloy.
Review the rbac.yaml file and adapt as needed for your local environment. Refer to Managing Role-based Access Control (RBAC) topic in the OCP documentation for more information about updating and managing your RBAC configurations.

Run Alloy as a non-root user

You must configure Alloy to run as a non-root user. This ensures that Alloy complies with your OCP security policies.

Apply security context constraints

OCP uses Security Context Constraints (SCC) to control Pod permissions. Refer to Managing security context constraints for more information about how you can define and enforce these permissions. This ensures that the pods running Alloy comply with OCP security policies.

Note
The security context is only configured at the container level, not at the container and deployment level.

You can apply the following SCCs when you deploy Alloy.

Note
Not all of these SCCs are required for each use case. You can adapt the SCCs to meet your local requirements and needs.

RunAsUser: Specifies the user ID under which Alloy runs. You must configure this constraint to allow a non-root user ID.
SELinuxContext: Configures the SELinux context for containers. If you run Alloy as root, you must configure this constraint to make sure that SELinux policies don’t block Alloy. This SCC is generally not required to deploy Alloy as a non-root user.
FSGroup: Specifies the fsGroup IDs for file system access. You must configure this constraint to give Alloy group access to the files it needs.
Volumes: Specifies the persistent volumes used for storage. You must configure this constraint to give Alloy access to the volumes it needs.

Example DaemonSet configuration

The following example shows a DaemonSet configuration that deploys Alloy as a non-root user:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: alloy-logs
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: alloy-logs
  template:
    metadata:
      labels:
        app: alloy-logs
    spec:
      securityContext:
        runAsUser: 473
        runAsGroup: 473
        fsGroup: 1000
      containers:
      - name: alloy-logs
        image: grafana/alloy:<ALLOY_VERSION>
        ports:
        - containerPort: 12345
        securityContext:
          readOnlyRootFilesystem: true
          allowPrivilegeEscalation: false
      volumes:
      - name: log-volume
        emptyDir: {}

Replace the following:

<ALLOY_VERSION>: Set to the specific Alloy version you are deploying. For example, 1.5.1.

Note
This example uses the simplest volume type, emptyDir. In this example configuration, if your node restarts, your data will be lost. Make sure you set the volume type to a persistent storage location for production environments. Refer to Using volumes to persist container data in the OpenShift documentation for more information.

Example SCC definition

The following example shows an SCC definition that deploys Alloy as a non-root user:

kind: SecurityContextConstraints
apiVersion: security.openshift.io/v1
metadata:
  name: scc-alloy
runAsUser:
  type: MustRunAs
  uid: 473
fsGroup:
  type: MustRunAs
  uid: 1000
volumes: 
- '*'
users:
- my-admin-user
groups:
- my-admin-group
seLinuxContext:
  type: MustRunAs
  user: <SYSTEM_USER>
  role: <SYSTEM_ROLE>
  type: <CONTAINER_TYPE>
  level: <LEVEL>

Replace the following:

<SYSTEM_USER>: The user for your SELinux context.
<SYSTEM_ROLE>: The role for your SELinux context.
<CONTAINER_TYPE>: The container type for your SELinux context.
<LEVEL>: The level for your SELinux context.

Refer to SELinux Contexts in the RedHat documentation for more information on the SELinux context configuration.

Note
This example sets volumes: to *. In a production environment, you should set volumes: to only the volumes that are necessary for the deployment. For example:
YAML
volumes:
  - configMap
  - downwardAPI
  - emptyDir
  - persistentVolumeClaim
  - secret 

Refer to Deploy Grafana Alloy for more information about deploying Alloy in your environment.

Next steps

Configure Alloy

Run Grafana Alloy in a Podman container

Mon, 30 Mar 2026 15:47:22 +0000

Run Grafana Alloy in a Podman container

Podman is a container engine that runs without a daemon for developing, managing, and running Open Container Initiative (OCI) containers. You can use Podman as a drop-in replacement for Docker to run Alloy.

Alloy is available as a Docker container image that you can use with Podman on the following platforms:

Linux for AMD64 and ARM64.
macOS for AMD64 (Intel) and ARM64 (Apple Silicon).
Windows for AMD64.

Note
On macOS and Windows, Podman runs containers in a Linux virtual machine managed by podman machine. The container commands are the same across all platforms once the machine is running.

Before you begin

Install Podman or Podman Desktop on your computer.
On macOS or Windows, initialize and start the Podman machine:
shell
```
podman machine init
podman machine start
```
Create and save an Alloy configuration file on your computer, for example:
Alloy
```
logging {
  level  = "info"
  format = "logfmt"
}
```

Run a rootless Podman container

One of the key features of Podman is the ability to run containers without root privileges. To run Alloy as a rootless Podman container, run the following command in a terminal window:

podman run \
  -v <CONFIG_FILE_PATH>:/etc/alloy/config.alloy:Z \
  -p 12345:12345 \
  docker.io/grafana/alloy:latest \
    run --server.http.listen-addr=0.0.0.0:12345 --storage.path=/var/lib/alloy/data \
    /etc/alloy/config.alloy

Replace the following:

<CONFIG_FILE_PATH>: The absolute path of the configuration file on your host system.

Note
The :Z suffix on the volume mount is required on Linux systems with Security-Enhanced Linux enabled (such as Fedora, RHEL, and CentOS) to set the correct security context for the mounted file.

If you’re running on macOS, Windows, or a Linux system without Security-Enhanced Linux, you can omit the :Z suffix.

You can modify the last line to change the arguments passed to the Alloy binary. Refer to the documentation for run for more information about the options available to the run command.

Note
Make sure you pass --server.http.listen-addr=0.0.0.0:12345 as an argument as shown in the example. If you don’t pass this argument, the [debugging UI][UI] won’t be available outside of the Podman container.

Run a Podman container with root privileges

If you need to run Alloy with root privileges, for example to access host-level resources, run the following command:

sudo podman run \
  -v <CONFIG_FILE_PATH>:/etc/alloy/config.alloy:Z \
  -p 12345:12345 \
  docker.io/grafana/alloy:latest \
    run --server.http.listen-addr=0.0.0.0:12345 --storage.path=/var/lib/alloy/data \
    /etc/alloy/config.alloy

Replace the following:

<CONFIG_FILE_PATH>: The absolute path of the configuration file on your host system.

Run with systemd integration on Linux

On Linux, Podman integrates with systemd to manage containers as services. To generate a systemd unit file for Alloy:

Run the container with a name:

podman run -d --name alloy \
  -v <CONFIG_FILE_PATH>:/etc/alloy/config.alloy:Z \
  -p 12345:12345 \
  docker.io/grafana/alloy:latest \
    run --server.http.listen-addr=0.0.0.0:12345 --storage.path=/var/lib/alloy/data \
    /etc/alloy/config.alloy

Replace the following:

<CONFIG_FILE_PATH>: The absolute path of the configuration file on your host system.

Generate a systemd unit file:

podman generate systemd --name alloy --files --new

Move the generated file to the systemd directory:
shell
```
mv container-alloy.service ~/.config/systemd/user/
```

Reload systemd and enable the service:

systemctl --user daemon-reload
systemctl --user enable --now container-alloy.service

Use Podman Compose

If you prefer using Compose files, Podman supports Docker Compose files through podman-compose.

Create a compose.yaml file:

services:
  alloy:
    image: docker.io/grafana/alloy:latest
    ports:
      - "12345:12345"
    volumes:
      - <CONFIG_FILE_PATH>:/etc/alloy/config.alloy:Z
    command:
      - run
      - --server.http.listen-addr=0.0.0.0:12345
      - --storage.path=/var/lib/alloy/data
      - /etc/alloy/config.alloy

Replace the following:

<CONFIG_FILE_PATH>: The absolute path of the configuration file on your host system.

Run the container:
shell
```
podman-compose up -d
```

BoringCrypto images

Note
BoringCrypto support is in Public preview and is only available on AMD64 and ARM64 platforms.

BoringCrypto images are published with every release starting with version 1.1:

The current BoringCrypto image is published as docker.io/grafana/alloy:boringcrypto.
A specific version of the BoringCrypto image is published as docker.io/grafana/alloy:<VERSION>-boringcrypto, such as docker.io/grafana/alloy:v1.1.0-boringcrypto.

Verify

To verify that Alloy is running successfully, navigate to http://localhost:12345 and make sure the Alloy UI loads without error.

You can also check the container status:

podman ps

Next steps

Configure Alloy

Install Grafana Alloy with Puppet

Mon, 30 Mar 2026 15:47:22 +0000

Install Grafana Alloy with Puppet

You can use Puppet to install and manage Alloy.

Before you begin

These steps assume you already have a working Puppet setup.
You can add the following manifest to any module.
The manifest installs Alloy from the package repositories. It targets Linux systems from the following families:
- Debian, including Ubuntu
- RedHat Enterprise Linux, including Fedora

Steps

To add Alloy to a host:

Make sure that the following module dependencies are declared and installed:

{
"name": "puppetlabs/apt",
"version_requirement": ">= 4.1.0 <= 7.0.0"
},
{
"name": "puppetlabs/yumrepo_core",
"version_requirement": "<= 2.0.0"
}

Create a Puppet manifest with the following class to add the Grafana package repositories, install the alloy package, and run the service:

class grafana_alloy::grafana_alloy () {
  case $::os['family'] {
    'debian': {
      apt::source { 'grafana':
        location => 'https://apt.grafana.com/',
        release  => '',
        repos    => 'stable main',
        key      => {
          id     => 'B53AE77BADB630A683046005963FA27710458545',
          source => 'https://apt.grafana.com/gpg.key',
        },
      } -> package { 'alloy':
        require => Exec['apt_update'],
      } -> service { 'alloy':
        ensure    => running,
        name      => 'alloy',
        enable    => true,
        subscribe => Package['alloy'],
      }
    }
    'redhat': {
      yumrepo { 'grafana':
        ensure   => 'present',
        name     => 'grafana',
        descr    => 'grafana',
        baseurl  => 'https://rpm.grafana.com',
        gpgkey   => 'https://rpm.grafana.com/gpg.key',
        enabled  => '1',
        gpgcheck => '1',
        target   => '/etc/yum.repos.d/grafana.repo',
      } -> package { 'alloy':
      } -> service { 'alloy':
        ensure    => running,
        name      => 'alloy',
        enable    => true,
        subscribe => Package['alloy'],
      }
    }
    default: {
      fail("Unsupported OS family: (${$::os['family']})")
    }
  }
}

To use this class in a module, add the following line to the module’s init.pp file:
ruby
```
include grafana_alloy::grafana_alloy
```

Configuration

The alloy package installs a default configuration file that doesn’t send telemetry anywhere.

The default configuration file location is /etc/alloy/config.alloy. You can replace this file with your own configuration, or create a configuration file for the service to use.

Next steps

Configure Alloy