Lynx Quick Start
Get your servers monitored in 5 minutes. Lynx learns what "normal" looks like and alerts you when something changes.
What is Lynx?
Lynx is a lightweight monitoring agent that runs on your servers and learns their normal behavior using AI. Instead of setting manual thresholds, Lynx builds a baseline during a learning phase and then detects anomalies automatically.
Lynx collects 12 system metrics (CPU, memory, disk, network, processes, connections) every few seconds and runs them through a neural network trained on your specific server's behavior.
Lynx works offline and on-device. Your data never leaves your server — only anomaly scores are sent to the dashboard.
How it works
- Learning — For the first 5 minutes, Lynx collects metrics and trains a model of normal behavior.
- Monitoring — After learning, every new data point is compared against the baseline. Deviations produce an anomaly score (0–10).
- Drift detection — Lynx also tracks if the overall distribution of metrics is shifting over time (drift score 0–100%).
- Alerting — When the anomaly score exceeds your threshold, Lynx fires an alert to your dashboard and (optionally) sends an email.
Installation
Supported platforms: Native install on Linux (Ubuntu, Debian, RHEL, CentOS, Rocky, AlmaLinux — x86_64 and aarch64). On macOS the installer automatically falls back to a Docker container — see the macOS section below. Windows is not supported as a native install; use WSL2 (which is Linux) or Docker Desktop.
Step 1: Generate API token
Go to the Lynx dashboard and click "Generate API Token". Copy the token — it will only be shown once.
Step 2: Install the agent
Run the installer on your server:
curl -sL https://luviner.com/install-lynx.sh | bash
Step 3: Start monitoring
Run the agent with your dashboard URL and token:
lynx-agent --token YOUR_API_TOKEN
That's it! Your node will appear in the dashboard within seconds. It will learn for 5 minutes, then start monitoring.
Install on macOS (Docker fallback)
macOS native install is not supported because Lynx ships compiled Cython binaries that would require a separate wheel for every Python minor version × every macOS major version. Instead, the installer detects macOS and runs the official Docker image (luviner/lynx). Prerequisite: Docker Desktop installed and running. Same one-liner as Linux:
curl -sL https://luviner.com/install-lynx.sh | bash
docker logs -f luviner-lynx
What is monitored on macOS: In Docker mode the Lynx agent monitors the Docker containers running on your Mac (CPU, RAM, network, anomaly detection per container) — it does NOT monitor the Mac host itself. To monitor a real production server, install Lynx natively on a Linux box (the standard path).
Docker mode
Lynx can also monitor all your Docker containers automatically. It discovers running containers and tracks per-container CPU, memory, I/O and network usage.
curl -sL https://luviner.com/install-lynx.sh | bash -s -- --docker
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
Understanding scores
Anomaly Score (0–10)
Measures how different the current system state is from the learned baseline. Higher = more anomalous.
| Range | Meaning | Action |
|---|
| 0.0 – 0.3 | Normal | No action needed |
| 0.3 – 0.7 | Elevated | Worth monitoring, may indicate a developing issue |
| 0.7 – 1.0 | Critical | Investigate immediately — something unusual is happening |
Drift Score (0–100%)
Measures how much the overall metric distribution has shifted from the baseline. High drift means the server's behavior has fundamentally changed.
| Range | Meaning | Action |
|---|
| 0 – 30% | Stable | Baseline is still representative |
| 30 – 70% | Shifting | Behavior is changing — consider restarting the agent to re-learn |
| 70 – 100% | Significant drift | Restart the agent to build a new baseline |
Mesh consensus
When you run multiple Lynx agents on different servers, they can cross-validate each other using mesh consensus. If only one node reports an anomaly but others disagree, it's likely a false positive. Mesh reduces noise.
lynx-agent --token TOKEN \
--mesh --mesh-port 7300 --peers server-b:7300
lynx-agent --token TOKEN \
--mesh --mesh-port 7300 --peers server-a:7300
Mesh consensus uses majority voting: an anomaly is confirmed only when more than half the peers agree. The dashboard shows the agreement ratio (e.g., "MESH 3/4").
Configuration reference
| CLI flag | Env variable | Default | Description |
|---|
--dashboard-url | LYNX_DASHBOARD_URL | https://luviner.com | URL of your Luviner SaaS dashboard |
--token | LYNX_API_TOKEN | — | API authentication token |
--learn-time | — | 300 | Baseline learning duration in seconds |
--interval | — | 10 | Metrics collection interval in seconds |
--threshold | — | 0.7 | Anomaly score threshold for alerts (0–1) |
--docker | — | off | Enable Docker container monitoring |
--mesh | — | off | Enable mesh consensus with peers |
--mesh-port | — | 7300 | TCP port for mesh communication |
--peers | — | — | Comma-separated list of peer addresses (host:port) |
--name | — | hostname | Display name for this node in the dashboard |
Slack alerts
Receive real-time alerts in a Slack channel when a node triggers a warning or critical event. Available on Team, Business, and Scale plans.
- Go to api.slack.com/apps and create a new Slack App (From scratch).
- In your app settings, go to Incoming Webhooks and activate it.
- Click "Add New Webhook to Workspace", choose a channel, and copy the Webhook URL.
- In Lynx Monitoring → Settings, paste the URL and click Save. Use "Send Test Message" to verify.
Slack alerts are rate-limited to 1 per node per 10 minutes, same as email alerts. Both channels work independently — you can enable one, both, or neither.
Running as a service
The install script automatically registers Lynx as a systemd service on Linux. You can manage it with:
sudo systemctl status luviner-lynx
sudo systemctl restart luviner-lynx
sudo journalctl -u luviner-lynx -f
nohup lynx-agent --token TOKEN > /var/log/lynx.log 2>&1 &
Troubleshooting
Node shows "offline"
A node is marked offline when no heartbeat is received within the configured threshold (default: 5 minutes, adjustable in Settings). Check:
- Is the agent process running? Check with: ps aux | grep lynx-agent
- Can the server reach your dashboard URL? Test with: curl -I https://luviner.com
- Is the API token correct? Regenerate it from the dashboard if needed.
Too many false alerts
False positives usually happen when the learning baseline is too short.
- Use at least 5 minutes of learning time (default is 300 seconds).
- Increase the anomaly threshold in Settings (e.g., from 0.70 to 0.80).
- Enable mesh consensus to cross-validate with other nodes.
High drift score
Drift means the server's behavior has changed significantly since the baseline was learned.
- Restart the agent to re-learn the new normal: sudo systemctl restart lynx-agent
- If drift keeps rising, it may indicate a real change (new deployment, traffic pattern shift).
FAQ
How much CPU/RAM does the agent use?
Minimal. The agent uses ~30 MB of RAM and <1% CPU. The neural network runs entirely on-device with fixed-point arithmetic.
Does Lynx send my data to the cloud?
No. Only anomaly scores and metadata (status, node name) are sent to the dashboard. Raw metrics stay on your server.
Can I monitor Windows servers?
Currently Lynx supports Linux and macOS. Windows support is planned.
How many nodes can I monitor for free?
The Starter plan includes 5 free nodes. Upgrade to Team or Business for more nodes.