The agent — optional edge connector for onboarding

linkmesh-agent is an optional helper you can run alongside a collector. It has three jobs:

Onboarding — discover what’s worth collecting on a host (running services, log sources) or in a cluster (pods, namespaces, workloads) and feed that into the onboarding wizard, so you configure the collector from what’s really there instead of from a blank page.
Optional collector install — where you don’t already have a collector on the host, the agent can install the upstream collector binary for you (linkmesh-agent install alloy) as a convenience.
Local diagnostics — on-host commands to inspect and validate what’s running: config show, validate-config, status, and preflight.

It is not a collector and produces no telemetry of its own — your logs, metrics, and traces always flow through the collector directly to your destinations, never through the agent. It is also never required: a collector runs, enrols, and fetches its own config over native remote config with no agent at all.

When you want the agent — and when you don’t

Scenario	Run the agent?
Onboarding a host with lots of services/log files and you want LinkMesh to find them for you	Yes. The agent inventories services and log sources and pre-fills the onboarding wizard.
Kubernetes cluster where you want to discover pods, namespaces, and workloads to decide what to collect	Yes (as a DaemonSet).
You don’t yet have a collector on the host and want a one-command install	Yes (optional). `linkmesh-agent install alloy` installs the upstream collector for you.
Your collector self-manages its config (Alloy via `remotecfg`, otelcol-contrib via OpAMP) and you don’t need discovery	Optional. These collectors pull config straight from the server — run agentless unless you want discovery or on-host diagnostics.
Tightly locked-down host where you don’t want an extra component	No. Run the collector alone — it enrols and pulls its own config without the agent.

The shorthand: the agent earns its place when discovery saves you work at onboarding time, when you want a one-command collector install, or when you want on-host diagnostics. A self-managing collector needs no agent to keep running.

What the agent does

Service discovery (VMs). Inventories the services running on a host (databases, web servers, message brokers, …) so the onboarding wizard can suggest matching receivers and pipelines.
Log-source discovery (VMs). Finds the log files and journald units worth collecting and surfaces them as candidate sources.
Workload discovery (Kubernetes). As a DaemonSet, lists pods, namespaces, and workloads so you can pick what to onboard without hand-writing selectors.
Feeds the onboarding wizard. Everything it discovers flows into the wizard, where you approve what becomes a real source. You stay in control of what’s actually collected.
Installs a collector on request (optional). linkmesh-agent install alloy fetches and installs the upstream collector package via the host’s native package manager. This is a convenience installer — the agent does not bundle a collector and does not manage it afterwards.
Local diagnostics. Read-only, on-host commands — status, preflight, config show, and validate-config — to check the agent’s connection and inspect or validate the collector’s on-host config.
Reports host context. A lightweight heartbeat carries hostname, OS, and agent version so the fleet UI can show where the agent is running.

How config reaches the collector

The agent is not in the config path. Collectors fetch their own config directly from the LinkMesh server:

Grafana Alloy pulls its config over remotecfg (a Connect-RPC poll, authenticated with a bearer_token).
otelcol-contrib receives its config over OpAMP (a WSS push at /v1/opamp, authenticated with a Bearer token).

See Native remote config for how both paths work. Telemetry itself never flows through the agent either — your logs, metrics, and traces go from the collector straight to your destinations.

What the agent does NOT do

The agent is intentionally not:

A collector. It receives, processes, and exports no telemetry. The collector (Alloy or otelcol-contrib) is the only telemetry runtime, and the agent never bundles one — you install the collector separately (or let the agent install the upstream package for you).
A telemetry path. Your logs/metrics/traces never pass through the agent — they flow collector → destination. If the agent isn’t running, telemetry is unaffected.
The config-delivery mechanism. Collectors fetch their own config from the server (Alloy via remotecfg, otelcol-contrib via OpAMP). The agent neither pushes nor writes the collector’s config.
A collector supervisor. It does not start, stop, restart, or upgrade the collector as a managed service.
Required. A collector runs fine with no agent at all. The agent adds discovery, an optional install, and diagnostics where you want them.

How it composes

The agent runs beside a collector — on a VM as a second process, on Kubernetes as its own DaemonSet — and talks only to the LinkMesh server:

┌────────────────────────────────────────────────────────────────┐
│  Host / cluster                                                  │
│                                                                  │
│   ┌────────────────────┐                 ┌─────────────────────┐  │
│   │ linkmesh-agent     │                 │ Collector (Alloy /  │  │
│   │ (optional)         │                 │ otelcol-contrib)    │  │
│   │ discovery +        │                 │ — telemetry runtime │  │
│   │ diagnostics        │                 └──────────┬──────────┘  │
│   └─────────┬──────────┘                            │ telemetry   │
│             │ discovery + host context              │ out         │
└─────────────┼────────────────────────────┬──────────┼────────────┘
              │                             │ config    │
              ▼                             │ (pull/    ▼
       ┌──────────────┐◀───────────────────┘ push)  ┌──────────────────────┐
       │ LinkMesh     │                             │ Your telemetry       │
       │ server       │                             │ destinations         │
       └──────────────┘                             └──────────────────────┘

The agent sends only discovery + host context to the server. The collector
fetches its own config directly from the server (Alloy pulls via remotecfg,
otelcol-contrib receives an OpAMP push) — the agent is never in the config
path.