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.

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

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

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

Enable and Start
```
systemctl enable --now netronome@$USER
```

Docker Installation

Quick Docker deployment with automatic dependency installation:

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

# Basic setup with SQLite
docker-compose up -d

# Or with PostgreSQL for better performance
docker-compose -f 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

Generate Configuration
```
netronome generate-config
```
This creates ~/.config/netronome/config.toml with default settings.
Start Server
```
netronome serve
```
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:

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

Multi-Site Infrastructure

Monitor connectivity between office locations:

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

Server Health Monitoring

Track server performance metrics:

Install agents on production servers
Monitor CPU, memory, disk usage, and temperatures
Configure threshold alerts for resource exhaustion
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

[tailscale]
enabled = true
method = "auto"  # auto, host, or tsnet
auth_key = ""    # Required for tsnet mode
hostname = ""    # Optional custom hostname

# Discovery settings
auto_discover = true
discovery_interval = "5m"
discovery_port = 8200

GeoIP Configuration

Enable country flags and ASN information in traceroute results (optional):

Sign up for a free license at MaxMind
Download the GeoLite2 databases (Country and ASN)

Add paths to your config:

[geoip]
country_database_path = "/path/to/GeoLite2-Country.mmdb"
asn_database_path = "/path/to/GeoLite2-ASN.mmdb"

Netronome works perfectly without GeoIP - this just adds visual country indicators.

Notifications

Configure notifications through the web interface at Settings > Notifications.

Supported Services

Discord, Telegram, Slack, Teams
Email (SMTP), Pushover, Pushbullet
Gotify, Matrix, Ntfy, Webhook
And 15+ more via Shoutrrr

Notification Events

Speed test completion, failures, threshold breaches
Packet loss state changes (degraded/recovered)
Agent metrics: CPU, memory, disk, bandwidth, temperature thresholds

Scheduling

Two scheduling types supported:

Duration-based Intervals

"30s", "5m", "1h", "24h"

Adds 1-300 seconds of random jitter to prevent simultaneous execution.

Exact Time Intervals

"exact:14:30"           # Daily at 2:30 PM
"exact:00:00,12:00"     # Midnight and noon daily

Adds 1-60 seconds of random jitter.

Reference

Environment Variables

All configuration options can be set via environment variables using the NETRONOME__ prefix. Here are the most commonly used:

# Server settings
NETRONOME__HOST=0.0.0.0              # Listen address
NETRONOME__PORT=7575                 # Web UI port
NETRONOME__BASE_URL=/                # Base URL for reverse proxy

# Database (SQLite by default)
NETRONOME__DB_TYPE=sqlite            # sqlite or postgres
NETRONOME__DB_PATH=netronome.db      # SQLite database path

# PostgreSQL (when DB_TYPE=postgres)
NETRONOME__DB_HOST=localhost
NETRONOME__DB_PORT=5432
NETRONOME__DB_USER=postgres
NETRONOME__DB_PASSWORD=secret
NETRONOME__DB_NAME=netronome
NETRONOME__DB_SSLMODE=disable

# Authentication
NETRONOME__AUTH_WHITELIST=127.0.0.1/32,192.168.1.0/24  # IP whitelist (comma-separated)
NETRONOME__SESSION_SECRET=           # Session secret (auto-generated if empty)

# OIDC (optional)
NETRONOME__OIDC_ISSUER=https://accounts.google.com
NETRONOME__OIDC_CLIENT_ID=your-client-id
NETRONOME__OIDC_CLIENT_SECRET=your-secret
NETRONOME__OIDC_REDIRECT_URL=https://example.com/api/auth/oidc/callback

Complete Environment Variables Reference (click to expand)

Server Configuration

NETRONOME__HOST=127.0.0.1                    # Server listen address
NETRONOME__PORT=7575                         # Server port
NETRONOME__BASE_URL=/                        # Base URL path (for reverse proxy)
NETRONOME__GIN_MODE=                         # Gin framework mode (debug/release/test)

Database Configuration

NETRONOME__DB_TYPE=sqlite                    # Database type: sqlite or postgres
NETRONOME__DB_PATH=netronome.db              # SQLite database file path
NETRONOME__DB_HOST=localhost                 # PostgreSQL host
NETRONOME__DB_PORT=5432                      # PostgreSQL port
NETRONOME__DB_USER=postgres                  # PostgreSQL user
NETRONOME__DB_PASSWORD=                      # PostgreSQL password
NETRONOME__DB_NAME=netronome                 # PostgreSQL database name
NETRONOME__DB_SSLMODE=disable                # PostgreSQL SSL mode

Logging

NETRONOME__LOG_LEVEL=info                    # Log level: trace, debug, info, warn, error, fatal, panic

Authentication

