Lynx Quick Start

Monitora i tuoi server in 5 minuti. Lynx impara cosa è "normale" e ti avvisa quando qualcosa cambia.

Cos'è Lynx?

Lynx è un agent di monitoraggio leggero che gira sui tuoi server e impara il loro comportamento normale usando l'AI. Invece di impostare soglie manuali, Lynx costruisce una baseline durante una fase di apprendimento e poi rileva anomalie automaticamente.

Lynx raccoglie 12 metriche di sistema (CPU, memoria, disco, rete, processi, connessioni) ogni pochi secondi e le analizza con una rete neurale addestrata sul comportamento specifico del tuo server.

Lynx funziona offline e on-device. I tuoi dati non lasciano mai il server — solo gli score di anomalia vengono inviati alla dashboard.

Come funziona

Apprendimento — Per i primi 5 minuti, Lynx raccoglie metriche e addestra un modello del comportamento normale.
Monitoraggio — Dopo l'apprendimento, ogni nuovo dato viene confrontato con la baseline. Le deviazioni producono un anomaly score (0–10).
Rilevamento drift — Lynx traccia anche se la distribuzione complessiva delle metriche sta cambiando nel tempo (drift score 0–100%).
Alerting — Quando l'anomaly score supera la tua soglia, Lynx genera un alert nella dashboard e (opzionalmente) invia un'email.

Installazione

Piattaforme supportate: Installazione nativa su Linux (Ubuntu, Debian, RHEL, CentOS, Rocky, AlmaLinux — x86_64 e aarch64). Su macOS l'installer passa automaticamente a un container Docker — vedi la sezione macOS qui sotto. Windows non è supportato come install nativo; usa WSL2 (che è Linux) o Docker Desktop.

Step 1: Genera il token API

Vai nella dashboard Lynx e clicca "Genera Token API". Copia il token — verrà mostrato solo una volta.

Step 2: Installa l'agent

Esegui l'installer sul tuo server:

# Installer one-line (Linux / macOS)
curl -sL https://luviner.com/install-lynx.sh | bash

Step 3: Avvia il monitoraggio

Avvia l'agent con l'URL della dashboard e il token:

lynx-agent --token YOUR_API_TOKEN

Fatto! Il tuo nodo apparirà nella dashboard in pochi secondi. Imparerà per 5 minuti, poi inizierà a monitorare.

Installazione su macOS (fallback Docker)

L'installazione nativa su macOS non è supportata perché Lynx ships binari Cython compilati che richiederebbero un wheel separato per ogni versione minor di Python × ogni major di macOS. L'installer rileva macOS e usa l'immagine Docker ufficiale (luviner/lynx). Prerequisito: Docker Desktop installato e in esecuzione. Stesso one-liner di Linux:

# Lancia l'installer (rileverà macOS e userà Docker)
curl -sL https://luviner.com/install-lynx.sh | bash

# Guarda i log dell'agent
docker logs -f luviner-lynx

Cosa viene monitorato su macOS: In modalità Docker, l'agent Lynx monitora i container Docker in esecuzione sul tuo Mac (CPU, RAM, rete, anomaly detection per container) — NON monitora il Mac host stesso. Per monitorare un server di produzione reale, installa Lynx nativamente su una macchina Linux (il percorso standard).

Modalità Docker

Lynx può anche monitorare tutti i tuoi container Docker automaticamente. Scopre i container attivi e traccia CPU, memoria, I/O e rete per ciascuno.

# Monitora il server host
curl -sL https://luviner.com/install-lynx.sh | bash -s -- --docker

# Monitora i container Docker (monta il socket)
docker run -d --name lynx \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e LYNX_API_TOKEN=YOUR_TOKEN \
  luviner/lynx:0.1.0 --docker

Capire gli score

Anomaly Score (0–10)

Misura quanto lo stato attuale del sistema è diverso dalla baseline appresa. Più alto = più anomalo.

Range	Significato	Azione
0.0 – 0.3	Normale	Nessuna azione necessaria
0.3 – 0.7	Elevato	Da tenere d'occhio, potrebbe indicare un problema in sviluppo
0.7 – 1.0	Critico	Investigare immediatamente — qualcosa di insolito sta accadendo

Drift Score (0–100%)

Misura quanto la distribuzione complessiva delle metriche si è spostata dalla baseline. Un drift alto significa che il comportamento del server è cambiato fondamentalmente.

Range	Significato	Azione
0 – 30%	Stabile	La baseline è ancora rappresentativa
30 – 70%	In cambiamento	Il comportamento sta cambiando — considera di riavviare l'agent per ri-apprendere
70 – 100%	Drift significativo	Riavvia l'agent per costruire una nuova baseline

