# digitalocean/do-agent: Droplet metrics shipped to DigitalOcean's monitoring backend

> do-agent is the Apache-2.0 Go binary that reads /proc and /sys on a Droplet and pushes resource metrics to DigitalOcean for graphs and alerting. It is a single-vendor telemetry shipper, not a general monitoring stack.

**digitalocean/do-agent** — Collects system metrics from DigitalOcean Droplets

- Repository: https://github.com/digitalocean/do-agent
- Stars: 618 · Forks: 117
- Language: Go
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/digitalocean-do-agent

## What do-agent is for, and who it is not for

do-agent exists to feed one consumer: DigitalOcean. The README states that it "enables droplet metrics to be gathered and sent to DigitalOcean to provide resource usage graphs and alerting." That sentence defines both the scope and the ceiling. The agent is a shipper, not a store. It has no query language, no dashboard of its own, and no local retention. If you want resource graphs on a Droplet, the data has to reach DigitalOcean's backend for those graphs to exist.

The audience is therefore narrow and clear: people running Droplets who want the platform's Monitoring tab populated. The README points at the Droplet create screen, where a Monitoring checkbox installs the latest stable version, and at the OS package manager (yum, dnf, apt-get) for updates afterwards. Anyone already inside that workflow gets the agent for free. Anyone who wants Prometheus-style scraping into their own storage is looking at the wrong tool, even though the dependency list in go.mod includes github.com/prometheus/client_golang and github.com/prometheus/node_exporter.

A practical consequence: do-agent is not a substitute for a full observability stack. It answers "what is this Droplet doing" for DigitalOcean's UI. It does not answer "what is this service doing" or "why did latency spike at 03:00" for you.

## How the agent reads a Droplet: procfs, sysfs and a snappy-encoded push

The mechanism is visible in the repository layout and the Dockerfile. The container image ends with an entrypoint that runs the binary with two path flags: --path.procfs and --path.sysfs. Those flags are the agent's entire input surface. It reads Linux kernel interfaces rather than instrumenting applications, so a Droplet with no application code at all still produces CPU, memory, disk and network numbers.

The Dockerfile sets those flags to /host/proc and /host/sys, which is why the README tells container users to mount the host directory /proc to /host/proc. The VOLUME line declares /host/proc and /host/sys, and the README's docker run example adds :ro to both bind mounts. Read-only is the correct posture: the agent has no reason to write into kernel pseudo-filesystems.

The dependency list explains the output path. go.mod requires github.com/golang/snappy, a compression library, alongside the Prometheus client and procfs packages. That combination is consistent with collecting metrics in a Prometheus-shaped model, compressing the payload, and pushing it outbound over HTTPS to DigitalOcean rather than waiting to be scraped. The README's SELinux note confirms the outbound direction: without nis_enabled set to 1, the agent "cannot reach the network to perform authentication or send metrics to DigitalOcean backend servers." Authentication and delivery are both outbound operations, which is the opposite of a pull-based exporter.

Build metadata is injected at link time. The Makefile's ldflags set main.version, main.revision and main.buildDate from the git tag, the short commit hash and the build timestamp. That matters when you are trying to work out which binary a Droplet is actually running.

## Installing do-agent from the package repository

The README's primary install path is a script served from repos.insights.digitalocean.com, piped into a root shell. That is the fastest route and also the one that asks the most trust, which is why the README offers an inspection variant.

The one-liner, for hosts where you are comfortable piping a remote script to bash:

```bash
curl -sSL https://repos.insights.digitalocean.com/install.sh | sudo bash
```

wget works the same way, per the README:

```bash
wget -qO- https://repos.insights.digitalocean.com/install.sh | sudo bash
```

If you would rather read the script before running it, download it first, inspect it, then execute it. The README gives exactly this sequence:

```bash
curl -L -o ./install.sh https://repos.insights.digitalocean.com/install.sh
less ./install.sh
sudo ./install.sh
```

After the script runs, the README says to manage the agent with the distribution's package manager, so apt-get, yum or dnf will handle later upgrades. On an SELinux host, the script sets nis_enabled to 1; if you install manually or reverse that flag, the README states you must run setsebool -P nis_enabled 1 && systemctl daemon-reexec or the agent will not operate at all.

The alternative install, for container hosts, mounts the host kernel interfaces read-only and runs the published stable image:

```bash
docker run \
        -v /proc:/host/proc:ro \
        -v /sys:/host/sys:ro \
        digitalocean/do-agent:stable
```

What you should see after either route is metrics appearing in the Droplet's resource graphs in the DigitalOcean control panel. The README does not document a --version flag, a status subcommand or a log file location, so verifying a running agent means checking the service through systemctl or the container runtime rather than a do-agent command.

## Where do-agent stops being the right answer

The strongest limitation is stated plainly in the README's own note: DigitalOcean officially supports Ubuntu from the oldest End Of Standard Support LTS release onward, Debian from the oldest supported LTS release onward, Fedora 27+, CentOS 6+, and Docker. CloudLinux 6+ is listed under "Not officially supported." The README then says do-agent works on most Linux distributions but that "any issues you encounter will not have official support from DigitalOcean." That is a real support boundary, not a formality. If you run an unsupported distribution in production, you own the failure.

SELinux is the second sharp edge. The install script mutates a system-wide boolean, nis_enabled, which is a broader change than most agents make. The README explains why (network access for authentication and metric delivery) and gives the manual command, but it also warns that reversing the action breaks the agent. Hardened environments that treat SELinux booleans as audited configuration should know this before running the script.

