Quickstart

This guide takes you from zero to live telemetry on a single Linux host in about 10 minutes. By the end, you’ll have the LinkMesh server running, one enrolled collector reporting in, an active source, and a route forwarding events to the destination of your choice.

What you're aiming at: the dashboard with at least one collector online, an active route, and live throughput.

Prerequisites

• One Linux host with sudo (Ubuntu 22.04 LTS or RHEL 9 verified — others should work)
• 1 vCPU, 1 GB RAM, 5 GB disk is plenty for the server itself
• Outbound HTTPS access to artifacts.saas.opensight.ch (for the install package)
• Open port 8080 on the host so you can reach the web UI from your browser
• Optional: a Grafana Cloud Loki endpoint + write token if you want to verify end-to-end delivery

1. Install the LinkMesh server

Install runs in one shell session. The package ships a systemd unit, an internal TLS CA, a default admin account, and a gitops-backed config store. The server keeps its state in an embedded database by default, so a single-host install needs no external database.

Note

That embedded database backs a single server instance. Running multiple instances for high availability uses an external MongoDB database instead — see Storage backends and Run a highly-available deployment.

Debian / Ubuntu

curl -fsSL https://artifacts.saas.opensight.ch/binaries/linkmesh-server/latest/linkmesh-server_latest_amd64.deb -o linkmesh-server.deb
sudo apt install ./linkmesh-server.deb
sudo journalctl -u linkmesh-server | grep "INITIAL ADMIN PASSWORD"

RHEL / Rocky / Alma

curl -fsSL https://artifacts.saas.opensight.ch/binaries/linkmesh-server/latest/linkmesh-server-latest.x86_64.rpm -o linkmesh-server.rpm
sudo dnf install ./linkmesh-server.rpm
sudo journalctl -u linkmesh-server | grep "INITIAL ADMIN PASSWORD"

Docker

docker run -d --name linkmesh-server \
  -p 8080:8080 -p 50051:50051 \
  -v linkmesh-data:/data/linkmesh-config \
  -v linkmesh-grpc:/etc/linkmesh-grpc \
  docker.io/opensight/linkmesh-server:latest
docker logs linkmesh-server 2>&1 | grep "INITIAL ADMIN PASSWORD"

The container persists its gitops config and gRPC server cert across restarts via the two named volumes. Use -p 8080:8080 for the web UI and -p 50051:50051 for the mTLS gRPC endpoint that agents connect to.

The last command prints a JSON line containing the one-time admin password — keep that handy for the next step.

Tip

Want auto-updates from apt upgrade / dnf update? Use the OpenSight package repository instead of the one-shot install. See linkmesh.io/install for repository setup.

Collectors connecting from another host?

Install auto-generates the server’s gRPC certificate covering only its local hostname and network-interface IPs. If your collectors will reach the server at an address that isn’t on the server’s own interfaces — a cloud public/NAT IP, a load-balancer address, or a DNS name — add that address to the certificate now, before enrolling:

sudo systemctl stop linkmesh-server
sudo runuser -u linkmesh -- linkmesh-server cert init --san dns:linkmesh.example.com
# for a bare IP instead:  --san ip:203.0.113.10
sudo systemctl start linkmesh-server

Cloud VMs hit this routinely: the external IP is a 1:1 NAT the VM never sees on its own interface, so auto-detection can’t include it — the agent then fails with x509: certificate is valid for …, not <your-ip>. Run linkmesh-server cert show to see the current SANs. Terminating TLS at a reverse proxy instead? See Run behind a reverse proxy. You can skip this entirely if collectors reach the server on the same host or a flat/VPC network.

2. Sign in

Open http://<your-host>:8080 in a browser. Sign in as admin with the one-time password from the install logs — you’ll be prompted to set a new password on first login.

3. Enroll your first collector

Open Collectors in the sidebar. The list starts empty.

Collectors page. The + Add Collector button at the top right opens the enrollment wizard.