Mesh consensus

Quando hai più agent Lynx su server diversi, possono validarsi a vicenda usando il mesh consensus. Se solo un nodo segnala un'anomalia ma gli altri non concordano, probabilmente è un falso positivo. Il mesh riduce il rumore.

# Abilita il mesh tra due server

# Server A
lynx-agent --token TOKEN \
--mesh --mesh-port 7300 --peers server-b:7300

# Server B
lynx-agent --token TOKEN \
--mesh --mesh-port 7300 --peers server-a:7300

Il mesh consensus usa il voto di maggioranza: un'anomalia viene confermata solo quando più della metà dei peer concorda. La dashboard mostra il rapporto di accordo (es. "MESH 3/4").

Riferimento configurazione

Flag CLI	Variabile env	Default	Descrizione
`--dashboard-url`	`LYNX_DASHBOARD_URL`	https://luviner.com	URL della tua dashboard Luviner SaaS
`--token`	`LYNX_API_TOKEN`	—	Token di autenticazione API
`--learn-time`	—	300	Durata dell'apprendimento baseline in secondi
`--interval`	—	10	Intervallo di raccolta metriche in secondi
`--threshold`	—	0.7	Soglia anomaly score per gli alert (0–1)
`--docker`	—	off	Abilita il monitoraggio container Docker
`--mesh`	—	off	Abilita il mesh consensus con i peer
`--mesh-port`	—	7300	Porta TCP per la comunicazione mesh
`--peers`	—	—	Lista di indirizzi peer separati da virgola (host:port)
`--name`	—	hostname	Nome visualizzato per questo nodo nella dashboard

Alert su Slack

Ricevi alert in tempo reale su un canale Slack quando un nodo genera un warning o critical. Disponibile nei piani Team, Business e Scale.

Vai su api.slack.com/apps e crea una nuova Slack App (From scratch).
Nelle impostazioni dell'app, vai su Incoming Webhooks e attivalo.
Clicca "Add New Webhook to Workspace", scegli un canale e copia l'URL del Webhook.
In Lynx Monitoring → Impostazioni, incolla l'URL e clicca Salva. Usa "Invia Messaggio di Test" per verificare.

Gli alert Slack hanno un rate limit di 1 per nodo ogni 10 minuti, come quelli email. I due canali funzionano indipendentemente — puoi attivarne uno, entrambi, o nessuno.

Esecuzione come servizio

Lo script di installazione registra automaticamente Lynx come servizio systemd su Linux. Puoi gestirlo con:

# systemd (installato automaticamente)
sudo systemctl status luviner-lynx
sudo systemctl restart luviner-lynx
sudo journalctl -u luviner-lynx -f

# Esecuzione manuale in background
nohup lynx-agent --token TOKEN > /var/log/lynx.log 2>&1 &

Risoluzione problemi

Il nodo risulta "offline"

Un nodo viene marcato offline quando non riceve heartbeat entro la soglia configurata (default: 5 minuti, regolabile nelle Impostazioni). Controlla:

Il processo agent sta girando? Verifica con: ps aux | grep lynx-agent
Il server riesce a raggiungere l'URL della dashboard? Testa con: curl -I https://luviner.com
Il token API è corretto? Rigeneralo dalla dashboard se necessario.

Troppi falsi alert

I falsi positivi di solito si verificano quando la baseline di apprendimento è troppo breve.

Usa almeno 5 minuti di tempo di apprendimento (il default è 300 secondi).
Aumenta la soglia anomalia nelle Impostazioni (es. da 0.70 a 0.80).
Abilita il mesh consensus per la validazione incrociata con altri nodi.

Drift score alto

Il drift indica che il comportamento del server è cambiato significativamente dalla baseline appresa.

Riavvia l'agent per ri-apprendere il nuovo normale: sudo systemctl restart lynx-agent
Se il drift continua a salire, potrebbe indicare un cambiamento reale (nuovo deploy, cambio pattern di traffico).

FAQ

Quanta CPU/RAM usa l'agent?

Minima. L'agent usa ~30 MB di RAM e <1% CPU. La rete neurale gira interamente on-device con aritmetica a virgola fissa.

Lynx invia i miei dati nel cloud?

No. Solo gli anomaly score e i metadati (stato, nome nodo) vengono inviati alla dashboard. Le metriche raw restano sul tuo server.

Posso monitorare server Windows?

Attualmente Lynx supporta Linux e macOS. Il supporto Windows è in programma.

Quanti nodi posso monitorare gratis?

Il piano Starter include 5 nodi gratuiti. Passa al piano Team o Business per monitorare più nodi.