Netronome

Monitor. Analyze. Alert.

A complete network performance monitoring solution with distributed agents, real-time metrics, and beautiful visualizations.

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

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

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

bash 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

1. Create Systemd Service (Recommended)

```bash 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 ```

1. Enable and Start bash 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)

1. Create a Windows Task Schedule

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

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

bash netronome generate-config

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

1. Start Server

bash netronome serve

1. 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/api/auth/oidc/callback

IP Whitelisting

Add to config.toml:

[auth]
whitelist = ["127.0.0.1/32", "192.168.1.0/24"]

Database

SQLite (Default)

No additional setup required. Database file is created automatically.

PostgreSQL

Configure via environment variables:

export NETRONOME__DB_TYPE=postgres
export NETRONOME__DB_HOST=localhost
export NETRONOME__DB_PORT=5432
export NETRONOME__DB_USER=postgres
export NETRONOME__DB_PASSWORD=your-password
export NETRONOME__DB_NAME=netronome

Reverse Proxy with Base URL

To serve Netronome under a subpath (e.g., /netronome) behind nginx:

1. Configure Netronome

Set the base URL in your config.toml:

[server]
host = "127.0.0.1"  # Listen only on localhost since nginx will proxy
port = 7575
base_url = "/netronome"  # The subpath you want to use

2. Configure nginx

Add this location block to your nginx configuration:

# Redirect /netronome to /netronome/
location = /netronome {
    return 301 /netronome/;
}

location /netronome/ {
    proxy_pass http://127.0.0.1:7575;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 86400;
}

That's it! The minimal configuration above handles WebSocket/SSE for real-time features.

Common Use Cases

Home Network Monitoring

Monitor your internet connection quality:

1. Schedule hourly speed tests to your ISP
2. Set up packet loss monitoring to 8.8.8.8 or 1.1.1.1
3. Configure notifications when speeds drop below expected thresholds

Multi-Site Infrastructure

Monitor connectivity between office locations:

1. Deploy agents at each site
2. Configure iperf3 tests between locations
3. Use Tailscale for secure agent communication
4. Set up alerts for degraded inter-site connectivity

Server Health Monitoring

Track server performance metrics:

1. Install agents on production servers
2. Monitor CPU, memory, disk usage, and temperatures
3. Configure threshold alerts for resource exhaustion
4. Track bandwidth usage patterns

Advanced Configuration

System Monitoring

Deploy monitoring agents on remote servers for full system visibility.

Quick Agent Installation

curl -sL https://netrono.me/install-agent | bash

The script provides interactive setup for:

• Network interface selection
• API key configuration
• Listening address and port
• Systemd service creation
• Automatic updates

Manual Agent Setup

# Basic agent
netronome agent

# With authentication
netronome agent --api-key your-secret-key

# Custom configuration
netronome agent --host 192.168.1.100 --port 8300 --interface eth0

Agent Configuration

Add to config.toml:

[agent]
host = "0.0.0.0"
port = 8200
interface = ""  # Empty for all interfaces
api_key = "your-secret-key"
disk_includes = ["/mnt/storage"]  # Additional mounts to monitor
disk_excludes = ["/boot", "/tmp"] # Mounts to exclude

[monitor]
enabled = true

Packet Loss Monitoring

Continuous network monitoring with MTR integration and performance tracking.

Key Features

• Flexible scheduling (10 seconds to 24 hours or exact daily times)
• Real-time progress indicators
• Historical performance charts
• Cross-platform support with privilege fallback

Important Notes

• MTR requires elevated privileges for full functionality
• Overall packet loss can be 0% even with intermediate hop timeouts (normal behavior)

Tailscale Integration

Native Tailscale support for secure mesh networking without port exposure.

Agent Setup

# Basic Tailscale agent
netronome agent --tailscale --tailscale-auth-key tskey-auth-YOUR-KEY

# Use existing tailscaled
netronome agent --tailscale --tailscale-method host

# Custom hostname
netronome agent --tailscale --tailscale-hostname "webserver-prod"

Server Configuration

```toml [tailsc