NETRONOME__AUTH_WHITELIST=                   # Comma-separated CIDR networks to bypass auth
NETRONOME__SESSION_SECRET=                   # Session encryption secret (auto-generated if empty)

OIDC Configuration

NETRONOME__OIDC_ISSUER=                      # OIDC provider URL
NETRONOME__OIDC_CLIENT_ID=                   # OIDC client ID
NETRONOME__OIDC_CLIENT_SECRET=               # OIDC client secret
NETRONOME__OIDC_REDIRECT_URL=                # OIDC callback URL

Speed Test Configuration

NETRONOME__SPEEDTEST_TIMEOUT=30              # Overall speedtest timeout (seconds)

# iperf3 settings
NETRONOME__IPERF_TEST_DURATION=10            # Test duration (seconds)
NETRONOME__IPERF_PARALLEL_CONNS=4            # Parallel connections
NETRONOME__IPERF_TIMEOUT=60                  # iperf3 timeout (seconds)
NETRONOME__IPERF_PING_COUNT=5                # Ping count for latency test
NETRONOME__IPERF_PING_INTERVAL=1000          # Ping interval (milliseconds)
NETRONOME__IPERF_PING_TIMEOUT=10             # Ping timeout (seconds)

# LibreSpeed settings
NETRONOME__LIBRESPEED_TIMEOUT=60             # LibreSpeed timeout (seconds)

Pagination

NETRONOME__DEFAULT_PAGE=1                    # Default page number
NETRONOME__DEFAULT_PAGE_SIZE=20              # Default items per page
NETRONOME__MAX_PAGE_SIZE=100                 # Maximum items per page
NETRONOME__DEFAULT_TIME_RANGE=1w             # Default time range for queries
NETRONOME__DEFAULT_LIMIT=20                  # Default query limit

GeoIP Configuration

NETRONOME__GEOIP_COUNTRY_DATABASE_PATH=      # Path to GeoLite2-Country.mmdb
NETRONOME__GEOIP_ASN_DATABASE_PATH=          # Path to GeoLite2-ASN.mmdb

Packet Loss Monitoring

NETRONOME__PACKETLOSS_ENABLED=true                      # Enable packet loss monitoring
NETRONOME__PACKETLOSS_DEFAULT_INTERVAL=3600             # Default test interval (seconds)
NETRONOME__PACKETLOSS_DEFAULT_PACKET_COUNT=10           # Packets per test
NETRONOME__PACKETLOSS_MAX_CONCURRENT_MONITORS=10        # Max concurrent monitors
NETRONOME__PACKETLOSS_PRIVILEGED_MODE=true              # Use privileged ICMP mode
NETRONOME__PACKETLOSS_RESTORE_MONITORS_ON_STARTUP=false # Restore monitors on startup

Agent Configuration

NETRONOME__AGENT_HOST=0.0.0.0                # Agent listen address
NETRONOME__AGENT_PORT=8200                   # Agent port
NETRONOME__AGENT_INTERFACE=                  # Network interface to monitor (empty for all)
NETRONOME__AGENT_API_KEY=                    # Agent API key for authentication
NETRONOME__AGENT_DISK_INCLUDES=              # Comma-separated paths to include
NETRONOME__AGENT_DISK_EXCLUDES=              # Comma-separated paths to exclude

Monitor Configuration

NETRONOME__MONITOR_ENABLED=true              # Enable system monitoring
NETRONOME__MONITOR_RECONNECT_INTERVAL=30s    # Agent reconnection interval

Tailscale Configuration

# Core settings
NETRONOME__TAILSCALE_ENABLED=false           # Enable Tailscale integration
NETRONOME__TAILSCALE_METHOD=auto             # Method: auto, host, or tsnet
NETRONOME__TAILSCALE_AUTH_KEY=               # Auth key (required for tsnet)

# TSNet settings
NETRONOME__TAILSCALE_HOSTNAME=               # Custom hostname (optional)
NETRONOME__TAILSCALE_EPHEMERAL=false         # Remove on shutdown
NETRONOME__TAILSCALE_STATE_DIR=~/.config/netronome/tsnet  # State directory
NETRONOME__TAILSCALE_CONTROL_URL=            # For Headscale (optional)

# Agent settings
NETRONOME__TAILSCALE_AGENT_PORT=8200         # Port for agent to listen on

# Discovery settings
NETRONOME__TAILSCALE_AUTO_DISCOVER=true      # Auto-discover Tailscale agents
NETRONOME__TAILSCALE_DISCOVERY_INTERVAL=5m   # Discovery check interval
NETRONOME__TAILSCALE_DISCOVERY_PORT=8200     # Port to probe for agents
NETRONOME__TAILSCALE_DISCOVERY_PREFIX=       # Hostname prefix filter

