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, RHEL 9, or another systemd-based distribution)
• 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, 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. It serves plain HTTP on port 8080; TLS is terminated by a reverse proxy or ingress in front (covered below).

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

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

Docker

docker run -d --name linkmesh-server \
  -p 8080:8080 \
  -e AUTH_ADMIN_PASSWORD='choose-a-strong-password' \
  -v linkmesh-data:/data \
  docker.io/opensight/linkmesh-server:latest

Set AUTH_ADMIN_PASSWORD on that first run to choose the admin account’s password up front — the container starts with it already in place.

Mount the whole /data directory, not a subpath — all durable state lives under it: the embedded database (/data/linkmesh/state.db), the GitOps config clones (/data/linkmesh-config/), and the auto-generated secrets encryption key (/data/linkmesh/secrets.key). Persisting only a subdirectory loses your destinations, users, and secrets on the next container recreate. Everything is served on the single HTTP port 8080 — the web UI, the REST API, the agent control channel (a WebSocket at /v1/agent), and OTLP ingest. In production, TLS is terminated by your ingress / reverse proxy in front of it.

Secrets encryption key

Destination credentials are stored encrypted; the key is generated on first start and kept in the data volume, so the vault works out of the box. For production, provide your own key with -e LINKMESH_SECRETS_KEY=<32-byte base64/hex> from a secret store outside the volume, and back it up — losing it makes stored secrets unrecoverable. See Destination secrets.

The install starts the server right away and creates an admin account whose random password is deliberately never written to any log. For the package installs above, set your own password with the recovery command — it needs no prior login, and works whether or not the server is running:

sudo linkmesh-server reset-password --email admin --password 'choose-a-strong-password'

Omit --password to have a strong one generated and printed. Resetting a password signs that account out of any sessions it already had. (The Docker install already set AUTH_ADMIN_PASSWORD above, so you can skip this step there.)

Tip

Want auto-updates from apt upgrade / dnf update? Add the signed OpenSight package repository instead of the one-shot install — copy-paste commands, architectures, and the signing-key fingerprint are on Install from APT or YUM.

Collectors connecting from another host?

The server speaks plain HTTP on 8080; for any connection over an untrusted network you terminate TLS at a reverse proxy (nginx, Caddy, or your cloud load balancer / ingress) in front of it. Agents and OpAMP collectors connect over HTTPS/WSS to that front door — there is no separate gRPC port.

The one thing to get right is the proxy’s TLS certificate: it must cover the exact address collectors use — a DNS name (preferred, survives IP changes), a load-balancer address, or a cloud public/NAT IP. If it doesn’t, the agent fails with x509: certificate is valid for …, not <your-address>. Point the agent’s server.url at the same name the certificate covers. See Run behind a reverse proxy for a worked config. You can skip TLS entirely if collectors reach the server on the same host or a trusted flat/VPC network (use http:///ws://).

2. Tell LinkMesh its public URL

Set externalUrl to the address collectors and browsers reach this server on, then restart. This is the one post-install setting you should not skip.

Package install (.deb / .rpm)

Edit /etc/linkmesh/config.yaml:

# A DNS name (preferred — survives IP changes, and matches your TLS cert)
externalUrl: "https://linkmesh.example.com"

# Or a bare IP, for a lab / flat-network install with no TLS in front
externalUrl: "http://192.0.2.10:8080"

Then restart:

sudo systemctl restart linkmesh-server

Docker / Kubernetes

Set it in the environment instead — LINKMESH_EXTERNALURL, or its shorter alias EXTERNAL_URL:

docker run -d --name linkmesh-server \
  -p 8080:8080 \
  -e LINKMESH_EXTERNALURL='https://linkmesh.example.com' \
  -e AUTH_ADMIN_PASSWORD='choose-a-strong-password' \
  -v linkmesh-data:/data \
  docker.io/opensight/linkmesh-server:latest

Use the address collectors resolve — an Ingress hostname or a Service DNS name like http://linkmesh-server.linkmesh.svc.cluster.local:8080, never a pod IP.

Skip this and the dashboard goes blind while the pipeline works fine

externalUrl is the address LinkMesh hands to collectors so they can push their own self-telemetry back. Leave it unset and:

• every OpAMP collector reports throughput 0, CPU 0, memory 0, uptime 0 — permanently, however much data it is really moving;
• user invites and password resets fail with a 500;
• nothing shows an error in the UI. The numbers are just zero.

Your telemetry keeps flowing to its destinations the whole time — the pipeline is fine, only the dashboard is blind. It reads exactly like a broken product, which is why this is step 2 rather than a footnote.

The server also says so on startup. If you see this in journalctl -u linkmesh-server, you skipped it:

WARN externalUrl is not configured — collector self-telemetry is DISABLED.

If you forget, LinkMesh limps rather than dies

From v1.329.2 the server derives a fallback URL from the first authenticated request it serves, so self-telemetry usually starts working once you sign in. Treat that as a safety net, not as configuration: the derived value is held in memory only and is lost on every restart, and it is wrong whenever collectors reach the server under a different name than your browser does.

Invites and password-reset emails are minted against the same fallback, so they work too — but the link inside them outlives the value that built it. After a restart, or if the recipient reaches the server under a different name, a link that was already sent stops working. Set externalUrl explicitly.

3. Sign in

Open http://<your-host>:8080 in a browser. Sign in as admin with the password you set in the previous step.

4. 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.

5. 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).

6. 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.

7. 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"

8. 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.