Getting started

This page walks through what you need to clone, build, test, and run the Datadog Agent locally.

Prerequisites

The Agent has a complex toolchain because it spans Go, Python, C, eBPF, and Rust, and it ships on three operating systems. The project provides a wrapper, dda, that installs and pins all of it.

Install dda

dda is the project's developer CLI. Almost every command in this repository is invoked through dda inv ….

# macOS
brew install --cask dda

# Linux / Windows: see https://datadoghq.dev/dda/install/

Once installed, run dda inv install-tools from the repo root. This pulls down Go, the right Go module dependencies, golangci-lint, mockery, protoc, and the other auxiliary binaries pinned in the repo.

Toolchain pins

A few files document the canonical versions of each toolchain:

File	What it pins
.go-version	Go compiler version
.python-version	Python version
rust-toolchain.toml	Rust toolchain for rust/
.bazelversion	Bazel version
.dda/	dda's own configuration

You normally do not interact with these directly. dda reads them and provisions the matching toolchain.

Optional: Bazel

The project is migrating to Bazel. If you intend to build packages or work on eBPF code, install Bazel at the version pinned in .bazelversion. dda inv install-tools covers most cases; bazelisk is a convenient launcher.

Clone

git clone https://github.com/DataDog/datadog-agent.git
cd datadog-agent

The default branch is main. Release branches follow the 7.NN.x pattern.

Build

The Agent has many possible build configurations because Go build tags select which subsystems are compiled in. Always use dda inv rather than calling go build directly — it computes the correct tag combination for each binary. From AGENTS.md:

This project uses extensive custom Go build tags. Most source files are ignored by the standard Go toolchain unless the correct tags are passed.

Common builds:

# Core Agent (omit systemd if you don't need journald log support)
dda inv agent.build --build-exclude=systemd

# Other binaries
dda inv dogstatsd.build
dda inv trace-agent.build
dda inv system-probe.build
dda inv cluster-agent.build
dda inv security-agent.build
dda inv process-agent.build
dda inv installer.build
dda inv otel-agent.build

Bazel-built distribution packages:

bazel build //packages/agent/linux:debian
bazel build //packages/agent/linux:rpm

To keep BUILD.bazel files in sync with Go module dependencies after editing go.mod:

dda inv tidy

The full list of build tags lives in tasks/build_tags.py. See Reference: build tags for a digest.

Test

# Whole project (slow)
dda inv test

# A specific package
dda inv test --targets=./pkg/aggregator

# Bazel-driven
bazel test //pkg/aggregator/...

End-to-end tests live in test/new-e2e/ and provision real cloud resources:

# Run E2E tests for one area
dda inv new-e2e-tests.run --targets=./tests/agent-platform/...

E2E tests use fakeintake (test/fakeintake/) — a local mock of the Datadog intake — to assert on outgoing payloads. See Testing for the longer story.

Lint

# Go (golangci-lint with the project's config)
dda inv linter.go

# All linters at once: Go, Python, YAML, shell, copyright, etc.
dda inv linter.all

Lint rules live in .golangci.yml, .pre-commit-config.yaml, and the per-language config files at the repo root.

Run locally

After building, the Agent looks for configuration under bin/agent/dist/. The simplest local setup:

# Create a dev config with a placeholder API key
mkdir -p dev/dist
echo "api_key: 0000001" > dev/dist/datadog.yaml

# Build (the build copies dev/dist/ to bin/agent/dist/)
dda inv agent.build --build-exclude=systemd

# Run
./bin/agent/agent run -c bin/agent/dist/datadog.yaml

The Agent will start collecting host metrics and emitting them to the configured intake. With the placeholder key it will fail to authenticate on upload — that is expected for local testing. To test against a real intake, set api_key to a valid Datadog API key. To capture payloads without sending them anywhere, point the Agent at a local fakeintake.

Run a check

Once the Agent is running, exercise the check runtime:

# List all configured checks
./bin/agent/agent configcheck

# Run a single check once and print the output
./bin/agent/agent check cpu

# Stream metrics being aggregated
./bin/agent/agent dogstatsd-stats

For the full list of agent subcommands, see Apps: Agent.

Where to go next

• Development workflow — branch, code, test, PR cycle.
• Tooling — dda inv task catalog, Bazel notes, pre-commit.
• Debugging — flares, expvar, pprof, gohai.
• Architecture — how the binaries fit together.