Agent configuration

The LeanSignal Agent is configured through three connection values plus a standard OpenTelemetry Collector configuration file. The installers set all of this up for you — this page is the reference for what each value means.

Looking for the commands?

This page is platform-independent reference. For where each file lives on your platform, how to restart a service after editing it, and how to read its logs, use the platform guide: Linux · macOS · Windows · Kubernetes. The agent overview compares them.

Connection variables

Variable	Required	Description
LEANSIGNAL_TENANT	✅	Your tenant name — the <short-name> in <short-name>.leansignal.io. The agent derives every endpoint from it (see below).
LEANSIGNAL_AGENT_KEY	✅	Authenticates the agent to your tenant — on the control stream and on all three ingest paths. Create it in the LeanSignal app under Agents.
LEANSIGNAL_AGENT_NAME	✅	Labels every metric, log, and trace from this agent with leansignal_agent_name — the label dashboards’ Instance filters commonly use. Independent of the agent record’s name in the LeanSignal app. The installers require it (--agent-name); Docker Compose defaults it to docker-agent.

How endpoints are derived. At startup the agent makes one HTTPS call to the LeanSignal control center (cc.leansignal.io) to look up which region hosts your tenant, then derives everything from the tenant name — the gRPC control host (<tenant>-grpc.<region>:443) and one ingest host per signal: <tenant>-metrics-ingest.<region>, <tenant>-logs-ingest.<region>, and <tenant>-traces-ingest.<region>. There is nothing else to configure, and moving an agent to another tenant means changing LEANSIGNAL_TENANT and restarting.

Pinning endpoints (advanced)

Every derived value can be overridden. Pins are useful for air-gapped DNS, private ingress, or removing the startup dependency on the control center — an agent with everything pinned (or the region pinned via LEANSIGNAL_DOMAIN) never calls it.

Variable	Overrides	Format
LEANSIGNAL_DOMAIN	the region lookup only	region domain, e.g. eu11.leansignal.io — hosts are still derived from the tenant name
LEANSIGNAL_ENDPOINT	gRPC control host	host:port, no scheme
LEANSIGNAL_DATAPLANE_ENDPOINT	metrics ingest	base origin, e.g. https://<tenant>-metrics-ingest.eu11.leansignal.io — the agent appends /api/v1/write
LEANSIGNAL_LOKI_ENDPOINT	logs ingest	base origin — the agent appends /otlp/v1/logs
LEANSIGNAL_TEMPO_ENDPOINT	traces ingest	base origin — the agent appends /v1/traces

The Linux installer takes these as --domain, --endpoint, --dataplane-endpoint, --loki-endpoint, and --tempo-endpoint; the Helm chart as leansignal.domain, leansignal.endpoint, dataplane.endpoint, logs.tenantEndpoint, and traces.tenantEndpoint.

Docker Compose is the exception

The Compose trial predates tenant-name resolution: it requires explicit endpoints, treats LEANSIGNAL_DATAPLANE_ENDPOINT as the full write URL rather than a base origin, and defaults the logs and traces endpoints to its own local stores. See Docker (trial).

Where the values live per install — each guide covers editing and restarting:

Install	Location
Linux	/etc/leansignal-agent/agent.env (mode 0600)
macOS	EnvironmentVariables in /Library/LaunchDaemons/com.leansignal.agent.plist — launchd does not read agent.env
Windows	the Environment registry value on the LeanSignalAgent service
Kubernetes	leansignal.* Helm values; the key from leansignal.agentKey.value or an existing Secret
Docker Compose	environment variables on the agent service

Caution

The agent key is a credential. Inject it via a secret manager, a Kubernetes Secret, or a root-only environment file — never commit it to source control or bake it into an image.

Ports

Port	Direction	Protocol	Purpose
4317	inbound	OTLP/gRPC	metrics, logs, and traces from your workloads
4318	inbound	OTLP/HTTP	metrics, logs, and traces from your workloads
3500 / 3600	inbound	Loki push (HTTP / gRPC)	logs from Promtail/Alloy-style shippers
13133	inbound (loopback)	HTTP	health check — curl -sf http://127.0.0.1:13133/
8428	inbound (loopback)	HTTP	co-located VictoriaMetrics (local metrics store)
3100	inbound (loopback)	HTTP	co-located Loki (local log store, ~1h window)
3200 / 4328	inbound (loopback)	HTTP	co-located Tempo (local trace store, ~1h window): query / OTLP ingest. Host installs use 4328 because the collector owns 4317/4318; in Kubernetes, Tempo runs in its own pod and takes OTLP on 4318
443	outbound	gRPC + HTTPS, TLS	control stream and demanded metrics, logs, and traces to LeanSignal

