Gonzales

Gonzales - Internet Speed Monitor

 ██████╗  ██████╗ ███╗   ██╗███████╗ █████╗ ██╗     ███████╗███████╗
██╔════╝ ██╔═══██╗████╗  ██║╚══███╔╝██╔══██╗██║     ██╔════╝██╔════╝
██║  ███╗██║   ██║██╔██╗ ██║  ███╔╝ ███████║██║     █████╗  ███████╗
██║   ██║██║   ██║██║╚██╗██║ ███╔╝  ██╔══██║██║     ██╔══╝  ╚════██║
╚██████╔╝╚██████╔╝██║ ╚████║███████╗██║  ██║███████╗███████╗███████║
 ╚═════╝  ╚═════╝ ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝

Professional internet monitoring for full transparency. Gonzales runs automated speed tests 24/7 and builds a comprehensive performance database. Know exactly what your connection delivers — with objective data, historical trends, and detailed analytics.

Why Gonzales?

Transparency & Documentation — Continuous monitoring creates an objective record of your internet performance. Understand patterns, identify issues early, and have data-backed documentation when you need it.

Comprehensive Analytics — Real-time dashboard with historical trends, hourly/daily/weekly breakdowns, per-server comparisons, SLA compliance tracking, and 7-day predictive forecasts.

Home Assistant Integration — One-click add-on installation with 10 sensors + diagnostics. Build automations based on connection quality — notifications, smart device control, multi-WAN failover.

100% Local & Private — All data stays on your hardware. No cloud accounts, no subscriptions, no external dependencies. Self-hosted and fully offline-capable.

Developer-Friendly — REST API with OpenAPI docs, SSE streaming for real-time updates, MCP server for AI assistants, CLI with JSON output for scripting.

Core Features

Gonzales Ecosystem

Gonzales consists of three repositories. Which ones you need depends on your setup:

Add-on users don't need the HACS integration -- the add-on bundles it automatically.

English

Getting Started

You need three things installed on your system:

• Python 3.10+ -- python.org
• Node.js 18+ -- nodejs.org
• Ookla Speedtest CLI -- speedtest.net/apps/cli

On Debian/Ubuntu, install the Speedtest CLI like this:

sudo apt-get install curl
curl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash
sudo apt-get install speedtest

Then run these four commands:

cd gonzales
make install
make build
make run

The web dashboard is now running at http://localhost:8470 -- open it in your browser.

Raspberry Pi (ARM64) Setup

Gonzales runs on Raspberry Pi 4/5 (64-bit OS required). All Python dependencies are pure Python or have ARM64 wheels.

# Install Speedtest CLI for ARM64
curl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash
sudo apt-get install speedtest

# Install Node.js (ARM64)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Clone and run
git clone <your-repo-url> gonzales
cd gonzales
make install
make build
make run

For running as a systemd service, create /etc/systemd/system/gonzales.service:

[Unit]
Description=Gonzales Speed Monitor
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/gonzales/backend
ExecStart=/usr/bin/python3 -m gonzales
Restart=always

[Install]
WantedBy=multi-user.target

Advanced

Install without Make

If you don't have make, you can install everything manually:

# Backend
cd backend
pip install -e .

# Frontend
cd ../frontend
npm install
npm run build

# Copy built frontend into backend
cp -r dist ../backend/gonzales/static

# Start
cd ../backend
python3 -m gonzales

Terminal UI

Gonzales also has a demoscene-style terminal interface:

make tui

Keybindings: D Dashboard, H History, S Settings, T Test Now, Q Quit

Frontend Development

For hot-reloading during frontend work, run two terminals:

# Terminal 1: Backend
make run

# Terminal 2: Vite dev server
make frontend-dev

The Vite dev server runs at http://localhost:5173 and proxies API calls to the backend.

Configuration

Copy .env.example to .env and adjust values:

cp .env.example .env

Settings can also be changed at runtime via the web UI (Settings page) or the API (PUT /api/v1/config). Runtime changes are persisted to config.json, which is auto-created and gitignored.

In-App Documentation

The web dashboard includes a built-in Docs page accessible from the sidebar. It covers all features, configuration options, QoS profiles, network topology analysis, troubleshooting tips, and Home Assistant integration examples.

Theme Support

Gonzales supports three theme modes:

• Auto -- follows your system/browser preference (light or dark)
• Light -- always light mode
• Dark -- always dark mode

Change the theme in Settings > Appearance, or set GONZALES_THEME in your .env file.

API Endpoints

All under /api/v1:

AI Agent Integration

Gonzales supports integration with AI assistants like Claude Desktop via the Model Context Protocol (MCP).

