Agent on Linux

Linux is the agent’s reference platform. The installer sets up the collector and all three co-located local stores — VictoriaMetrics (metrics), Loki (logs), and Tempo (traces) — as independent systemd units. amd64 and arm64 are supported.

Install

You need your tenant name and an agent key from the LeanSignal app (Agents → Add Agent). Everything else is derived.

curl -fsSL https://raw.githubusercontent.com/LeanSignal/leansignal-agent/main/scripts/install/install.sh \
  | sudo bash -s -- --agent-key YOUR_KEY --agent-name this-host --tenant YOUR_TENANT

To read the script before running it:

curl -fsSL https://raw.githubusercontent.com/LeanSignal/leansignal-agent/main/scripts/install/install.sh -o install.sh
less install.sh
sudo bash install.sh --agent-key YOUR_KEY --agent-name this-host --tenant YOUR_TENANT

--agent-name labels this host’s telemetry with leansignal_agent_name. Useful extra flags: --no-loki / --no-tempo / --no-vm skip a local store, --central-url HOST:PORT installs in edge mode, and --bundle FILE installs from a downloaded bundle for hosts without internet access.

Host metrics — CPU, memory, disk, filesystem, network — start flowing immediately. Confirm the agent is up:

curl -sf http://127.0.0.1:13133/ && echo " agent healthy"

What gets installed

Path	Contents
/usr/local/bin/{leansignal-agent,victoria-metrics,loki,tempo}	binaries
/etc/leansignal-agent/config.yaml	collector configuration
/etc/leansignal-agent/agent.env	tenant, agent key, agent name (mode 0600)
/etc/leansignal-agent/loki.yaml, tempo.yaml	local store configuration
/var/lib/leansignal-agent/{vm,loki,tempo}	local metrics, logs, and traces data
four systemd units	leansignal-agent, leansignal-victoria-metrics, leansignal-loki, leansignal-tempo

Configure

Edit the file, then restart only that service — the others keep running and no data is lost.

What	File	Restart
Tenant, agent key, agent name	/etc/leansignal-agent/agent.env	sudo systemctl restart leansignal-agent
Collector pipeline (receivers, processors)	/etc/leansignal-agent/config.yaml	sudo systemctl restart leansignal-agent
Local log store	/etc/leansignal-agent/loki.yaml	sudo systemctl restart leansignal-loki
Local trace store	/etc/leansignal-agent/tempo.yaml	sudo systemctl restart leansignal-tempo

To change tenant or rotate the key:

sudo nano /etc/leansignal-agent/agent.env

LEANSIGNAL_TENANT=<your-tenant>
LEANSIGNAL_AGENT_KEY=<your-key>
LEANSIGNAL_AGENT_NAME=this-host

sudo systemctl restart leansignal-agent

Changing tenant is a single value — the agent re-resolves its region and re-derives every endpoint on restart. See Agent configuration for pinning endpoints explicitly and for the full variable reference.

Note

Re-running the installer never overwrites an existing configuration — it writes config.yaml.new beside it, so your edits survive upgrades.

Manage the services

Four independent units. Restarting one does not touch the others, and restarting the agent never interrupts the local stores or their data.

# status
systemctl status leansignal-agent leansignal-victoria-metrics leansignal-loki leansignal-tempo

# restart just the collector — the stores keep running
sudo systemctl restart leansignal-agent

# restart a local store
sudo systemctl restart leansignal-victoria-metrics
sudo systemctl restart leansignal-loki
sudo systemctl restart leansignal-tempo

Investigate logs

Each service logs to journald:

journalctl -u leansignal-agent -f
journalctl -u leansignal-victoria-metrics -f
journalctl -u leansignal-loki -f
journalctl -u leansignal-tempo -f

# errors only, since boot
journalctl -u leansignal-agent -p err -b

What is actually being forwarded? Each demand filter logs its verdict per batch, so the agent’s own log tells you the split between what it received and what it sent:

journalctl -u leansignal-agent | grep 'demand filter' | tail -20

You will see received / allowed / dropped counts. allowed=0 on a fresh agent is normal and correct — nothing is forwarded until a dashboard or alert demands it. The local stores keep receiving everything either way.

Query the local stores directly

Everything below is loopback-only. The agent self-monitors, so its own telemetry is there before you send anything.

# METRICS — what exists locally
curl -s 'http://127.0.0.1:8428/api/v1/label/__name__/values' | head -c 500

# is the control stream up? (1 = connected to LeanSignal)
curl -s --get 'http://127.0.0.1:8428/api/v1/query' \
  --data-urlencode 'query=leansignal_edgecontroller_connection_up'

# LOGS — the agent's own, a reliable smoke test
curl -s --get 'http://127.0.0.1:3100/loki/api/v1/query_range' \
  --data-urlencode 'query={service_name="leansignal-agent"}' --data-urlencode 'limit=5'

# TRACES — recent traces ({} matches everything)
curl -s --get 'http://127.0.0.1:3200/api/search' \
  --data-urlencode 'q={}' --data-urlencode 'limit=5'

Note

The local log window is exactly one hour (max_query_lookback: 1h), so a query over a longer range legitimately returns nothing older. Traces are approximately an hour, and the agent emits very few spans of its own — an empty trace result usually means nothing has sent traces yet, not that the store is broken.

Extend the agent

The agent bundles the full OpenTelemetry Collector Contrib set, so you can add any receiver to /etc/leansignal-agent/config.yaml — scrape a Prometheus endpoint, poll a database, tail a log file — and restart with sudo systemctl restart leansignal-agent.

The integration pages give you a ready-made receiver block and a matching demand you can import in one step, which is the quickest path: the receiver starts collecting, and the imported demand tells the agent which of it to forward.

Caution

Collecting a new source is only half of it. Until something demands the new data it stays on the host — visible in the local store, absent from LeanSignal. Importing the integration’s demand, or building a dashboard on it, is what starts forwarding.

Upgrade and uninstall

# upgrade the agent binary only — local stores and their data are untouched
curl -fsSL https://raw.githubusercontent.com/LeanSignal/leansignal-agent/main/scripts/install/upgrade.sh | sudo bash

# also upgrade VictoriaMetrics (takes a snapshot first, rolls back if unhealthy)
curl -fsSL https://raw.githubusercontent.com/LeanSignal/leansignal-agent/main/scripts/install/upgrade.sh | sudo bash -s -- --with-vm

Loki and Tempo have no --with-* upgrade path; re-run the installer to move them to a newer pinned version.

# uninstall — keeps config and data unless you pass --purge
curl -fsSL https://raw.githubusercontent.com/LeanSignal/leansignal-agent/main/scripts/install/uninstall.sh -o uninstall.sh
sudo bash uninstall.sh
sudo bash uninstall.sh --purge    # also delete config and store data

Sizing and egress

Sizing is dominated by the local stores, which buffer everything your systems emit — not just the demanded subset. A couple of CPU cores and a few GB of RAM cover most environments; disk under /var/lib/leansignal-agent is the resource to watch.

The agent dials out only, to <tenant>-grpc.<region>:443 (control stream) and the three per-signal ingest hosts, plus one startup call to cc.leansignal.io to resolve your region. Behind a proxy, add a systemd drop-in with sudo systemctl edit leansignal-agent:

[Service]
Environment=HTTPS_PROXY=http://proxy:3128

Full detail lives in the Linux install guide in the agent repository.