Quickstart

Installs in three steps: binary, config, systemd unit. Takes about five minutes on a host that already has outbound HTTPS.

1. Download the agent

Static binary, no dependencies. Pick the architecture that matches the host:

curl -fsSL https://qooqes.online/dl/telemetry-agent-linux-amd64 \
  -o /usr/local/bin/telemetry-agent
chmod +x /usr/local/bin/telemetry-agent
telemetry-agent -version

2. Write the config

One YAML file. token is issued when a host is registered; treat it like a password and keep it out of version control.

# /etc/telemetry-agent/agent.yml
api:
  endpoint: https://qooqes.online/api/v1
  token: ${AGENT_TOKEN}

host:
  id: web-03
  tags: [prod, eu-west]

collect:
  interval: 30s
  metrics: [cpu, memory, disk, network]

interval below 15s is rejected by the ingest endpoint — see API reference for the full validation rules.

3. Install the systemd unit

# /etc/systemd/system/telemetry-agent.service
[Unit]
Description=Telemetry agent
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/telemetry-agent -config /etc/telemetry-agent/agent.yml
EnvironmentFile=/etc/telemetry-agent/agent.env
Restart=on-failure
RestartSec=5
User=telemetry
Group=telemetry
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

echo "AGENT_TOKEN=<your token>" > /etc/telemetry-agent/agent.env
chmod 600 /etc/telemetry-agent/agent.env
systemctl daemon-reload
systemctl enable --now telemetry-agent

4. Confirm it checked in

curl -H "Authorization: Bearer $AGENT_TOKEN" \
  https://qooqes.online/api/v1/hosts

{
  "hosts": [
    { "id": "web-03", "tags": ["prod", "eu-west"], "last_seen": "2026-07-30T12:00:04Z", "status": "up" }
  ],
  "count": 1
}

last_seen updates on every accepted ingest batch. If the host doesn't show up within a minute, check journalctl -u telemetry-agent for a 401 (bad token) or a connection timeout (outbound 443 blocked).

Common errors

Symptom	Likely cause
`401` in the logs	Token typo, or `agent.env` not readable by the `telemetry` user (check the file's owner and mode).
Connection timeout, no HTTP response	Outbound 443 blocked by a firewall or egress proxy. Confirm with `curl -v https://qooqes.online/api/v1/hosts` from the same host.
`400` with a clock-skew message	`collected_at` more than 5 minutes off from real time. Check `timedatectl` and that NTP sync is actually running.
Host appears, but no metrics under `/v1/metrics`	Metric name mismatch — query with the exact dotted name from `collect.metrics`, e.g. `cpu.load1`, not `cpu`.

Removing the agent

systemctl disable --now telemetry-agent
rm /usr/local/bin/telemetry-agent
rm -r /etc/telemetry-agent

The host's data is not deleted automatically — it ages out per the retention periods in privacy, or can be removed sooner on request.

Next: full endpoint list in the API reference.