Install the LinkMesh agent (optional)

linkmesh-agent is the optional edge connector. You run it beside a collector to let LinkMesh discover what’s worth collecting on a host or in a cluster and feed it into the onboarding wizard. Where you don’t already have a collector, it can also install the upstream collector binary for you, and it offers on-host diagnostics to inspect and validate what’s running. It is not a collector and not required — a collector enrols, runs, and fetches its own config from the server without it. See The agent for what it does and when it earns its place, and Enrol a collector for the agentless path.

Install the collector separately

The agent does not bundle or replace a collector. You install an upstream collector (Grafana Alloy or otelcol-contrib) on its own — the agent only adds discovery-assisted onboarding alongside it.

Before you start

• A running LinkMesh server reachable from the host over HTTPS — have its base URL handy, e.g. https://linkmesh.example.com. That same address should be set on the server as externalUrl (Quickstart step 2) — it is what the server hands collectors for self-telemetry, so leaving it unset makes the dashboard read zero for the whole fleet.
• An enrollment token (single-use for one host, or reusable for a fleet). In the LinkMesh UI open Collectors → + Add Collector and copy the token (see Enrollment tokens). The server derives the host’s identity from the token on first connect; the token then persists in the agent config as the host’s durable reconnect credential.

Install

Linux (DEB/RPM)

Download the package for your architecture from your LinkMesh distribution channel, then install it:

# Debian / Ubuntu
sudo dpkg -i linkmesh-agent_<version>_amd64.deb

# RHEL / Fedora / Amazon Linux
sudo rpm -i linkmesh-agent_<version>_amd64.rpm

The package installs:

Path	What
/usr/local/bin/linkmesh-agent	the agent binary
/etc/linkmesh/config.yaml	the config file
/etc/systemd/system/linkmesh-agent.service	the systemd unit (Restart=always)

The post-install step enables the service but does not start it — you configure the token first (next section), then start it.

Windows

Place linkmesh-agent.exe on the host, write your config (next section), then register it as a Windows service:

linkmesh-agent.exe service install
# remove later with:  linkmesh-agent.exe service uninstall

macOS

Download the linkmesh-agent binary for your architecture (darwin-amd64 / darwin-arm64), put it on your PATH, and run it with a config file (next section). There is no package installer on macOS.

Kubernetes

Run the agent as a DaemonSet (one pod per node) so it can discover cluster workloads. Use the opensight/linkmesh-agent image, supply server.url and the enrollment token (via a Secret → the LINKMESH_SERVER_TOKEN env var), and mount the config from a ConfigMap. The pod runs non-root and needs only a read-only ClusterRole (list pods/namespaces) for discovery.

For the collector substrate itself on Kubernetes, see Deploy a collector fleet on Kubernetes.

Configure and enrol

The agent connects to the server over WebSocket at wss://<your-server>/v1/agent using the enrollment token as a Bearer credential. A minimal /etc/linkmesh/config.yaml:

server:
  url: https://linkmesh.example.com   # your LinkMesh server base URL
  token: <enrollment-token>           # from Collectors → + Add Collector

You can override either value from the environment — handy for containers:

export LINKMESH_SERVER_URL=https://linkmesh.example.com
export LINKMESH_SERVER_TOKEN=<enrollment-token>

Servers behind an internal CA

If your server’s certificate is issued by a private CA, point the agent at the CA bundle with certificates.caCertPath. Only disable verification (certificates.insecureSkipVerify: true) in a lab — never in production.

Start and verify

1. Start the agent (Linux):

   sudo systemctl enable --now linkmesh-agent

2. Check it connected:

   linkmesh-agent status

3. If it can’t reach the server, probe connectivity:

   linkmesh-agent preflight

   See Firewall & connectivity for the ports and hosts the agent and collector need.

Once connected, the host appears in the LinkMesh UI and the onboarding wizard can use the agent’s discovery results.

Optional: install a collector with the agent

If you don’t already have a collector on the host, the agent can install the upstream Grafana Alloy collector binary for you via the system package manager (apt/yum) or MSI on Windows:

linkmesh-agent install alloy            # latest pinned version
linkmesh-agent install alloy --version=<x.y.z>
linkmesh-agent install alloy --mirror=https://your-mirror.example.com/grafana   # air-gapped

This installs the upstream Alloy package — the agent does not bundle a collector. Remove it again with linkmesh-agent uninstall alloy.

Command reference

Command	Purpose
linkmesh-agent status	show agent status, connection state, and collector health (queries the running agent)
linkmesh-agent preflight	check that the agent can reach the LinkMesh server (and optional endpoints)
linkmesh-agent discover	scan the host for log sources and print suggested receiver configs
linkmesh-agent detect	detect running services and print recommended pipeline templates
linkmesh-agent containers	discover running containers and print recommended log receivers
linkmesh-agent config show	display the collector’s on-host config (read-only diagnostic)
linkmesh-agent validate-config	validate the collector’s on-host config with the detected collector’s own validator (read-only diagnostic)
linkmesh-agent install alloy / uninstall alloy	install/remove Grafana Alloy via the host’s native package manager
linkmesh-agent service install / uninstall	register/remove the Windows service (Windows only)
linkmesh-agent version	print the agent version

See also

The agent What the agent does, and when you need it versus running the collector alone.

Enrol a collector The agentless path — enrol Alloy or otelcol-contrib directly.

Onboard your first log End-to-end: install, discover, and onboard a log source.

Enrollment tokens How tokens identify and authenticate a host.