MCP Server (for Claude Desktop)

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gonzales": {
      "command": "gonzales-mcp"
    }
  }
}

Available tools: get_latest_speedtest, run_speedtest, get_statistics, get_connection_status, get_outages, get_isp_score, get_summary

Summary API (for LLMs)

# JSON format
curl http://localhost:8470/api/v1/summary

# Markdown format (ideal for LLM context)
curl "http://localhost:8470/api/v1/summary?format=markdown"

See AGENTS.md for complete AI agent documentation.

Real-time Test Streaming

The /api/v1/speedtest/stream endpoint provides Server-Sent Events (SSE) during speed tests:

event: started
data: {"phase": "started"}

event: progress
data: {"phase": "download", "bandwidth_mbps": 450.5, "progress": 0.65}

event: complete
data: {"phase": "complete", "download_mbps": 500.2, "upload_mbps": 250.1, "ping_ms": 12.3}

CLI Commands

Gonzales includes a comprehensive CLI for scripting and automation:

# Run a speed test
gonzales run

# View statistics
gonzales stats

# Smart Scheduler commands
gonzales smart-scheduler status    # View scheduler phase, stability, data usage
gonzales smart-scheduler enable    # Enable adaptive scheduling
gonzales smart-scheduler disable   # Disable adaptive scheduling
gonzales smart-scheduler config    # View/update scheduler configuration

# Root-Cause Analysis commands
gonzales root-cause analyze        # Full network health analysis
gonzales root-cause fingerprints   # View detected problem patterns
gonzales root-cause recommendations # Get actionable recommendations
gonzales root-cause hops           # View hop-speed correlations

Verification

# Manual speed test
curl -X POST http://localhost:8470/api/v1/speedtest/trigger

# Check latest result
curl http://localhost:8470/api/v1/measurements/latest

# Enhanced statistics
curl http://localhost:8470/api/v1/statistics/enhanced

# List available servers
curl http://localhost:8470/api/v1/servers

# Download CSV
curl http://localhost:8470/api/v1/export/csv > results.csv

# System status
curl http://localhost:8470/api/v1/status

# Smart scheduler status
curl http://localhost:8470/api/v1/smart-scheduler/status

# Root-cause analysis
curl http://localhost:8470/api/v1/root-cause/analysis

Home Assistant

Gonzales integrates with Home Assistant in three ways:

Option A: Home Assistant Add-on (recommended for HA OS/Supervised)

One-click installation that runs Gonzales entirely inside Home Assistant as a Docker container. The web dashboard is accessible via the HA sidebar (Ingress). Database and config are persisted across updates.

1. In HA go to Settings > Apps > App Store (three-dot menu) > Repositories
2. Add https://github.com/akustikrausch/gonzales-ha
3. Install Gonzales Speed Monitor and start it
4. The sensor integration is auto-discovered -- confirm setup when prompted

Option B: HACS Integration (for standalone Gonzales)

Install the integration via HACS to connect Home Assistant to a Gonzales server running on a separate device (Docker, Raspberry Pi, bare metal). Gonzales is part of the HACS Default repository -- no custom repository URL needed.

1. Open HACS > Integrations, search for Gonzales, and install
2. Go to Settings > Devices & Services > Add Integration
3. Search for Gonzales and enter host, port, and API key

Option C: Manual Integration

Copy custom_components/gonzales/ from the gonzales-integration repository to your HA config directory.

Sensors (all options):

• sensor.gonzales_download_speed -- latest download speed (Mbit/s)
• sensor.gonzales_upload_speed -- latest upload speed (Mbit/s)
• sensor.gonzales_ping_latency -- latest ping latency (ms)
• sensor.gonzales_ping_jitter -- latest ping jitter (ms)
• sensor.gonzales_packet_loss -- latest packet loss (%)
• sensor.gonzales_last_test_time -- timestamp of last test
• sensor.gonzales_isp_score -- ISP performance score (0-100)
• sensor.gonzales_network_health -- root-cause network health score (0-100)
• sensor.gonzales_smart_scheduler_phase -- current scheduler phase (normal/burst/recovery)
• sensor.gonzales_stability_score -- network stability score (0-100%)
• Diagnostic: scheduler status, test in progress, uptime, total measurements, DB size

Button (all options):

• button.gonzales_run_speed_test -- manually trigger a speed test from HA

Deutsch

Gonzales Ecosystem

Gonzales besteht aus drei Repositories. Welche du brauchst, haengt von deinem Setup ab:

Add-on Nutzer brauchen die HACS-Integration nicht -- das Add-on bringt sie automatisch mit.

