---
title: "Build a custom Grafana Alloy binary with the OpenTelemetry Collector Builder (OCB) | Grafana Alloy documentation"
description: "Learn how to build a customized Grafana Alloy binary with the OpenTelemetry Collector Builder"
---

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

# Build a custom Grafana Alloy binary with the OpenTelemetry Collector Builder (OCB)

Grafana builds the OTel Engine from a declarative [OpenTelemetry Collector Builder (OCB)](https://opentelemetry.io/docs/collector/custom-collector/) manifest. If you need additional components or want to remove bundled components, edit the manifest and build a customized Alloy binary.

> Caution
> 
> Grafana doesn’t offer commercial support for custom builds.

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

- Git
- Go 1.26.7 or later
- Node.js
- Docker, if you want to build the container image

The build compiles C dependencies, so you also need the following for your platform:

- On Linux, the systemd headers. On Debian-based distributions, run `sudo apt-get install libsystemd-dev`.
- On Windows, a 64-bit [mingw-w64](https://www.mingw-w64.org/) gcc toolchain. Grafana recommends the [WinLibs](https://winlibs.com/) build.

## Build a custom binary

1. Clone the Alloy repository and change to the repository root. The following steps assume you run commands from this directory.
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   git clone https://github.com/grafana/alloy.git
   cd alloy
   ```
   
   To build from a specific release, fetch tags and check out the tag after you clone:
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   git fetch --tags
   git checkout <RELEASE_TAG>
   ```
   
   Replace *`<RELEASE_TAG>`* with the [release tag](https://github.com/grafana/alloy/releases) you want.
2. Add or remove components by editing the OCB manifest in [`collector/builder-config.yaml`](https://github.com/grafana/alloy/blob/main/collector/builder-config.yaml).
   
   To remove a component, delete its entire entry from the appropriate section. To add a component, append an entry that points at the module path and version you want. Follow the same `- gomod:` pattern as the other entries.
3. Build the full Alloy binary.
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   make alloy
   ```
   
   This command regenerates the collector distribution from the manifest before it builds, so your manifest edits take effect. The binary in `build/` behaves like a standard `alloy` build. To skip the UI build when the UI assets already exist, run `SKIP_UI_BUILD=1 make alloy`. Use [`alloy otel`](../../../reference/cli/otel/) to run collector YAML against your custom bundle.
4. Confirm that your components are in the build.
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   ./build/alloy otel components
   ```
   
   The command lists each bundled component with its module path, version, and stability level.
5. Optional: Build the Alloy Docker image.
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   make alloy-image ALLOY_IMAGE=<REGISTRY>/<IMAGE_NAME>:<TAG>
   ```
   
   Set `ALLOY_IMAGE` to your own registry and image name.
   
   Replace the following:
   
   - *`<REGISTRY>`* : Your container registry.
   - *`<IMAGE_NAME>`* : Your image name.
   - *`<TAG>`* : Your image tag.