The third limitation is architectural rather than operational. There is no documented way to point do-agent at your own endpoint, no scrape port to configure, and no retention. The README documents exactly two ends of the pipe: the Droplet's /proc and /sys, and DigitalOcean's backend. If your requirement is a metrics pipeline you control, this agent is not a component you can repurpose. A Prometheus node_exporter deployment is the honest comparison: node_exporter exposes an HTTP endpoint that any compatible scraper can pull from, so the storage and query layer stays yours. do-agent pushes to one vendor's backend by design, and go.mod's node_exporter dependency reflects shared collection code, not shared deployment model.

The README also does not document rollback. Uninstall is covered (apt-get remove do-agent on Debian-based systems, yum remove do-agent on RHEL-based ones), but there is no documented procedure for reverting the nis_enabled change, and no mention of what happens to historical metrics after removal.

## Building do-agent from source and the version you actually get

The README's development section requires Go 1.11 or later, GNU Make and Docker, and go.mod declares go 1.22, so the module's own floor is the stricter of the two. The build runs through Docker by default: the Makefile's go variable invokes a golang image tagged with the version parsed out of go.mod, sets GO111MODULE=on, GOFLAGS=-mod=vendor, CGO_ENABLED=0 and GOOS/GOARCH, and mounts the working directory. Setting DOCKER_BUILD=1 switches to a local Go toolchain, which is what the Dockerfile does inside its build stage.

```bash
git clone git@github.com:digitalocean/do-agent.git
cd do-agent
make
```

Adding a dependency means exporting the module flags first, then vendoring. The README recommends direnv to set these from the project's .envrc, or setting them by hand:

```bash
export GO111MODULE=on GOFLAGS=-mod=vendor
go mod vendor
```

Because the repository vendors its dependencies, the vendor/ directory is part of the tree and the build does not need network access to resolve modules. That is convenient for reproducible builds and annoying for anyone who expects go get to work without the vendor flag.

The Makefile derives VERSION from the latest git tag via git describe --tags --abbrev=0 and strips a leading v, so a source build reports a tag rather than an arbitrary string. The release history shows 3.18.14 on 2026-05-14, 3.18.12 on 2026-04-23 and 3.18.10 on 2026-03-24, all within the 3.18 line. The repository's last push was on 2026-09-07, which is recent; the project is not archived. That said, the last tagged release is roughly four months before the last push, so commit activity and release cadence are not the same thing here.

## Licence and the cost of keeping it current

do-agent is Apache-2.0, which permits commercial use, modification and redistribution provided the licence and notices are preserved. The LICENSE file sits at the repository root. One thing worth noting for anyone embedding it: the repository vendors third-party code under vendor/, and those dependencies carry their own licences, so an Apache-2.0 label on the project does not mean every file in the tree is Apache-2.0. If you redistribute a binary built from this tree, the vendored dependency licences travel with it. This is a description of the repository layout, not legal advice; a licence audit is a question for your own counsel.

Upgrade cost is low if you install through the package manager, because the README says to use apt-get, yum or dnf to update and manage the agent. The install script writes the repository configuration, and after that the distro handles versions. Container users pull a new digitalocean/do-agent:stable tag and restart, which is a redeploy rather than an in-place upgrade. Source builders pay the most: the Makefile pins the Go toolchain by parsing go.mod, so a Go version bump in go.mod changes the build image tag, and vendored dependencies have to be refreshed with go mod vendor.

There is no documented configuration file, no documented environment variable set and no documented flags beyond --path.procfs and --path.sysfs. That cuts both ways. There is almost nothing to misconfigure, and almost nothing to tune when the agent behaves unexpectedly.

## Conclusion

Adopt do-agent if your fleet is DigitalOcean Droplets and you want the Monitoring graphs and alerts the platform draws from agent data; the install script and the distro packages make that a one-line change. Skip it if you need a vendor-neutral metrics pipeline, a configurable scrape target, or support on distributions outside the documented list, because the README makes clear that unofficial distros get no official support. Verify first that the Droplet's distribution is on the supported list, that SELinux hosts have nis_enabled set to 1, and that a read-only /proc and /sys mount exists if you plan to run the container image.

## FAQ

### How do I install do-agent on a DigitalOcean Droplet?

The README gives a one-line install script from repos.insights.digitalocean.com piped to sudo bash, or you can select the Monitoring checkbox on the Droplet create screen to get the latest stable version. After installation, the README says to use apt-get, yum or dnf to update and manage the agent.

### Which operating systems does do-agent support?

The README lists Ubuntu from the oldest End Of Standard Support LTS release onward, Debian from the oldest supported LTS release onward, Fedora 27+, CentOS 6+, and Docker. CloudLinux 6+ is listed as not officially supported, and the README states that issues on other distributions get no official support.

### What does do-agent do with the metrics it collects?

It sends them to DigitalOcean, where the README says they provide resource usage graphs and alerting. Collection reads the host's /proc and /sys, which is why the container example mounts both read-only.

### Can I run do-agent as a Docker container?

Yes. The README's example mounts /proc to /host/proc and /sys to /host/sys as read-only volumes and runs digitalocean/do-agent:stable. The Dockerfile sets the entrypoint to pass --path.procfs /host/proc and --path.sysfs /host/sys to the binary.

## Sources

- [digitalocean/do-agent on GitHub](https://github.com/digitalocean/do-agent)
- [Issues](https://github.com/digitalocean/do-agent/issues)
- [License: Apache-2.0](https://github.com/digitalocean/do-agent/blob/master/LICENSE)
- [README](https://github.com/digitalocean/do-agent/blob/master/README.md)
- [Releases](https://github.com/digitalocean/do-agent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/digitalocean-do-agent