---
title: "Run the Alloy OpenTelemetry Engine with service installations | Grafana Cloud documentation"
description: "Learn how to run the Alloy OpenTelemetry Engine from an Alloy service installation on Linux, macOS, or Windows"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Run the Alloy OpenTelemetry Engine with service installations

The Alloy service installations for Linux, macOS, and Windows can run the OTel Engine instead of the Default Engine. Set `ALLOY_OTEL_MODE` to `1`, `true`, `yes`, or `on` to run the OTel Engine. Matching is case-insensitive. If you don’t set `ALLOY_OTEL_MODE`, or you set it to any other value, Alloy runs the Default Engine.

No service installer exposes an install-time flag for this setting. Set it with the platform-specific mechanism below, then restart the service.

> **EXPERIMENTAL**: OTel Engine is an [experimental](/docs/release-life-cycle/) feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement.
> 
> To maintain full compatibility of the OTel Engine with the upstream OpenTelemetry Collector and expose a compatible command line interface, the OTel Engine isn’t hidden behind a stability [flag](/docs/alloy/latest/reference/cli/run/).
> 
> Make sure that you understand the risks involved before using an experimental feature in your production environments.

## Before you begin

Make sure you have the following:

- Alloy installed as a service. Refer to [Install Grafana Alloy](/docs/grafana-cloud/send-data/alloy/set-up/install) for more information.
- An OpenTelemetry Collector configuration. To create one, refer to [Run the OTel Engine with the CLI](/docs/grafana-cloud/send-data/alloy/set-up/otel_engine/cli).

## Linux

Alloy is [installed](/docs/grafana-cloud/send-data/alloy/set-up/run/linux) as a systemd service on Linux. It reads `ALLOY_OTEL_MODE` from the systemd environment file.

To run the OTel Engine on Linux:

1. Edit the environment file for the service:
   
   - Debian or Ubuntu: Edit `/etc/default/alloy`
   - RHEL/Fedora or SUSE/openSUSE: Edit `/etc/sysconfig/alloy`
2. Set `ALLOY_OTEL_MODE=1`.
3. Edit the sample OpenTelemetry Collector configuration the package installs at `/etc/alloy/config.yaml`. The sample receives OTLP data and sends it to the `debug` exporter, which only writes to the console. Replace the `debug` exporter with a real backend. To use a different file, set `OTEL_CONFIG_FILE` to its path.
4. Optional: Set `OTEL_CUSTOM_ARGS` to pass additional command-line flags to the OTel Engine. This setting works the same way as `CUSTOM_ARGS` does for the Default Engine.
5. Check the configuration, and replace *`<OTEL_CONFIG_FILE>`* with the path configured above:
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   alloy otel validate --config=<OTEL_CONFIG_FILE>
   ```
6. Restart the service:
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   sudo systemctl restart alloy
   ```
7. Verify that the OTel Engine runs:
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   curl http://localhost:8888/metrics
   ```

Refer to [Pass additional command-line flags](/docs/grafana-cloud/send-data/alloy/configure/linux/#pass-additional-command-line-flags) for more information about the environment file.

## macOS

Alloy is [installed](/docs/grafana-cloud/send-data/alloy/set-up/run/macos) as a launchd service on macOS. It reads `ALLOY_OTEL_MODE` from the Homebrew environment file.

To run the OTel Engine on macOS:

1. Edit the file at `$(brew --prefix)/etc/alloy/config.env`.
2. Set `ALLOY_OTEL_MODE=1`.
3. Create your OpenTelemetry Collector configuration at `$(brew --prefix)/etc/alloy/config.yaml`. The Homebrew formula doesn’t create this file, and the service always loads it.
   
   To load an additional file, add `--config=<PATH>` to `$(brew --prefix)/etc/alloy/otel-extra-args.txt`. Alloy applies this flag after the default, so its values override the installer’s default where they overlap. Create `config.yaml` even when you use this option.
4. Optional: Add command-line flags for the OTel Engine to `$(brew --prefix)/etc/alloy/otel-extra-args.txt`. This file works the same way as `extra-args.txt` does for the Default Engine.
5. Check the configuration:
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   alloy otel validate --config=$(brew --prefix)/etc/alloy/config.yaml
   ```
6. Restart the service:
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   brew services restart grafana/grafana/alloy
   ```
7. Verify that the OTel Engine runs:
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   curl http://localhost:8888/metrics
   ```

Refer to [Configure environment variables](/docs/grafana-cloud/send-data/alloy/configure/macos/#configure-environment-variables) for more information about the environment file.

## Windows

Alloy is [installed](/docs/grafana-cloud/send-data/alloy/set-up/run/windows) as a Windows Service. It reads `ALLOY_OTEL_MODE` from the Windows registry at `HKLM\Software\GrafanaLabs\Alloy`.

To run the OTel Engine on Windows:

1. Open the Registry Editor and navigate to `HKEY_LOCAL_MACHINE\SOFTWARE\GrafanaLabs\Alloy`.
2. Set the string value `ALLOY_OTEL_MODE` to `1`.
3. Edit the sample OpenTelemetry Collector configuration the installer creates at `%PROGRAMFILES%\GrafanaLabs\Alloy\config.yaml`. The sample receives OTLP data and sends it to the `debug` exporter, which only writes to the log. Replace the `debug` exporter with a real backend. To use a different file, add `--config=<PATH>` to the multi-string value `OTelArguments`. Alloy applies this flag after the default, so its values override the installer’s default where they overlap.
4. Optional: Add command-line flags for the OTel Engine to the multi-string value `OTelArguments`. This value works the same way as `Arguments` does for the Default Engine.
5. Check the configuration:
   
   powershell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```powershell
   & "$env:PROGRAMFILES\GrafanaLabs\Alloy\alloy-windows-amd64.exe" otel validate --config="$env:PROGRAMFILES\GrafanaLabs\Alloy\config.yaml"
   ```
6. Restart the **Alloy** service from the Windows Services manager.
7. Verify that the OTel Engine runs:
   
   powershell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```powershell
   Invoke-WebRequest http://localhost:8888/metrics -UseBasicParsing
   ```

Refer to [Service configuration](/docs/grafana-cloud/send-data/alloy/set-up/install/windows/#service-configuration) for more information about the registry values Alloy uses.