---
title: "Run the Alloy OpenTelemetry Engine with the CLI | Grafana Alloy documentation"
description: "Learn how to run the Alloy OpenTelemetry Engine with the Alloy CLI"
---

> 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 the CLI

The OTel Engine is available under the Alloy `otel` command. Use the CLI to experiment locally or to run the OTel Engine on a single host. Refer to the [`otel`](../../../reference/cli/otel/) reference documentation for more information.

> **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 Alloy installed. Refer to [Install Grafana Alloy](../../install/) for more information.

## Run the OTel Engine

1. Create a configuration file named `config.yaml`. The following example accepts traces over [OTLP](https://opentelemetry.io/docs/specs/otel/protocol/) and prints it to the console:
   
   YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```yaml
   receivers:
     otlp:
       protocols:
         grpc: {}
         http: {}
   
   processors:
     batch:
       timeout: 1s
       send_batch_size: 512
   
   exporters:
     debug:
       verbosity: detailed
   
   service:
     pipelines:
       traces:
         receivers: [otlp]
         processors: [batch]
         exporters: [debug]
   ```
2. Check the configuration:
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   alloy otel validate --config=config.yaml
   ```
3. Start the OTel Engine:
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   alloy otel --config=config.yaml
   ```
   
   To pass extra command-line flags, refer to the [`otel` command reference](../../../reference/cli/otel/).
4. 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
   ```

Alloy then accepts incoming OTLP traces on `localhost:4317` for gRPC and `localhost:4318` for HTTP requests. Metrics are also available on the default collector port and endpoint at `localhost:8888/metrics`.

The Default Engine isn’t running, so its UI at `localhost:12345` and its metrics at `localhost:12345/metrics` aren’t available.

## Send data to Grafana Cloud

The following example configuration accepts telemetry over OTLP and sends it to Grafana Cloud:

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

```yaml
extensions:
  basicauth/my_auth:
    client_auth:
      username: "<USERNAME>"
      password: "<PASSWORD>"

receivers:
  otlp:
    protocols:
      grpc: {}
      http: {}

processors:
  batch:
    timeout: 1s
    send_batch_size: 512

exporters:
  otlp_http/my_backend:
    endpoint: <URL>
    auth:
      authenticator: basicauth/my_auth

service:
  extensions: [basicauth/my_auth]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http/my_backend]
```

Replace the following:

- *`<USERNAME>`* : Your Grafana Cloud instance ID.
- *`<PASSWORD>`* : Your Grafana Cloud API token.
- *`<URL>`* : Your Grafana Cloud OTLP endpoint URL.

For more information about where to find these values, refer to [Send data using OpenTelemetry Protocol](/docs/grafana-cloud/send-data/otlp/send-data-otlp/).

## Manage with Grafana Fleet Management

Use the embedded `otel-supervisor` command to manage the OTel Engine through Grafana Fleet Management. The supervisor starts Alloy and receives OpenTelemetry Collector configuration from Grafana Fleet Management through OpAMP.

Refer to [`otel-supervisor`](../../../reference/cli/otel-supervisor/) for setup instructions and required environment variables.