Install the agent

The LeanSignal Agent is a custom distribution of the OpenTelemetry Collector. Install one per cluster or environment: it receives your telemetry, keeps everything locally at full fidelity for a short window, and forwards only what your dashboards and alerts demand to LeanSignal.

This page gets you running. For configuring, operating, and extending the agent on your platform, see The agent.

1. Get your tenant name and agent key

Every install command below needs exactly two values. Everything else is discovered: at startup the agent asks LeanSignal which region hosts your tenant and derives every endpoint from the name — so there are no URLs to look up.

Value	What it is	Where to get it
Tenant name	The short name you picked when creating your tenant — the <short-name> in <short-name>.leansignal.io	It is in your browser’s address bar while you are signed in to LeanSignal
Agent key	Authenticates this agent to your tenant, on the control stream and all ingest paths	Agents → Add Agent, then reveal and copy it — see below

Create the agent and copy its key

1. In LeanSignal, open Agents → Add Agent and give it a name — for example prod-eu-central or this-host. This is the agent’s label in the app.
2. The new agent appears in the list with its Agent Key column masked.
3. Click the eye icon to reveal the key, then copy it.

Note

Only admins can reveal and copy agent keys — editors and viewers see them masked. Give every agent its own key: a key allows one connection at a time, so a second agent sharing it is rejected until the first disconnects.

Caution

The agent key is a credential. Treat it as a secret — inject it via an environment variable, secret manager, or Kubernetes Secret, and never commit it to source control.

2. Install

Substitute your two values

In every command below, replace:

• YOUR_TENANT → your tenant name from step 1 (for example acme, not the full acme.leansignal.io)
• YOUR_KEY → the agent key you just revealed and copied

--agent-name / -AgentName is yours to choose — it labels this machine’s telemetry with leansignal_agent_name and is independent of the agent’s name in the app.

Linux and macOS

One installer serves both and detects the platform. It sets up the collector plus all three local stores — VictoriaMetrics, Loki, and Tempo — as services and starts them.

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

Host metrics start flowing immediately. Full detail: Linux · macOS.

Windows

From an elevated PowerShell:

$u = "https://raw.githubusercontent.com/LeanSignal/leansignal-agent/main/scripts/install/install.ps1"
Invoke-WebRequest $u -OutFile install.ps1
.\install.ps1 -AgentKey YOUR_KEY -AgentName this-host -Tenant YOUR_TENANT

Full detail: Windows.

Kubernetes

helm upgrade --install leansignal-agent \
  oci://ghcr.io/leansignal/charts/leansignal-agent \
  --namespace leansignal --create-namespace \
  --set leansignal.tenant="YOUR_TENANT" \
  --set leansignal.agentKey.value="YOUR_KEY"

Full detail, including keeping the key in a Secret: Kubernetes.

Docker Compose

A local trial that runs the agent and all three stores as containers — it receives OTLP only and collects no host metrics. See Docker (trial).

3. Verify it connected

In the LeanSignal app, open Agents. Within a few seconds the agent shows Connected, along with its version, when it was last seen, and the timeseries it forwards versus the timeseries available on it.

That ratio is the whole idea in one number. This agent can see 209,747 timeseries in its local store and forwards 21 of them — everything else stays on the host at no central cost until something asks for it. A fresh agent legitimately reads 0/N (0%): nothing is demanded yet. Import an integration or build a dashboard and watch it move.

If it does not connect, check that:

• the agent key and tenant are correct — see Agent configuration for where those values live on each platform;
• the host can reach <tenant>-grpc.<region> on port 443 — the agent dials out only, so no inbound ports need opening (network requirements);
• the health endpoint responds: curl -sf http://127.0.0.1:13133/;
• the agent’s log is clean — each platform guide shows how to read it: Linux · macOS · Windows · Kubernetes.

Still stuck? See Troubleshooting.

Next steps

• The agent — configure it, manage the services, read its logs, and add new data sources.
• Agent configuration — every variable, port, and local-storage window.
• Activate your first demand — nothing is forwarded until something asks for it.

Note

Run one agent per cluster or environment. It applies the current demand set to every signal flowing through it; additional machines run edge agents or lightweight collectors that forward to it — see the Host Metrics integration.

The agent accepts logs and traces on the same OTLP endpoints it accepts metrics on, plus the Loki push API for existing log shippers — see Logs and Traces.