Click + Add Collector and pick a collector runtime — Grafana Alloy (config via remotecfg) or otelcol-contrib + OpAMP (config pushed via OpAMP). This walkthrough uses Alloy. The wizard creates an enrollment token and shows the install commands to run on the host you want to monitor. Copy them, SSH into the target host, and run them as root.

You install upstream Grafana Alloy from its OS package, then drop in a small bootstrap config — a remotecfg block pointing at your server plus a per-collector Bearer token from the wizard. On its first poll, Alloy enrols and fetches its real pipeline config from the server directly; within ~10 seconds the collector appears in the dashboard’s fleet table. See Add a collector for the full per-runtime templates and the otelcol-contrib + OpAMP alternative.

Note

The collector is the only thing required on the host. linkmesh-agent is a separate, optional onboarding helper that discovers services and log sources to pre-fill the wizard — it never installs, supervises, or configures the collector, and isn’t needed for this quickstart. See The agent.

4. Activate a source

Click into your new collector. Switch to the Inputs tab.

The Inputs tab on a collector shows every receiver activated on it. + Add Input opens the source library.

Click + Add Input to open the source library. Pick a receiver type that matches what you want to ingest — syslog, OTLP, file tail, journald, Kafka, or anything else in the library.

The source library lists every receiver type LinkMesh supports. Filter by signal (logs, metrics, traces) or search by name.

Pick Syslog for this walkthrough — it accepts UDP traffic on port 5514 with no further configuration. The activation is saved as soon as you confirm, and the collector picks up the new config on its next heartbeat (typically within a few seconds).

5. Add a destination

Switch to the Destinations tab on the collector detail page, or open the Destinations library in the sidebar. Click + New Destination and pick an exporter type. Common choices:

• Debug — logs records to the collector’s own stdout. Zero credentials. Useful for the first end-to-end verification.
• Grafana Cloud Loki — push logs to a Loki tenant. Needs an endpoint and a write token (free tier works).
• OTLP — send to any OpenTelemetry-compatible backend.

The destination library. Each entry shows the exporter type, signal coverage, and which collectors have it active.

For this walkthrough, Debug is the fastest path to “I can see events flowing.” Save the destination, then return to the collector detail page.

6. Wire a route

Switch to the Routing tab. A route is the matcher that ties a source to a destination through an optional processing pipeline.

The Routing tab lists every route on this collector. + Create new Route opens an inline editor for source, pipeline, and destinations.

Click + Create new Route. Pick the syslog source as input, leave the pipeline empty (no transformation), pick the Debug destination as output. Save.

The collector picks up the change within a few seconds. Generate test traffic from any host that can reach the collector on port 5514:

logger -d -n <collector-host> -P 5514 "hello from quickstart"

7. See it work

Back on the dashboard, the Throughput card ticks within ~30 seconds.

The dashboard's Throughput card. The collector is processing the syslog records and forwarding them to the Debug destination.

The Fleet Status table shows your collector with current status, type, and last-seen timestamp — refreshed live as heartbeats land.

The Fleet Status table on the dashboard. Each row is one collector. Click into a row to see its detail page.

If you wired a real backend (Loki, ClickHouse, OTLP), check your downstream tool to confirm records are arriving. The Debug destination just logs to the collector’s journal — sudo journalctl -u alloy on the collector host shows the records as they flow through.

What’s next

• Install on Kubernetes — if your collector hosts live in a K8s cluster, use the DaemonSet flow instead of the VM install above
• Concepts — what each entity (Collector, Source, Pipeline, Route, Destination) actually means and how they relate
• Drop noisy logs — strip health-check noise before it reaches your destination
• Mask PII — redact email addresses, phone numbers, and card patterns with one processor step
• Route to Grafana Cloud Loki — wire the destination you most likely already have running

If something didn’t work, open the Events feed on the dashboard — every config push, heartbeat, and error is logged there with context.