Netronome

<h1 align="center">Netronome</h1> <p align="center"> <strong>Monitor. Analyze. Alert.</strong><br> A complete network performance monitoring solution with distributed agents, real-time metrics, and beautiful visualizations. </p> <div align="center"> <p align="center"> <img src="https://img.shields.io/badge/Go-1.24-blue?logo=go" alt="Go version"> <img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build Status"> <img src="https://img.shields.io/github/v/release/autobrr/netronome" alt="Latest Release"> </a> <a href="https://github.com/autobrr/netronome"> <img src="https://img.shields.io/badge/%F0%9F%92%A1%20netronome-docs-00ACD7.svg?style=flat-square"> </a> </p>

</div> <p align="center"> <img src=".github/assets/netronome_dashboard.png" alt="Netronome Dashboard"> </p>

Netronome is a complete network performance monitoring solution that helps you understand and track your network's health. Whether you're monitoring your home internet connection, managing multi-site infrastructure, or tracking server performance, Netronome provides the insights you need through an intuitive web interface.

Built with Go and designed for simplicity, Netronome packages both frontend and backend into a single binary for effortless deployment. With a minimal footprint of just ~35MB RAM usage, it's perfect for resource-constrained environments. No complex setups - just download, configure, and run.

Key capabilities: Speed testing across multiple providers, continuous packet loss monitoring, distributed server monitoring via lightweight agents, and automated alerting - all with beautiful visualizations and historical tracking.

Quick Start

Get Netronome running in under 5 minutes:

Option 1: Download from Releases Page

Download prebuilt binaries from the Releases page.

Option 2: One-liner Installation

