Skip to content

Agent on Linux

The Hexcovery agent is a single static binary that runs as a systemd service and collects system metrics and host logs from a Linux server, shipping them to Hexcovery over gRPC.

This page covers installing and running the agent on a host. For Kubernetes, see Agent on Kubernetes. For the full config reference, see Configuring the agent.

What it collects

The Linux agent runs a set of collectors against the host's /proc filesystem:

Collector Metrics
Host CPU usage, load (1/5/15m), memory (total/used/available/cached/buffers/swap), process count, uptime
Disk Per-device read/write bytes, read/write ops, read/write time, I/O time
Filesystem Per-mount total/used/free bytes, inodes total/used/free, usage %
Network Per-interface bytes / packets / errors / drops, sent and received
Process Per-process CPU %, memory (RSS/VMS/data/shared), threads, state, command line, uptime

It also tails host logs — both files and journald units — and ships them alongside the metrics. See Configuring the agent for selecting which paths and units to tail and how to attribute them to a service and Project.

The collected metrics surface on the Hosts dashboard page and are queryable in OQL (for example, SELECT avg(cpu_usage_pct) FROM host LAST 1h).

Lightweight

A Linux host running all system collectors uses roughly 50–100m CPU and 50–100 MB of memory, and produces on the order of a few MB of metrics per day. Log volume depends entirely on how much your host logs.

Prerequisites

  • A Linux server (the agent ships as linux/amd64 and linux/arm64 binaries).
  • An API key for your organization — create one in the dashboard (see API keys).
  • Network access from the host to the Hexcovery ingest endpoint.

Install

The agent runs as a systemd service. The high-level steps are:

  1. Place the agent binary at /usr/local/bin/hexcovery-agent.
  2. Install the systemd unit at /etc/systemd/system/hexcovery-agent.service.
  3. Provide configuration — the agent reads /etc/hexcovery-agent/config.yaml and keeps state in /var/lib/hexcovery-agent/.
  4. Enable and start the service.
sudo cp hexcovery-agent /usr/local/bin/
sudo cp deploy/systemd/hexcovery-agent.service /etc/systemd/system/
sudo systemctl enable --now hexcovery-agent

Create /etc/hexcovery-agent/config.yaml with at least the endpoint and a profile, and supply the API key as an environment variable:

server:
  endpoint: ingest.hexcovery.com:4317   # your ingest endpoint
  tls: true
profile: linux                          # enables all system collectors

Provide the key via the environment (keeps it out of the config file):

HEXCOVERY_API_KEY=YOUR_API_KEY

See Configuring the agent for every option, including which collectors run and how logs are attributed.

Exact binary and endpoint values

The download location for the agent binary and your organization's exact ingest endpoint are shown in the dashboard. Use the values from your account rather than the placeholders above.

The linux profile enables all system collectors and disables the Kubernetes ones. See profiles for the full list.

Verify

After starting the service, check it's running and shipping data:

sudo systemctl status hexcovery-agent
sudo journalctl -u hexcovery-agent -f

Within a minute or two, your host should appear on the Hosts page.

Permissions

The agent runs with minimal Linux capabilities (CAP_DAC_READ_SEARCH and CAP_SYS_PTRACE) — only what it needs to read /proc for process metrics. It holds no secrets in code: the API key comes from the environment or config file.

Next