The agent dials out only — LeanSignal never connects in, so no inbound firewall rules are required for the control plane.

The OTLP receivers bind to 0.0.0.0 (all interfaces) on every install, so workloads on other hosts can forward telemetry to the agent — the gateway topology used by the integrations. They are unauthenticated by design, so keep the agent on a trusted or internal network, or firewall 4317/4318. To accept only local traffic, set the otlp receiver’s endpoint in the collector configuration to 127.0.0.1:4317 / 127.0.0.1:4318 and restart the agent.

Local storage

The agent writes everything it receives to a co-located local store per signal. These buffers are what power discovery and edit-mode previews — the Available source on the Metrics, Logs, and Traces pages. Long-term storage happens in your central dataplane, which receives only the demanded subset.

Signal	Store	Window
Metrics	VictoriaMetrics	1 day, exact (--retentionPeriod=1d)
Logs	Loki	1 hour, exact (max_query_lookback: 1h)
Traces	Tempo	~1 hour, approximate — deletion is compaction-driven, so queries may see a little more

None of these windows is configurable through the agent; change one by editing that store’s own configuration or service definition.

Windows

Windows installs get the local metrics store only. Logs and traces are still received and still forwarded to LeanSignal when demanded, but there is no local log or trace store to explore first. See Windows.

See Architecture.

Collector configuration

The agent is an OpenTelemetry Collector distribution, so its pipeline is a regular collector configuration file. The shipped configuration receives OTLP and host metrics, indexes every timeseries, applies the demand filter, and exports to both the local store and the dataplane.

You can extend it with any receiver from the OpenTelemetry Collector Contrib set — the distribution bundles it in full, including the prometheus, mysql, and postgresql receivers used by the integrations. Each integration page shows a ready-made receiver configuration.

Where the file lives and how to reload it after editing: Linux · macOS · Windows · Kubernetes (Helm values, not a file).

Editing the configuration from the app

You don’t have to SSH in to change a collector configuration. Admins can read and edit the file the agent is actually running from the LeanSignal app — Agents, open the agent, Configuration tab — or with leanctl agent config get|apply. Both reach the file on the agent host over the agent’s own control stream, so they work wherever the agent does; the agent must be Connected.

The agent validates every write before applying it — a YAML parse plus a full collector dry-run of the merged configuration. A rejected write changes nothing on the host and comes back with the validator’s own message. An accepted one keeps the previous contents as <path>.bak, writes atomically, and then restarts the agent to apply — expect a few seconds of downtime on the OTLP receivers. The service manager brings it back automatically: systemd and launchd installs restart on exit, the Windows service does too, and the shipped Docker Compose file carries restart: unless-stopped — keep that policy if you run the container your own way.

A configuration mounted read-only — typically a Kubernetes ConfigMap — is shown read-only in the app: a write to it could not stick (GitOps would revert it on the next sync). Change those through their Helm values or ConfigMap instead.

Caution

Adding a receiver only starts collecting. Until a dashboard or alert demands the new data it stays on the host — visible in the local store, absent from LeanSignal. Importing the integration’s demand is what starts forwarding.

Pointing workloads at the agent

Configure your application’s OpenTelemetry SDK (or a local collector) to export OTLP to the agent:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://<agent-host>:4317"   # gRPC, or :4318 for HTTP
export OTEL_SERVICE_NAME="my-service"

App in Docker?

Inside a container, localhost is the container itself — not the host the agent runs on. If the agent runs on the host, point the app at http://host.docker.internal:4317; on Linux, also add extra_hosts: ["host.docker.internal:host-gateway"] to the app’s compose service (or use the docker0 bridge IP, typically 172.17.0.1). If the agent runs in the same Compose project, join the app to the agent’s network and use the service name instead — http://agent:4317.

The integration pages cover per-language setup, including the instrumentation packages and the metric names each runtime emits.