Agent on macOS

macOS is a full-feature platform: the installer sets up the collector and all three co-located local stores — VictoriaMetrics (metrics), Loki (logs), and Tempo (traces) — as independent launchd daemons. Apple silicon (arm64) and Intel (amd64) are supported.

Note

Local log and trace stores on macOS arrived in agent 0.7.0. Earlier versions installed only VictoriaMetrics, so a Mac had nowhere to keep logs and spans locally. Upgrading an older Mac install means re-running the installer.

Install

You need your tenant name and an agent key from the LeanSignal app (Agents → Add Agent). The same installer serves Linux and macOS and detects the platform.

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

--agent-name labels this host’s telemetry with leansignal_agent_name. Add --no-loki / --no-tempo / --no-vm to skip a local store.

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"

Caution

Release binaries are not notarized, so Gatekeeper may ask for approval the first time. The installer registers everything as root daemons.

What gets installed

Path	Contents
/usr/local/bin/{leansignal-agent,victoria-metrics,loki,tempo}	binaries
/usr/local/etc/leansignal-agent/config.yaml	collector configuration
/usr/local/etc/leansignal-agent/loki.yaml, tempo.yaml	local store configuration
/usr/local/var/leansignal-agent/{vm,loki,tempo}	local metrics, logs, and traces data
/usr/local/var/log/leansignal-agent/	one log file per service
four LaunchDaemons	com.leansignal.agent, com.leansignal.victoria-metrics, com.leansignal.loki, com.leansignal.tempo

Configure

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

What	Where	Restart
Tenant, agent key, agent name	EnvironmentVariables in /Library/LaunchDaemons/com.leansignal.agent.plist	sudo launchctl kickstart -k system/com.leansignal.agent
Collector pipeline (receivers, processors)	/usr/local/etc/leansignal-agent/config.yaml	sudo launchctl kickstart -k system/com.leansignal.agent
Local log store	/usr/local/etc/leansignal-agent/loki.yaml	sudo launchctl kickstart -k system/com.leansignal.loki
Local trace store	/usr/local/etc/leansignal-agent/tempo.yaml	sudo launchctl kickstart -k system/com.leansignal.tempo

Caution

launchd does not read agent.env. Unlike Linux, the connection values live in the agent’s plist, not in an environment file. Editing agent.env on a Mac has no effect.

To change tenant or rotate the key, edit the two values in the plist:

sudo nano /Library/LaunchDaemons/com.leansignal.agent.plist

<key>LEANSIGNAL_TENANT</key>    <string>your-tenant</string>
<key>LEANSIGNAL_AGENT_KEY</key> <string>your-key</string>

sudo launchctl unload /Library/LaunchDaemons/com.leansignal.agent.plist
sudo launchctl load -w /Library/LaunchDaemons/com.leansignal.agent.plist

Those are normally the only two values you touch — the agent re-resolves its region and re-derives every endpoint on restart. The plist also carries empty LEANSIGNAL_ENDPOINT and LEANSIGNAL_DATAPLANE_ENDPOINT entries; fill one in only to pin that host. See Agent configuration.

Or simply re-run the installer with --agent-key / --tenant — it rewrites these and keeps your configuration and all local store data.

Manage the services

Four independent daemons. Restarting one does not touch the others.

# status — a numeric PID in the first column means running
sudo launchctl list | grep leansignal

# restart just the collector — the stores keep running
sudo launchctl kickstart -k system/com.leansignal.agent

# restart a local store
sudo launchctl kickstart -k system/com.leansignal.victoria-metrics
sudo launchctl kickstart -k system/com.leansignal.loki
sudo launchctl kickstart -k system/com.leansignal.tempo

# stop / start (unload = stop, load = start)
sudo launchctl unload /Library/LaunchDaemons/com.leansignal.agent.plist
sudo launchctl load   -w /Library/LaunchDaemons/com.leansignal.agent.plist

macOS system daemons live in the system/ domain and need sudo.

Investigate logs

One file per service:

tail -f /usr/local/var/log/leansignal-agent/agent.log
tail -f /usr/local/var/log/leansignal-agent/victoria-metrics.log
tail -f /usr/local/var/log/leansignal-agent/loki.log
tail -f /usr/local/var/log/leansignal-agent/tempo.log

What is actually being forwarded? Each demand filter logs its verdict per batch:

grep 'demand filter' /usr/local/var/log/leansignal-agent/agent.log | 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 http://127.0.0.1:3100/ready
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 http://127.0.0.1:3200/ready
curl -s --get 'http://127.0.0.1:3200/api/search' \
  --data-urlencode 'q={}' --data-urlencode 'limit=5'

Note

The local trace store takes OTLP on 4328, not 4318 — the collector itself owns 4317/4318. Tempo’s /api/search/tags stays empty until its first blocks flush, so an empty tag list shortly after install is expected; search and trace-by-id already work.

Extend the agent

The agent bundles the full OpenTelemetry Collector Contrib set, so you can add any receiver to /usr/local/etc/leansignal-agent/config.yaml and restart with sudo launchctl kickstart -k system/com.leansignal.agent.

The integration pages give you a ready-made receiver block and a matching demand you can import in one step.

Caution

Collecting a new source is only half of it. Until something demands the new data it stays on the Mac — visible in the local store, absent from LeanSignal.

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

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

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