NGINX Agent v3: remote configuration and metrics for NGINX instances

What NGINX Agent actually manages, and who ends up running it

The README describes NGINX Agent as "a companion application designed to efficiently manage NGINX instances," with two headline capabilities: remote management and real-time metrics. Read that literally. The agent is not a monitoring server, not a dashboard, and not a configuration store. It is the process that sits next to each nginx binary, watches it, and talks to something else.

The audience follows from that shape. If you run one NGINX host and edit nginx.conf by hand, the agent adds a moving part for no benefit. If you run dozens or hundreds of instances and want configuration changes and performance data to arrive through one interface rather than a loop of SSH sessions, the agent is the piece that makes that possible. The repository topics list agent, api, metrics, metrics-gathering, monitoring-tool, nginx-configuration and observability, which matches the two-sided job: push configuration down, pull telemetry up.

One detail worth noticing is the naming. The README title is "F5 NGINX Agent," and the primary call to action points at an NGINX One free enterprise trial. The open source repository is the agent itself; the management experience it plugs into is a commercial product. That is the central trade-off of adopting it, and it should shape how you read everything below.

How the agent is put together: Go, gRPC, OpenTelemetry and a file watcher

The dependency list in go.mod is the clearest available description of the architecture. The module is github.com/nginx/agent/v3 and the toolchain is Go 1.27.1, so this is a statically compiled Go binary rather than a script or a sidecar in another runtime.

Several dependencies point at distinct responsibilities. github.com/grpc-ecosystem/go-grpc-middleware/v2 indicates gRPC as the transport to the management side. The buf.build/go/protovalidate and protobuf entries indicate protocol buffer definitions with validation, and the repository has an api/ directory where those definitions live. On the collection side, a large set of github.com/open-telemetry/opentelemetry-collector-contrib components is imported: the Prometheus exporter, the stanza log receiver, plus attributes, filter and deltatorate processors. That means the metric pipeline is assembled from OpenTelemetry Collector building blocks rather than written from scratch, which is why the agent can expose metrics in a Prometheus-compatible form and process log streams.

github.com/fsnotify/fsnotify and github.com/nxadm/tail cover the local side: watching files for changes and tailing logs. github.com/nginx/nginx-plus-go-client/v3 is the NGINX Plus API client, so NGINX Plus instances get richer data than open source NGINX, which the agent has to read from other sources. There is also a default.pgo file at the repository root, a Go profile-guided optimization artifact, and a catalog/ directory that most likely holds the metric and event definitions the agent knows how to emit.

A final piece of the layout: the repository ships both an nginx-agent.conf file and a templates/ directory, so configuration is file-based and templated rather than purely flag-driven.

Installing NGINX Agent and connecting a first instance

The README does not inline install commands. It gives three routes: the official documentation page "How to add an instance," the GitHub releases page for binaries and packages, and the NGINX Agent installation and upgrade guide. Because the README points at those rather than reproducing them, treat the documentation as the source of truth for flags and paths.

Since the module path is github.com/nginx/agent/v3 and the Makefile defines standard Go targets, building from source is the route you can reason about from the repository alone. The Makefile reads the toolchain version out of go.mod, so the build expects the Go version declared there:

git clone https://github.com/nginx/agent.git
cd agent
make build

The Makefile variables show what that target wraps: GOBUILD is $(GOCMD) build, and GOTEST, GOVET, GOGEN and GORUN are defined the same way. If you prefer to invoke Go directly rather than through the Makefile, the module path tells you the package to build. Expect a binary, not a service unit; the README does not document a systemd unit or a container image, and the packaging Makefiles (Makefile.packaging, Makefile.containers, .nfpm.yaml) exist in the tree but their contents are not reproduced in the README.

For configuration, the repository root holds nginx-agent.conf. The README does not print its contents, so read it from your checkout rather than from any example here. The same applies to the management endpoint: the README's first installation route is the NGINX One "add an instance" flow, which is where the connection details for a control plane come from. There is no documented standalone mode in the README, so plan on having an endpoint to point the agent at before you start it.

When the agent is running, the README's promised output is remote management plus real-time metrics for NGINX and the underlying operating system. The repository has a test/ directory and a docs/ directory if you want to see how the maintainers exercise it, and a cmd/ directory that holds the entry points.

The control plane dependency, and where the agent is the wrong tool

