GitHub - autobrr/netronome: Netronome is a modern network speed testing and monitoring tool built with Go and React.
Extracto
Netronome is a modern network speed testing and monitoring tool built with Go and React. - autobrr/netronome
Resumen
Resumen Principal
Netronome es una solución integral de monitoreo del rendimiento de red que ofrece capacidades avanzadas para analizar, alertar y visualizar la salud de infraestructuras diversas. Diseñada para la simplicidad y eficiencia, esta herramienta de código abierto combina su frontend y backend en un único binario (aproximadamente 66MB
Contenido
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
- Basic Configuration
- Advanced Configuration
- Reference
- 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
-
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
Windows Generic
- 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)
- Create a Windows Task Schedule
https://www.windowscentral.com/how-create-automated-task-using-task-scheduler-windows-10
- 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) 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.tomlwith default settings. -
Start Server
-
Access Interface Navigate to
http://localhost:7575and 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.1to0.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.8or1.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 | bashThe 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
Docker Agent Integration
You may wish to run an agent inside of a Docker container, for example, to monitor VPN traffic on a container like Gluetun. By default, this will not work, because the container cannot access the host's network interface for statistics.
To monitor bandwidth on VPN networked containers, you will need to run both the agent, and a vnstat container in the same network as your VPN container.
Docker Agent Integration Compose Example
services: # Gluetun - VPN client container gluetun: image: qmcgaw/gluetun:latest container_name: gluetun restart: unless-stopped cap_add: - NET_ADMIN devices: - /dev/net/tun:/dev/net/tun volumes: - /path/to/gluetun:/gluetun environment: - VPN_SERVICE_PROVIDER=your_provider - VPN_TYPE=wireguard # ... your VPN configuration networks: monitoring: aliases: - netronome-vpn-agent # Allows dashboard to reach agent by name # vnstat - collects bandwidth data on the VPN tunnel vnstat: image: vergoh/vnstat:latest container_name: vnstat restart: unless-stopped network_mode: "service:gluetun" depends_on: - gluetun environment: - TZ= volumes: - /path/to/vnstat:/var/lib/vnstat # Add a mount for the vnstat db # Netronome VPN agent - monitors VPN tunnel traffic netronome-vpn-agent: image: ghcr.io/autobrr/netronome:latest # You could also put the agent bin in a smaller image container_name: netronome-vpn-agent restart: unless-stopped network_mode: "service:gluetun" depends_on: - gluetun - vnstat environment: - TZ= - NETRONOME__AGENT_HOST=0.0.0.0 - NETRONOME__AGENT_PORT=8200 - NETRONOME__AGENT_API_KEY= # Optional: set for authentication command: - agent - --interface - tun0 # VPN tunnel interface volumes: - /path/to/vnstat:/var/lib/vnstat:ro cap_add: - NET_RAW - NET_ADMIN # Netronome dashboard - main web interface netronome: image: ghcr.io/autobrr/netronome:latest container_name: netronome restart: unless-stopped environment: - TZ= - NETRONOME__HOST=0.0.0.0 - NETRONOME__PORT=7575 ports: - "7575:7575" volumes: - /path/to/netronome:/data networks: - monitoring cap_add: - NET_RAW - NET_ADMIN networks: monitoring: driver: bridge
Determine the correct VPN intercface to monitor by running:
docker exec gluetun ip -br link
Common interface names:
tun0- OpenVPN or Gluetun custom providerwg0- WireGuard
Limiting Monitored Interfaces
By default, vnstat will monitor all detected interfaces (e.g., eth0 and tun0). To monitor only the VPN tunnel:
# Remove unwanted interfaces from vnstat docker exec vnstat vnstat --remove -i eth0 --force # Verify only tun0 is being tracked docker exec vnstat vnstat
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
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, panicAuthentication
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:
iperf3for iperf3 speed testslibrespeed-clifor 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.
Fuente: GitHub

.png)



