The agent

The LeanSignal Agent is a custom distribution of the OpenTelemetry Collector that runs inside your network. It receives metrics, logs, and traces, keeps everything locally at full fidelity for a short window, and forwards only what your dashboards and alerts demand to LeanSignal.

It dials out only over a single gRPC stream — LeanSignal never connects in, so no inbound ports need opening. That one stream carries the demand set down, the metric index up, and the queries that let the app read your local stores without exposing them.

Pick your platform

Each guide covers the same ground end to end: install, configure, manage the services, read the logs, and extend the agent with new receivers.

Linux systemd. All three local stores. The reference platform.

macOS launchd. All three local stores, Apple silicon and Intel.

Kubernetes Helm chart. Collector plus the local stores as pods.

Windows Windows services. Local metrics store; logs and traces forward only.

Just trying it out? Docker Compose runs the agent and all three local stores as containers in one command — a trial rather than a deployment, as it receives OTLP only and collects no host metrics.

What runs where

Every platform receives all three signals and forwards demanded telemetry to LeanSignal. What differs is which local stores are installed alongside the agent — and the local store is what powers exploring a signal before you demand it.

	Linux	macOS	Kubernetes	Windows
Service manager	systemd	launchd	Helm / Deployments	Windows services
Receives metrics, logs, traces	✅	✅	✅	✅
Forwards demanded telemetry	✅	✅	✅	✅
Local metrics store (VictoriaMetrics, 1 day)	✅	✅	✅	✅
Local log store (Loki, ~1h)	✅	✅	✅	—
Local trace store (Tempo, ~1h)	✅	✅	✅	—

On Windows, logs and traces are still collected and still reach LeanSignal when demanded — you just cannot browse them locally first, so demand selectors have to be written directly. See Windows.

Common tasks

Configure the connection Tenant, agent key, agent name — plus pinning endpoints and ports.

Add a new data source Drop in an OpenTelemetry receiver and import a ready-made demand.

Troubleshoot Agent not connecting, no data arriving, gaps in a dashboard.

How demand works Why nothing is forwarded until something asks for it.

Two things worth knowing up front

Nothing is forwarded until it is demanded. The agent’s filters are fail-closed: on a fresh install, before any dashboard or alert references your data, zero telemetry leaves the host. That is by design, not a fault — the local stores still receive everything, so nothing is lost while you decide what matters. If you are staring at an empty chart on day one, this is usually why.

The local stores are a short buffer, not storage. VictoriaMetrics keeps one day, Loki and Tempo about an hour. They exist so you can see what the agent is seeing and choose what to keep. Long-term retention happens in LeanSignal, on the demanded subset.

Network requirements

The agent dials out only — LeanSignal never connects in, so no inbound firewall rules are needed for the control plane. Allow these destinations:

When	Destination	Why
Install	raw.githubusercontent.com, api.github.com, github.com	the install script, release lookup, and the agent plus grafana/loki / grafana/tempo downloads
Startup	cc.leansignal.io	one HTTPS call that resolves your tenant’s region — skipped entirely if you pin the region with --domain / LEANSIGNAL_DOMAIN
Runtime	<tenant>-grpc.<region>:443	the gRPC control stream
Runtime	<tenant>-{metrics,logs,traces}-ingest.<region>	one ingest host per signal, for demanded telemetry

Behind a proxy, set HTTPS_PROXY for the agent — on Linux via a systemd drop-in (sudo systemctl edit leansignal-agent). For hosts with no internet access at all, build a bundle on a connected machine and install offline with install.sh --bundle FILE.

Sizing

The collector itself is lightweight; 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 is the resource to watch: budget for one day of metrics plus roughly an hour each of logs and traces, proportional to the total telemetry flowing through the agent.

Modes

Most installs are central agents — the full pipeline described above. A lighter edge mode turns the agent into a plain OTLP forwarder with no local stores, no demand filtering, and no control stream: it collects host metrics and local OTLP and ships them to a central agent, which does the rest. Use it to fan many machines into one aggregation point. Set the central agent’s OTLP endpoint at install (--central-url on hosts, leansignal.centralAgentGrpcUrl in Helm) and the installer selects edge mode for you.

Note

Run one central agent per cluster or environment. It applies the current demand set to everything flowing through it; other machines run edge agents or lightweight collectors that forward to it.