Install the agent on a Linux host

This tutorial takes you from nothing to your first telemetry flowing into AtherOps on a single Linux host. It takes about five minutes and assumes no prior AtherOps knowledge. Follow every step in order.

By the end you will have:

the atherops-otel-agent running under systemd,
the host registered and showing online in AtherOps,
host metrics, logs, and (optionally) traces flowing to the platform.

The agent is installed from releases.atherops.com (Cloudflare R2). Current version: 0.1.2.

Before you start

You need:

A Linux host (amd64 or arm64) where you have root / sudo.
Outbound HTTPS (port 443) from the host to AtherOps.
These commands installed on the host: curl, sha256sum, tar, and jq. Most distros have them; minimal images (Alpine, Amazon Linux minimal) often lack jq; install it first. The installer checks for them and stops with a clear message if one is missing.

Step 1: Generate an install token

The installer authenticates the host using a one-time install token.

In the AtherOps web app, go to Settings → Hosts → Install Token.
Click to generate a token. AtherOps shows you the full install command with the token already filled in.

Each token registers exactly one host. Generate a fresh token per host. If a token is expired or already used, registration fails with HTTP 401 (you will see how to recover below).

Step 2: Run the one-liner

Copy the command from the Hosts page. It looks like this:

curl -sSL https://releases.atherops.com/otel-agent/install.sh | sudo INSTALL_TOKEN=<token> bash

Replace <token> with your token (the Hosts page does this for you).

:::danger Common mistake: put INSTALL_TOKEN= after sudo, not before This is the #1 first-run failure. sudo drops environment variables before it runs the script, so the token must be set on the sudo command itself.

Correct (token after sudo):

curl -sSL https://releases.atherops.com/otel-agent/install.sh | sudo INSTALL_TOKEN=<token> bash

Wrong (token before sudo; the script never sees it, registration fails):

# ~~INSTALL_TOKEN=<token> sudo ...~~  ← sudo strips INSTALL_TOKEN, install fails
curl -sSL https://releases.atherops.com/otel-agent/install.sh | INSTALL_TOKEN=<token> sudo bash

Copy the command from the Hosts page exactly; it already uses the correct form. :::

Step 3: Watch the install

Every line is prefixed with [atherops] so it is easy to grep in CI logs. A successful run looks like this:

[atherops] Detecting platform…             os=linux arch=amd64
[atherops] Fetching version manifest…      https://releases.atherops.com/otel-agent/manifest.json
[atherops] Target versions               agent=0.1.2  otelcol=0.102.0
[atherops] Downloading otelcol-contrib…   0.102.0/linux_amd64  (this may take a moment)
[atherops] Verifying sha256…
[atherops] OK  sha256 matches             otelcol-contrib-linux_amd64
[atherops] Installing agent binary…       /usr/local/bin/atherops-otel-agent
[atherops] OK  Installed atherops-otel-agent          /usr/local/bin/atherops-otel-agent
[atherops] Writing default config…        /etc/atherops/config.yaml
[atherops] Installing systemd unit…       /etc/systemd/system/atherops-otel-agent.service
[atherops] Registering with platform…     https://api.atherops.com
[atherops] OK  Registered                 host_id=h_7f3a2b  hostname=prod-web-01
[atherops] Starting service…
[atherops] OK  atherops-otel-agent started (systemd)

  AtherOps OTel Agent installed successfully.
  Agent version : 0.1.2
  Collector      : otelcol-contrib 0.102.0

  Check status : systemctl status atherops-otel-agent
  View logs    : journalctl -u atherops-otel-agent -f
  Config file  : /etc/atherops/config.yaml

The exact version numbers depend on the current manifest. The important thing is the OK sha256 matches line: the collector binary was checksum-verified before it was installed or run. If that check fails, the installer aborts and nothing is installed; see Troubleshooting.

Step 4: Verify the service is running

Check the systemd unit:

systemctl status atherops-otel-agent

You want to see Active: active (running).

Tail the agent's logs:

journalctl -u atherops-otel-agent -f

Within a few seconds you should see lines like these (logfmt):

level=info msg="agent started" agent_version=0.1.2 host_id=h_7f3a2b
level=info msg="collector started" collector_version=0.102.0 pid=3821
level=info msg="registration complete" host_id=h_7f3a2b

Confirm both version numbers from the command line:

atherops-otel-agent --version

atherops-otel-agent 0.1.2
otelcol-contrib     0.102.0

Both lines must show a real version. (If the second line says unknown, the collector binary has not been resolved yet. See Troubleshooting.)

Step 5: Confirm the host appears in AtherOps

Open the Hosts page in the AtherOps web app.
Find your host's card. It shows an Agent version row and a Collector version row, and a green dot with online once the first heartbeat lands (within ~30 seconds).

Your host is now sending metrics and logs to AtherOps. Host metrics appear in your metrics views; journald and /var/log/syslog logs flow to the logs store.

Host metrics and logs flow automatically. Traces require your applications to send OTLP spans to the agent. See Enable traces.

See your data

The agent is now collecting. Here is where each signal goes and how to extend or confirm it:

Metrics: host CPU, memory, disk, filesystem, network, and load flow automatically to your metrics views. Adjust how often they're collected in Change the scrape interval.
Logs: the systemd journal and /var/log/syslog flow automatically. Add your own application log files (or disable journald on non-systemd hosts) in Configure log sources.
Traces: opt-in. Point your apps at the agent and positively confirm spans reached AtherOps by following Enable traces.

Every signal is isolated per tenant (see Multi-tenant isolation). The collection path is explained in how the agent works.

Self-hosting: point the agent at your platform

If you run your own AtherOps platform, tell the installer where to reach it. Pass PLATFORM_URL (for the install script) and write the same address into /etc/atherops/config.yaml afterward:

curl -sSL https://releases.atherops.com/otel-agent/install.sh | \
  sudo INSTALL_TOKEN=<token> PLATFORM_URL=https://atherops.your-domain.com bash

The installer registers against that URL and writes it into the config. The running agent reads platform.url from /etc/atherops/config.yaml and also respects the ATHEROPS_PLATFORM_URL environment variable (set in /etc/atherops/env).

How the data flows

After install, this is what happens on every collection cycle:

The raw HMAC key never leaves the host. The platform derives your org_id from the key on every ingest request, so your data is always scoped to your account.

What got installed

Path	What it is
`/usr/local/bin/atherops-otel-agent`	the agent (wrapper) binary
`/etc/atherops/config.yaml`	your editable config
`/etc/atherops/credentials.json`	host key + id (mode `0600`, do not edit)
`/etc/atherops/env`	env vars for the systemd unit (mode `0600`)
`/var/lib/atherops/otelcol/<version>/otelcol-contrib`	the collector binary
`/var/lib/atherops/buffer/`	persistent send queue (survives backend outages)
`/etc/systemd/system/atherops-otel-agent.service`	the systemd unit

Full details are in Files & ports.

Next steps

Configure log sources (add files, disable journald)
Enable traces
Change the scrape interval
Understand how the agent works

Before you start​

Step 1: Generate an install token​

Step 2: Run the one-liner​

Step 3: Watch the install​

Step 4: Verify the service is running​

Step 5: Confirm the host appears in AtherOps​

See your data​

Self-hosting: point the agent at your platform​

How the data flows​

What got installed​

Next steps​