# Deprecated (for backward compatibility)
NETRONOME__TAILSCALE_PREFER_HOST=false       # Prefer host mode over tsnet
NETRONOME__TAILSCALE_AGENT_ENABLED=false     # Enable agent mode
NETRONOME__TAILSCALE_AGENT_ACCEPT_ROUTES=true # Accept Tailscale routes

CLI Commands

# Server management
netronome serve                    # Start the server
netronome generate-config          # Generate default config

# User management
netronome create-user <username>   # Create new user
netronome change-password <username> # Change user password

# Agent mode
netronome agent                    # Start monitoring agent
netronome agent --api-key secret   # Agent with authentication

FAQ & Troubleshooting

Getting Started

Q: What's the default username/password?

For manual installation, you register through the web interface on first visit - no default credentials.

Q: Can I access Netronome from other devices on my network?

Yes! Change the host in your config from 127.0.0.1 to 0.0.0.0 or set NETRONOME__HOST=0.0.0.0.

Q: Do I need all the external dependencies?

No, Netronome works without them. You only need:

iperf3 for iperf3 speed tests
librespeed-cli for LibreSpeed tests
Speedtest.net works out of the box

Common Issues

Q: "Port 7575 already in use" error?

Another service is using the port. Either stop that service or change Netronome's port in the config.

Q: Speed tests are slower than expected?

Ensure you're testing to a nearby server
Check if other devices are using bandwidth
Try different test providers (some ISPs throttle specific tests)
For iperf3, ensure the server supports your connection speed

Temperature Monitoring

Q: Why don't I see disk temperatures?

Disk temperature monitoring requires:

Platform support (Linux/macOS for SATA, all platforms for NVMe)
Elevated privileges (root/sudo for SMART access)
SMART-enabled drives with temperature sensors

Network Diagnostics

Q: Why do I see 0% packet loss but 100% loss at intermediate hops?

This is normal behavior. Intermediate routers often block/rate-limit ICMP responses for security while still forwarding traffic. Overall packet loss measures end-to-end connectivity, which is the primary indicator of network performance.

Agent Discovery

Q: Tailscale agent not discovered?

Ensure agent runs on discovery port (default 8200)
Verify both server and agent are on same Tailnet
Check connectivity: tailscale ping <agent-hostname>
Test endpoint: curl http://<agent-hostname>:8200/netronome/info

Building from Source

Building Netronome creates a single binary with the frontend embedded:

With Full SMART Support (Linux/macOS)

git clone https://github.com/autobrr/netronome
cd netronome
make build  # Builds frontend, embeds it, compiles Go binary

Without SMART Support

# First build frontend
cd web && pnpm install && pnpm build && cd ..
# Then build Go binary
CGO_ENABLED=0 go build -tags nosmart -o bin/netronome ./cmd/netronome

Docker Build

make docker-build
make docker-run

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the GNU General Public License v2.0 - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 163 Commits
.claude		.claude
.github		.github
ai_docs		ai_docs
cmd/netronome		cmd/netronome
docs		docs
internal		internal
pkg/migrator		pkg/migrator
scripts		scripts
web		web
.air.toml		.air.toml
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
ci.Dockerfile		ci.Dockerfile
config.toml		config.toml
docker-compose.postgres.yml		docker-compose.postgres.yml
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
librespeed-servers.json		librespeed-servers.json

Uh oh!

License

autobrr/netronome

Folders and files

Latest commit

History

Repository files navigation

Netronome

Quick Start

Option 1: Download from Releases Page

Option 2: One-liner Installation

Table of Contents

Features

Core Functionality

Network Diagnostics

System Monitoring

Additional Features

Technical Overview

Prerequisites

System Requirements

External Dependencies

Installation

Linux Generic

Docker Installation

Basic Configuration

First Run Setup

Authentication

Built-in Authentication

OpenID Connect (OIDC)

IP Whitelisting

Database

SQLite (Default)

PostgreSQL

Reverse Proxy with Base URL

1. Configure Netronome

2. Configure nginx

Common Use Cases

Home Network Monitoring

Multi-Site Infrastructure

Server Health Monitoring

Advanced Configuration

System Monitoring

Quick Agent Installation

Manual Agent Setup

Agent Configuration

Packet Loss Monitoring

Key Features

Important Notes

Tailscale Integration

Agent Setup

Server Configuration

GeoIP Configuration

Notifications

Supported Services

Notification Events

Scheduling

Duration-based Intervals

Exact Time Intervals

Reference

Environment Variables

Server Configuration

Database Configuration

Logging

Authentication

OIDC Configuration

Speed Test Configuration

Pagination

GeoIP Configuration

Packet Loss Monitoring

Agent Configuration

Monitor Configuration

Tailscale Configuration

CLI Commands

FAQ & Troubleshooting

Getting Started

Common Issues

Temperature Monitoring

Network Diagnostics

Agent Discovery

Building from Source

Packages