The most consequential limitation is structural, not technical. NGINX Agent is one half of a client-server relationship, and the README only ships the client half. Its primary installation path is the NGINX One add-instance guide, and the README's own call to action is an enterprise trial. If your goal is a self-contained observability stack with no external dependency, this is the wrong component: you would be adopting an agent whose documented happy path terminates in a commercial console.

The second limitation is version fragmentation. The useful links section lists two documentation sets, one for v2 and one for v3, and the release list shows both lines still receiving tags (v3.12.0, v3.11.4, and v2.46.9 within weeks of each other). The go.mod module path is v3. Nothing in the README explains how the two lines differ or when v2 stops mattering. If you are already running v2 agents, you cannot tell from the README alone whether the upgrade is a drop-in or a migration, and the installation guide is where that answer would have to live.

The third is scope. The agent collects metrics and events and pushes configuration. It does not store them, alert on them, or render them. It also does not replace a configuration management system for the rest of the host: it manages NGINX, not the operating system around it. Teams that expect one tool to cover provisioning, secrets and NGINX configuration will find the boundary in the wrong place.

How it differs from nginx-prometheus-exporter and from agentless collection

The closest well-known alternative is nginx-prometheus-exporter, and the dependency list makes the comparison concrete: github.com/nginx/nginx-prometheus-exporter is imported by the agent. So the agent contains an exporter rather than competing with one.

The difference is direction and scope. A standalone Prometheus exporter is read-only and one-way: Prometheus scrapes an HTTP endpoint, and configuration on the NGINX host does not change as a result. NGINX Agent adds the reverse channel. It watches local files with fsnotify, tails logs with nxadm/tail, and speaks gRPC to a management endpoint, which is what makes remote configuration possible at all. It also folds log collection into the same process through the OpenTelemetry stanza receiver, where an exporter-only setup would need a separate log shipper.

The trade-off is dependency weight. Pulling in the OpenTelemetry Collector contrib modules, the NGINX Plus client and gRPC middleware produces a much larger binary and a much larger dependency surface than a single-purpose exporter, and it only pays off if you actually use the remote management channel. If all you want is a /metrics endpoint for Prometheus, the exporter alone is the smaller and simpler answer. The second alternative is agentless collection: scraping the NGINX stub_status endpoint and reading config files over SSH or from a configuration repository. That keeps zero long-running processes on the host, but it cannot push a validated configuration change back, and it gives you no event stream from the instance itself.

Maintenance, release cadence and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-10, ten days before this writing. Releases are frequent: v3.12.0 on 2026-09-09, v3.11.4 on 2026-08-27, and v2.46.9 on 2026-08-28. Two maintained lines means two upgrade paths to track, and the v2 line is still tagged, so anyone on v2 has to decide when to move rather than being forced by abandonment.

Upgrade cost is governed by the packaging story, which the README does not spell out. The tree contains .nfpm.yaml for package generation, Makefile.packaging, Makefile.containers and a dependencies.Dockerfile, so distribution packages and container builds exist, but the README does not describe an upgrade procedure, a rollback path, or how configuration migrates between major versions. That gap matters more than usual here because the agent writes configuration to NGINX: a version mismatch between agent and control plane is a plausible failure mode, and the README does not document how the agent behaves when it meets an endpoint it does not understand.

The licence is Apache-2.0, per the LICENSE file and the README badge. Apache-2.0 is permissive and includes an explicit patent grant, which is generally the least friction option for embedding a component in a commercial deployment. This is a description of the licence, not legal advice; if you redistribute the agent inside a product, have your own counsel review the NOTICE and attribution requirements. The licence covers the agent. It does not grant anything with respect to the NGINX One console the agent connects to, which is a separate commercial product.

Editorial conclusion

Adopt NGINX Agent if you run more than a handful of NGINX hosts and want configuration and metrics to flow through one control plane instead of per-host SSH sessions; the v3 line is where current work is happening, with the last push on 2026-09-10. Do not adopt it as a standalone monitoring stack: it is an agent, and without a management endpoint (the NGINX One console or your own integration against the api/ definitions) it does little on its own. Verify first that your NGINX One or self-managed control plane speaks the v3 protocol, since the README points v2 users to a different documentation set than v3 users, and confirm which of the two release lines your distribution packages map to before you roll it out.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. nginx/agent on GitHub
3. Project website
4. README
5. Releases