Professionelle Internet-Überwachung für volle Transparenz. Gonzales führt rund um die Uhr automatisierte Speedtests durch und baut eine umfassende Performance-Datenbank auf. Wisse genau, was deine Verbindung leistet — mit objektiven Daten, historischen Trends und detaillierten Analysen.

Warum Gonzales?

Transparenz & Dokumentation — Kontinuierliches Monitoring erstellt eine objektive Aufzeichnung deiner Internet-Performance. Verstehe Muster, erkenne Probleme frühzeitig und habe datengestützte Dokumentation, wenn du sie brauchst.

Umfassende Analysen — Echtzeit-Dashboard mit historischen Trends, stündlichen/täglichen/wöchentlichen Aufschlüsselungen, Server-Vergleichen, SLA-Compliance-Tracking und 7-Tage-Vorhersagen.

Home Assistant Integration — Ein-Klick-Add-on-Installation mit 10 Sensoren + Diagnose-Entities. Erstelle Automationen basierend auf Verbindungsqualität — Benachrichtigungen, Smart-Device-Steuerung, Multi-WAN-Failover.

100% Lokal & Privat — Alle Daten bleiben auf deiner Hardware. Keine Cloud-Konten, keine Abos, keine externen Abhängigkeiten. Selbst gehostet und vollständig offline-fähig.

Entwicklerfreundlich — REST API mit OpenAPI-Docs, SSE-Streaming für Echtzeit-Updates, MCP-Server für KI-Assistenten, CLI mit JSON-Ausgabe für Scripting.

Kernfunktionen

Schnellstart

Du brauchst drei Dinge auf deinem System:

• Python 3.10+ -- python.org
• Node.js 18+ -- nodejs.org
• Ookla Speedtest CLI -- speedtest.net/apps/cli

Auf Debian/Ubuntu installierst du die Speedtest CLI so:

sudo apt-get install curl
curl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash
sudo apt-get install speedtest

Dann diese vier Befehle ausfuehren:

cd gonzales
make install
make build
make run

Das Web-Dashboard laeuft jetzt unter http://localhost:8470 -- einfach im Browser oeffnen.

Erweitert

Installation ohne Make

Falls make nicht vorhanden ist:

# Backend installieren
cd backend
pip install -e .

# Frontend installieren und bauen
cd ../frontend
npm install
npm run build

# Gebautes Frontend ins Backend kopieren
cp -r dist ../backend/gonzales/static

# Server starten
cd ../backend
python3 -m gonzales

Terminal-Oberflaeche

Gonzales hat auch eine Demoscene-Terminal-Oberflaeche:

make tui

Tasten: D Dashboard, H Verlauf, S Einstellungen, T Test starten, Q Beenden

Frontend-Entwicklung

Fuer Hot-Reloading bei der Frontend-Entwicklung zwei Terminals starten:

# Terminal 1: Backend
make run

# Terminal 2: Vite Dev-Server
make frontend-dev

Der Vite Dev-Server laeuft unter http://localhost:5173 und leitet API-Anfragen an das Backend weiter.

Konfiguration

.env.example nach .env kopieren und Werte anpassen:

cp .env.example .env

Einstellungen koennen auch zur Laufzeit ueber die Web-Oberflaeche (Einstellungen) oder die API (PUT /api/v1/config) geaendert werden. Laufzeitaenderungen werden in config.json gespeichert (wird automatisch erstellt, nicht in Git).

Home Assistant

Gonzales laesst sich auf drei Arten mit Home Assistant verbinden:

Option A: Home Assistant Add-on (empfohlen fuer HA OS/Supervised)

Ein-Klick-Installation, die Gonzales komplett in Home Assistant als Docker-Container ausfuehrt. Das Web-Dashboard ist ueber die HA-Sidebar (Ingress) erreichbar. Datenbank und Config bleiben bei Updates erhalten.

1. In HA zu Einstellungen > Apps > App Store (Drei-Punkte-Menue) > Repositories
2. https://github.com/akustikrausch/gonzales-ha hinzufuegen
3. Gonzales Speed Monitor installieren und starten
4. Die Sensor-Integration wird automatisch erkannt -- Einrichtung bestaetigen

Option B: HACS Integration (fuer Standalone-Gonzales)

Die Integration ueber HACS installieren, um Home Assistant mit einem Gonzales-Server zu verbinden, der auf einem separaten Geraet laeuft (Docker, Raspberry Pi, Bare Metal). Gonzales ist im HACS Default Repository enthalten -- keine Custom Repository URL noetig.

1. HACS > Integrations oeffnen, nach Gonzales suchen und installieren
2. Zu Einstellungen > Geraete & Dienste > Integration hinzufuegen
3. Nach Gonzales suchen und Host, Port und API-Key eingeben

