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.

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

The signed APT / YUM repository is the path that keeps the agent updated with the rest of the host — copy-paste commands, architectures, and the signing-key fingerprint are on Install from APT or YUM. sudo apt install linkmesh-agent or sudo dnf install linkmesh-agent from that repository is enough.

For a one-shot package, download the file that matches this host’s architecture (amd64/arm64 on Debian, x86_64/aarch64 on RPM) from your LinkMesh distribution channel, then install it:

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

# RHEL / Fedora / Amazon Linux
sudo rpm -i linkmesh-agent_<version>_x86_64.rpm   # or _aarch64.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.

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

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.

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>

Start and verify

Start the agent (Linux):

sudo systemctl enable --now linkmesh-agent

Check it connected:
```
linkmesh-agent status
```
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