---
title: "Run the Grafana Alloy Engine extension | Grafana Cloud documentation"
description: "Learn how to run a Default Engine pipeline inside the Alloy OpenTelemetry Engine with the Grafana Alloy Engine extension"
---

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

# Run the Grafana Alloy Engine extension

You can run the OTel Engine and the Default Engine in the same process. Add the `alloyengine` extension to your OpenTelemetry Collector configuration to start a Default Engine pipeline alongside the OTel Engine pipeline. The two engines run in parallel and can’t exchange data with each other. If required, they can still communicate over the network via components like the OTLP exporter and receiver

Set exactly one of `config.path` or `config.inline.content`. The extension fails to start if you set both or neither.

> **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:

- 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).
- A Default Engine configuration file or directory.

## Run both engines

1. Add the `alloyengine` extension to your Collector configuration, and enable it in the `service` block:
   
   YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```yaml
   extensions:
     alloyengine:
       config:
         path: <ALLOY_CONFIG_PATH>
       flags:
         server.http.listen-addr: 0.0.0.0:12345
   
   service:
     extensions: [alloyengine]
   ```
   
   Replace *`<ALLOY_CONFIG_PATH>`* with the path to your Default Engine configuration file or directory. If you provide a directory, Alloy loads the `*.alloy` files in that directory as a single configuration source and ignores subdirectories.
   
   The `flags` map passes command-line flags to the Default Engine. Refer to [Pass flags to the Default Engine](#pass-flags-to-the-default-engine) for details.
   
   Keep your other `extensions` and `service.extensions` entries, and add `alloyengine` to them.
2. Start both engines:
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   alloy otel --config=config.yaml
   ```
   
   The output of both engines is visible in the logs.
3. Verify that the Default Engine runs by opening its UI at `localhost:12345`.

## Pass flags to the Default Engine

Use the optional `flags` map to pass command-line flags to the Default Engine. Write each flag without the leading `--`. The example sets `server.http.listen-addr` to `0.0.0.0:12345` so the Default Engine UI accepts connections from other hosts. The default address, `127.0.0.1:12345`, accepts connections only from the local host. Refer to the [run command reference](/docs/grafana-cloud/send-data/alloy/reference/cli/run) for the available flags.

[Clustering](/docs/grafana-cloud/send-data/alloy/get-started/clustering) is also supported this way, using the same `cluster.*` flags as the standalone Default Engine.

## Provide the configuration inline

To provide the Default Engine configuration inline, use `config.inline.content` instead of `config.path`:

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
extensions:
  alloyengine:
    config:
      inline:
        content: |
          logging {
            level = "info"
          }
```

The `module_path` Alloy configuration keyword resolves to the value of `config.inline.module_path`. If you don’t set `config.inline.module_path`, `module_path` resolves to the current working directory of the Collector process.

## Limitations

The Default Engine runs with some features disabled in extension mode. The `remotecfg` block isn’t supported, and configuration reload isn’t available. Use OpenTelemetry OpAMP for configuration management instead.

If the Default Engine configuration fails to load, the extension retries with exponential backoff, starting at 2 seconds and capping at 15 seconds. The Collector still reports the extension as ready, so a broken configuration doesn’t stop the OTel Engine. Check the `/-/ready` and `/-/healthy` endpoints of the Default Engine HTTP server for its actual state.

> Warning
> 
> Only one `alloyengine` extension can be active per process. If you configure more than one, the first extension to start succeeds, the rest fail, and the Collector doesn’t start.

## Embed the extension in another distribution

You can embed the `alloyengine` extension into any other OpenTelemetry Collector distribution with the OpenTelemetry Collector Builder (OCB). Refer to [Include `alloyengine` extension in an OCB distribution](https://github.com/grafana/alloy/blob/main/extension/alloyengine/README.md#include-alloyengine-extension-in-an-ocb-distribution) for instructions.