Option C: Manuelle Integration

custom_components/gonzales/ aus dem gonzales-integration Repository ins HA Config-Verzeichnis kopieren.

Sensoren (alle Optionen): Download-Geschwindigkeit, Upload-Geschwindigkeit, Ping-Latenz, Ping-Jitter, Paketverlust, Letzter Test, ISP-Score, Netzwerk-Gesundheit, Smart-Scheduler-Phase, Stabilitaets-Score. Zusaetzlich Diagnose-Sensoren fuer Scheduler-Status, laufende Tests, Uptime, Gesamtmessungen und Datenbankgroesse.

Button (alle Optionen): button.gonzales_run_speed_test -- manuell einen Speedtest aus HA starten.

CLI-Befehle

Gonzales enthaelt eine umfassende CLI fuer Scripting und Automatisierung:

# Speedtest starten
gonzales run

# Statistiken anzeigen
gonzales stats

# Smart Scheduler Befehle
gonzales smart-scheduler status    # Phase, Stabilitaet, Datenverbrauch
gonzales smart-scheduler enable    # Adaptives Scheduling aktivieren
gonzales smart-scheduler disable   # Adaptives Scheduling deaktivieren

# Ursachenanalyse Befehle
gonzales root-cause analyze        # Vollstaendige Netzwerk-Gesundheitsanalyse
gonzales root-cause fingerprints   # Erkannte Problemmuster
gonzales root-cause recommendations # Umsetzbare Empfehlungen

Ueberpruefen

# Manuellen Speedtest starten
curl -X POST http://localhost:8470/api/v1/speedtest/trigger

# Letztes Ergebnis abrufen
curl http://localhost:8470/api/v1/measurements/latest

# Erweiterte Statistiken
curl http://localhost:8470/api/v1/statistics/enhanced

# Verfuegbare Server auflisten
curl http://localhost:8470/api/v1/servers

# CSV herunterladen
curl http://localhost:8470/api/v1/export/csv > ergebnisse.csv

# Systemstatus
curl http://localhost:8470/api/v1/status

# Smart Scheduler Status
curl http://localhost:8470/api/v1/smart-scheduler/status

# Ursachenanalyse
curl http://localhost:8470/api/v1/root-cause/analysis

Runtime Files (not in Git)

The following files are created automatically at runtime and are excluded from version control via .gitignore:

After a fresh clone, simply run make install && make build && make run. All runtime files are created automatically on first startup. To customize settings before first run, copy the template files:

cp .env.example .env          # Environment variables
cp config.json.example config.json  # Runtime settings (optional)

Tech Stack

Security

API Key Protection

By default, the API is open (no authentication required). This is safe when binding to 127.0.0.1 (localhost only).

If you expose Gonzales on the network (e.g., by setting GONZALES_HOST=0.0.0.0 for Home Assistant or remote access), you must set an API key:

export GONZALES_API_KEY="your-secret-key-here"

Without an API key, anyone on your network can trigger speed tests, change configuration, and delete measurements. Gonzales will print a warning at startup if it detects network binding without an API key.

When set, all mutating endpoints (config update, speedtest trigger, measurement delete) require the X-API-Key header:

curl -X POST http://localhost:8470/api/v1/speedtest/trigger -H "X-API-Key: your-secret-key-here"

Read-only endpoints (measurements, statistics, status, export) remain open.

Rate Limiting

Gonzales includes two layers of rate limiting to prevent abuse:

1. slowapi (per-endpoint): Default 100 requests/minute per IP. Specific endpoints have custom limits (e.g., speedtest trigger: 5/min, exports: 10/min, config updates: 20/min, reads: 200/min).
2. Middleware (global): 120 requests/minute sustained (burst of 20) per IP. Resource-intensive endpoints (/speedtest/trigger, /root-cause/analysis, /export/*, /topology/analyze) limited to 6 requests/minute.

The middleware layer is only active when binding to a non-localhost address (host != 127.0.0.1) and debug mode is off. HTTP 429 (Too Many Requests) is returned when limits are exceeded.

For production deployments, consider placing Gonzales behind a reverse proxy (nginx, Caddy) for TLS and additional access control.

License

MIT -- see LICENSE for details.

Important: Gonzales requires the Ookla Speedtest CLI as a runtime dependency. The Ookla Speedtest CLI is proprietary software licensed under a separate EULA:

• Personal, non-commercial use: Permitted (free of charge)
• Commercial use: Requires a separate license from Ookla
• Redistribution: Not permitted -- users must install it independently

Gonzales itself (this repository) is MIT-licensed. All other dependencies are permissively licensed (MIT/BSD/Apache-2.0).