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 — and, where you want it, to supervise the local collector: start/stop/restart/upgrade it, deliver its config when the collector can’t fetch config itself, and health-probe it. It is not a collector and not required — a self-managing collector enrols and runs fine 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.
• A reusable enrollment token. 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.

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 upstream Grafana Alloy 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 connection state
linkmesh-agent preflight	probe reachability to the server and destinations
linkmesh-agent discover	scan the host for log sources
linkmesh-agent detect	detect running services + suggest pipeline templates
linkmesh-agent install alloy / uninstall alloy	install/remove the upstream Alloy collector
linkmesh-agent service install / uninstall	register/remove the Windows service
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.