# Download latest release
wget $(curl -s https://api.github.com/repos/autobrr/netronome/releases/latest | grep download | grep linux_x86_64 | cut -d\" -f4)
tar -C /usr/local/bin -xzf netronome*.tar.gz

# Generate default config
netronome generate-config

# Start the server
netronome serve

Open http://localhost:7575 in your browser and create your account through the registration page. For Docker users, see the Docker Installation section.

Table of Contents

• Features
• External Dependencies
• Installation
  • Linux Generic
  • Docker Installation
• Basic Configuration
  • First Run Setup
  • Authentication
  • Database
• Advanced Configuration
  • System Monitoring
  • Packet Loss Monitoring
  • Tailscale Integration
  • Docker Agent Integration
  • GeoIP Configuration
  • Notifications
  • Scheduling
• Reference
  • Environment Variables
  • CLI Commands
• FAQ & Troubleshooting
• Building from Source
• Contributing
• License

Features

Core Functionality

• Speed Testing: Multiple providers (Speedtest.net, iperf3, LibreSpeed) with real-time progress and historical tracking
• Network Diagnostics: Traceroute and continuous packet loss monitoring with MTR integration
• System Monitoring: Deploy agents for distributed server monitoring with real-time metrics
• Flexible Scheduling: Automated tests with customizable intervals and smart jitter prevention

Network Diagnostics

<p align="center"> <img src=".github/assets/packetloss-monitors(mtr).png" alt="Network Diagnostics Interface"> </p>

Advanced network path analysis with:

• Cross-platform traceroute support
• Continuous ICMP monitoring
• Per-hop packet loss statistics
• GeoIP visualization with country flags
• Historical performance tracking

System Monitoring

<p align="center"> <img src=".github/assets/agents-dashboard.png" alt="System Monitoring Dashboard"> </p> <p align="center"> <img src=".github/assets/agents-bandwidth.png" alt="Bandwidth Monitoring"> </p> <p align="center"> <img src=".github/assets/agents-systeminfo.png" alt="Agent System Information"> </p>

Monitor multiple servers from one dashboard:

• CPU, memory, disk, and temperature metrics
• Real-time bandwidth monitoring (vnstat)
• Auto-discovery for Tailscale networks
• Configurable alerting thresholds
• Live data streaming via SSE
• Agents are also single binaries - same simple deployment

Additional Features

• Modern UI: Responsive design with dark mode support
• Authentication: Built-in auth, OIDC support, IP whitelisting
• Notifications: 15+ services via Shoutrrr (Discord, Telegram, Email, etc.)
• Database Support: SQLite (default) or PostgreSQL
• Tailscale Integration: Secure mesh networking without port exposure

Technical Overview

• Single Binary: Frontend and backend compiled into one executable (~66MB)
• Language: Written in Go for performance and easy deployment
• Frontend: React with TypeScript, embedded in the binary
• Database: SQLite by default, PostgreSQL optional
• No Runtime Dependencies: Just the binary and optional external tools

Prerequisites

System Requirements

• Operating System: Linux, macOS, or Windows
• Architecture: x86_64, ARM64
• Memory: ~35MB (typical usage)
• Disk Space: 65MB for application + database growth

External Dependencies

The following tools enable specific features (automatically included in Docker):

• iperf3 - For iperf3 speed testing
• librespeed-cli - For LibreSpeed testing
• traceroute - For basic network path discovery (usually pre-installed)
• mtr - For advanced packet loss analysis per hop (optional, falls back to traceroute)
  • Windows users should get the binary from https://github.com/dqos/WinMTRCmd/releases
• vnstat - For bandwidth monitoring on agents (optional but recommended)

Install on Linux:

# Debian/Ubuntu
sudo apt-get install iperf3 traceroute mtr vnstat

# RHEL/Fedora
sudo dnf install iperf3 traceroute mtr vnstat

Notes:

• Speedtest.net is built-in
• All external dependencies are optional - Netronome gracefully handles missing tools

Installation

Linux Generic

1. Download and Install

   wget $(curl -s https://api.github.com/repos/autobrr/netronome/releases/latest | grep download | grep linux_x86_64 | cut -d\" -f4)
   tar -C /usr/local/bin -xzf netronome*.tar.gz
   

2. Create Systemd Service (Recommended)

   sudo tee /etc/systemd/system/netronome@.service > /dev/null <<EOF
   [Unit]
   Description=netronome service for %i
   After=syslog.target network-online.target
   
   [Service]
   Type=simple
   User=%i
   Group=%i
   ExecStart=/usr/local/bin/netronome serve --config=/home/%i/.config/netronome/config.toml
   
   [Install]
   WantedBy=multi-user.target
   EOF
   

3. Enable and Start

   systemctl enable --now netronome@$USER
   

Windows Generic

1. Download and Install

Get the latest binary from https://github.com/autobrr/netronome/releases
Unzip the release into a folder
Place any third party binaries in the same folder
Add the folder to Windows environment variables - restart explorer.exe (and any open terminals)

2. Create a Windows Task Schedule

https://www.windowscentral.com/how-create-automated-task-using-task-scheduler-windows-10

3. Create Config

Run `netronome generate-config`
Edit config.toml to suit `C:\Users\{USERNAME}\.config\netronome`

Docker Installation

Quick Docker deployment with automatic dependency installation:

# Clone the repository (for docker-compose files in distrib/docker)
git clone https://github.com/autobrr/netronome.git
cd netronome

# Basic setup with SQLite
docker-compose -f distrib/docker/docker-compose.yml up -d

# Or with PostgreSQL for better performance
docker-compose -f distrib/docker/docker-compose.postgres.yml up -d

The Docker image includes all dependencies (iperf3, librespeed-cli, traceroute, mtr, vnstat) pre-installed, so you don't need to install them separately. For Tailscale integration with Docker, see the Docker Tailscale Sidecar Guide.

Basic Configuration

First Run Setup

1. Generate Configuration

   netronome generate-config
   

   This creates ~/.config/netronome/config.toml with default settings.

2. Start Server

   netronome serve
   

3. Access Interface Navigate to http://localhost:7575 and register your account through the web interface.

   To access from other devices on your network, change the host in config.toml from 127.0.0.1 to 0.0.0.0.

Authentication

Netronome supports multiple authentication methods:

Built-in Authentication

Users can register directly through the web interface on first visit. For automation or admin purposes, you can also manage users via CLI:

netronome create-user <username>     # Create user via CLI
netronome change-password <username>  # Change password via CLI

OpenID Connect (OIDC)

Configure via environment variables:

export NETRONOME__OIDC_ISSUER=https://your-provider.com
export NETRONOME__OIDC_CLIENT_ID=your-client-id
export NETRONOME__OIDC_CLIENT_SECRET=your-client-secret
export NETRONOME__OIDC_REDIRECT_URL=https://netronome.example.com