{"id":43556470,"url":"https://github.com/akustikrausch/gonzales","last_synced_at":"2026-06-11T21:00:52.839Z","repository":{"id":336085031,"uuid":"1147896157","full_name":"akustikrausch/gonzales","owner":"akustikrausch","description":"Open-source internet speed monitor and bandwidth checker. Automated 24/7 speed tests with Ookla Speedtest CLI, real-time analytics dashboard, Home Assistant add-on, ISP performance grading, outage detection, and network diagnostics. Self-hosted, private, Raspberry Pi ready.","archived":false,"fork":false,"pushed_at":"2026-03-10T15:42:14.000Z","size":6340,"stargazers_count":14,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-10T21:51:59.362Z","etag":null,"topics":["bandwidth-monitor","fastapi","home-assistant","home-assistant-addon","internet-monitoring","internet-speed","isp-monitor","mcp-server","network-diagnostics","network-monitoring","ookla","python","raspberry-pi","react","self-hosted","speed-checker","speed-monitor","speedtest","sqlite","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/akustikrausch/gonzales","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akustikrausch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-02T10:36:00.000Z","updated_at":"2026-03-10T15:42:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/akustikrausch/gonzales","commit_stats":null,"previous_names":["akustikrausch/gonzales"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/akustikrausch/gonzales","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akustikrausch%2Fgonzales","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akustikrausch%2Fgonzales/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akustikrausch%2Fgonzales/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akustikrausch%2Fgonzales/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akustikrausch","download_url":"https://codeload.github.com/akustikrausch/gonzales/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akustikrausch%2Fgonzales/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34217312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bandwidth-monitor","fastapi","home-assistant","home-assistant-addon","internet-monitoring","internet-speed","isp-monitor","mcp-server","network-diagnostics","network-monitoring","ookla","python","raspberry-pi","react","self-hosted","speed-checker","speed-monitor","speedtest","sqlite","typescript"],"created_at":"2026-02-03T20:21:44.242Z","updated_at":"2026-06-11T21:00:52.821Z","avatar_url":"https://github.com/akustikrausch.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gonzales - Internet Speed Monitor\n\n[![GitHub Release](https://img.shields.io/github/release/akustikrausch/gonzales.svg)](https://github.com/akustikrausch/gonzales/releases)\n[![GitHub Stars](https://img.shields.io/github/stars/akustikrausch/gonzales)](https://github.com/akustikrausch/gonzales)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)\n[![Home Assistant](https://img.shields.io/badge/Home%20Assistant-2024.12+-41bdf5.svg)](https://www.home-assistant.io/)\n[![React 19](https://img.shields.io/badge/React-19-61dafb.svg)](https://react.dev/)\n\n```\n ██████╗  ██████╗ ███╗   ██╗███████╗ █████╗ ██╗     ███████╗███████╗\n██╔════╝ ██╔═══██╗████╗  ██║╚══███╔╝██╔══██╗██║     ██╔════╝██╔════╝\n██║  ███╗██║   ██║██╔██╗ ██║  ███╔╝ ███████║██║     █████╗  ███████╗\n██║   ██║██║   ██║██║╚██╗██║ ███╔╝  ██╔══██║██║     ██╔══╝  ╚════██║\n╚██████╔╝╚██████╔╝██║ ╚████║███████╗██║  ██║███████╗███████╗███████║\n ╚═════╝  ╚═════╝ ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝\n```\n\n**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.\n\n## Why Gonzales?\n\n**Transparency \u0026 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.\n\n**Comprehensive Analytics** — Real-time dashboard with historical trends, hourly/daily/weekly breakdowns, per-server comparisons, SLA compliance tracking, and 7-day predictive forecasts.\n\n**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.\n\n**100% Local \u0026 Private** — All data stays on your hardware. No cloud accounts, no subscriptions, no external dependencies. Self-hosted and fully offline-capable.\n\n**Developer-Friendly** — REST API with OpenAPI docs, SSE streaming for real-time updates, MCP server for AI assistants, CLI with JSON output for scripting.\n\n## Core Features\n\n| Category | Features |\n|----------|----------|\n| **Monitoring** | Scheduled tests (15-240 min), 10,000+ Ookla servers, preferred server pinning, real-time SSE streaming |\n| **Smart Scheduling** | Adaptive intervals, anomaly detection with burst mode, stability analysis, daily data budget (2 GB default), optional schedule randomization for full time-of-day coverage |\n| **Analytics** | Hourly/daily/weekly stats, per-server comparison, SLA compliance, reliability metrics, trend prediction |\n| **Root-Cause Analysis** | Network health scoring, multi-layer diagnostics (DNS/Local/ISP), hop-speed correlation, actionable recommendations |\n| **Quality Analysis** | ISP grading (A+ to F), QoS profiles (gaming/streaming/video calls), network topology, latency analysis |\n| **Detection** | Outage detection (3-strike retry), jitter monitoring, packet loss tracking, performance degradation alerts |\n| **Export** | CSV export, PDF reports with charts, API access, data retention controls |\n| **Interfaces** | Web dashboard (React 19), Terminal UI (Textual), CLI (Typer), REST API, MCP server |\n| **Integration** | Home Assistant add-on, HACS integration, 10 sensors + diagnostics, button entity |\n| **Security** | API key protection, dual rate limiting (100 req/min slowapi default + 120 req/min middleware), CORS configuration, localhost-only by default |\n| **Accessibility** | WCAG 2.1 AA compliant, keyboard navigation, screen reader support, focus management |\n| **Architecture** | Clean Architecture, Domain-Driven Design, async SQLAlchemy, SQLite with WAL mode |\n\n---\n\n## Gonzales Ecosystem\n\nGonzales consists of three repositories. Which ones you need depends on your setup:\n\n| Repository | What it is | You need this if... |\n|-----------|------------|---------------------|\n| **[gonzales](https://github.com/akustikrausch/gonzales)** | Backend, Web Dashboard, TUI, CLI, API, MCP Server | You run Gonzales standalone (Docker, Raspberry Pi, bare metal) |\n| **[gonzales-ha](https://github.com/akustikrausch/gonzales-ha)** | Home Assistant Add-on (App) | You use HA OS/Supervised and want one-click installation |\n| **[gonzales-integration](https://github.com/akustikrausch/gonzales-integration)** | Home Assistant Integration (HACS Default) | You run Gonzales standalone AND want HA sensors |\n\n\u003e **Add-on users** don't need the HACS integration -- the add-on bundles it automatically.\n\n---\n\n## English\n\n### Getting Started\n\nYou need three things installed on your system:\n\n- **Python 3.10+** -- [python.org](https://www.python.org/downloads/)\n- **Node.js 18+** -- [nodejs.org](https://nodejs.org/)\n- **Ookla Speedtest CLI** -- [speedtest.net/apps/cli](https://www.speedtest.net/apps/cli)\n\nOn Debian/Ubuntu, install the Speedtest CLI like this:\n\n```bash\nsudo apt-get install curl\ncurl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash\nsudo apt-get install speedtest\n```\n\nThen run these four commands:\n\n```bash\ncd gonzales\nmake install\nmake build\nmake run\n```\n\nThe web dashboard is now running at **http://localhost:8470** -- open it in your browser.\n\n---\n\n### Raspberry Pi (ARM64) Setup\n\nGonzales runs on Raspberry Pi 4/5 (64-bit OS required). All Python dependencies are pure Python or have ARM64 wheels.\n\n```bash\n# Install Speedtest CLI for ARM64\ncurl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash\nsudo apt-get install speedtest\n\n# Install Node.js (ARM64)\ncurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -\nsudo apt-get install -y nodejs\n\n# Clone and run\ngit clone \u003cyour-repo-url\u003e gonzales\ncd gonzales\nmake install\nmake build\nmake run\n```\n\nFor running as a systemd service, create `/etc/systemd/system/gonzales.service`:\n\n```ini\n[Unit]\nDescription=Gonzales Speed Monitor\nAfter=network.target\n\n[Service]\nType=simple\nUser=pi\nWorkingDirectory=/home/pi/gonzales/backend\nExecStart=/usr/bin/python3 -m gonzales\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n```\n\n---\n\n### Advanced\n\n#### Install without Make\n\nIf you don't have `make`, you can install everything manually:\n\n```bash\n# Backend\ncd backend\npip install -e .\n\n# Frontend\ncd ../frontend\nnpm install\nnpm run build\n\n# Copy built frontend into backend\ncp -r dist ../backend/gonzales/static\n\n# Start\ncd ../backend\npython3 -m gonzales\n```\n\n#### Terminal UI\n\nGonzales also has a demoscene-style terminal interface:\n\n```bash\nmake tui\n```\n\nKeybindings: `D` Dashboard, `H` History, `S` Settings, `T` Test Now, `Q` Quit\n\n#### Frontend Development\n\nFor hot-reloading during frontend work, run two terminals:\n\n```bash\n# Terminal 1: Backend\nmake run\n\n# Terminal 2: Vite dev server\nmake frontend-dev\n```\n\nThe Vite dev server runs at `http://localhost:5173` and proxies API calls to the backend.\n\n#### Configuration\n\nCopy `.env.example` to `.env` and adjust values:\n\n```bash\ncp .env.example .env\n```\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `GONZALES_HOST` | `127.0.0.1` | Bind address |\n| `GONZALES_PORT` | `8470` | Server port |\n| `GONZALES_TEST_INTERVAL_MINUTES` | `60` | Minutes between tests (overridden to 30 in `.env.example`) |\n| `GONZALES_MANUAL_TRIGGER_COOLDOWN_SECONDS` | `60` | Cooldown between manual tests |\n| `GONZALES_SPEEDTEST_BINARY` | `speedtest` | Path to speedtest CLI binary |\n| `GONZALES_DOWNLOAD_THRESHOLD_MBPS` | `1000.0` | Expected download speed (your subscribed plan) |\n| `GONZALES_UPLOAD_THRESHOLD_MBPS` | `500.0` | Expected upload speed (your subscribed plan) |\n| `GONZALES_TOLERANCE_PERCENT` | `15.0` | Acceptable deviation from threshold (15% = 85% of subscribed speed is OK) |\n| `GONZALES_DB_PATH` | `gonzales.db` | SQLite database file path |\n| `GONZALES_CORS_ORIGINS` | `localhost:5173,8470` | Allowed CORS origins (JSON array) |\n| `GONZALES_LOG_LEVEL` | `INFO` | Logging level |\n| `GONZALES_DEBUG` | `false` | Enable API docs at /docs |\n| `GONZALES_PREFERRED_SERVER_ID` | `0` | Preferred speedtest server (0 = auto) |\n| `GONZALES_API_KEY` | *(empty)* | API key for mutating endpoints. **Required when host != 127.0.0.1** |\n| `GONZALES_THEME` | `auto` | UI theme: auto, light, or dark |\n| `GONZALES_CONFIG_PATH` | `config.json` | Path to runtime config file |\n| `GONZALES_HA_ADDON` | `false` | Enable Home Assistant Add-on mode (Ingress headers, stdout-only logging) |\n| `GONZALES_ISP_NAME` | *(empty)* | Provider name for reports |\n| `GONZALES_DATA_RETENTION_DAYS` | `0` | Delete data older than N days (0 = unlimited) |\n| `GONZALES_WEBHOOK_URL` | *(empty)* | Webhook URL for notifications (empty = disabled) |\n| `GONZALES_SCHEDULER_RANDOMIZE` | `false` | Add random jitter to test intervals for full time-of-day coverage (25% of interval, capped at 30 min) |\n\nSettings 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.\n\n#### In-App Documentation\n\nThe 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.\n\n#### Theme Support\n\nGonzales supports three theme modes:\n\n- **Auto** -- follows your system/browser preference (light or dark)\n- **Light** -- always light mode\n- **Dark** -- always dark mode\n\nChange the theme in Settings \u003e Appearance, or set `GONZALES_THEME` in your `.env` file.\n\n#### API Endpoints\n\nAll under `/api/v1`:\n\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/measurements` | Paginated list |\n| GET | `/measurements/latest` | Most recent result |\n| GET | `/measurements/{id}` | Single measurement |\n| DELETE | `/measurements/{id}` | Delete measurement |\n| DELETE | `/measurements/all` | Delete all measurements (requires `?confirm=true`) |\n| GET | `/statistics` | Aggregates and percentiles |\n| GET | `/statistics/enhanced` | Enhanced stats (hourly, daily, trend, SLA, reliability, per-server) |\n| GET | `/summary` | AI-friendly status summary (supports `?format=markdown`) |\n| GET | `/status` | Scheduler state, uptime |\n| PUT | `/status/scheduler` | Enable/disable the scheduler |\n| GET | `/export/csv` | Download CSV |\n| GET | `/export/pdf` | Download PDF report |\n| GET | `/export/report/professional` | Professional compliance report (PDF) |\n| POST | `/speedtest/trigger` | Run test manually |\n| GET | `/speedtest/stream` | SSE stream for real-time test progress |\n| GET | `/config` | Current config |\n| PUT | `/config` | Update config |\n| GET | `/servers` | List available speedtest servers |\n| GET | `/outages` | List detected outages |\n| GET | `/outages/statistics` | Aggregated outage statistics |\n| GET | `/qos/profiles` | All QoS profiles with requirements |\n| GET | `/qos/current` | QoS status for latest measurement |\n| GET | `/qos/evaluate/{id}` | Evaluate a measurement against QoS profiles |\n| GET | `/qos/history/{profile_id}` | QoS compliance history for a profile |\n| POST | `/topology/analyze` | Run traceroute analysis |\n| GET | `/topology/latest` | Most recent topology analysis |\n| GET | `/topology/history` | Recent topology analyses |\n| GET | `/topology/diagnosis` | Aggregated network diagnosis |\n| GET | `/topology/{id}` | Specific topology analysis |\n| GET | `/smart-scheduler/status` | Smart scheduler status (phase, stability, data usage) |\n| GET/PUT | `/smart-scheduler/config` | Smart scheduler configuration |\n| POST | `/smart-scheduler/enable` | Enable smart scheduling |\n| POST | `/smart-scheduler/disable` | Disable smart scheduling |\n| GET/POST | `/root-cause/analysis` | Full root-cause analysis with recommendations |\n\n#### AI Agent Integration\n\nGonzales supports integration with AI assistants like Claude Desktop via the Model Context Protocol (MCP).\n\n**MCP Server (for Claude Desktop)**\n\nAdd to `~/.config/claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gonzales\": {\n      \"command\": \"gonzales-mcp\"\n    }\n  }\n}\n```\n\nAvailable tools: `get_latest_speedtest`, `run_speedtest`, `get_statistics`, `get_connection_status`, `get_outages`, `get_isp_score`, `get_summary`\n\n**Summary API (for LLMs)**\n\n```bash\n# JSON format\ncurl http://localhost:8470/api/v1/summary\n\n# Markdown format (ideal for LLM context)\ncurl \"http://localhost:8470/api/v1/summary?format=markdown\"\n```\n\nSee [AGENTS.md](AGENTS.md) for complete AI agent documentation.\n\n#### Real-time Test Streaming\n\nThe `/api/v1/speedtest/stream` endpoint provides Server-Sent Events (SSE) during speed tests:\n\n```\nevent: started\ndata: {\"phase\": \"started\"}\n\nevent: progress\ndata: {\"phase\": \"download\", \"bandwidth_mbps\": 450.5, \"progress\": 0.65}\n\nevent: complete\ndata: {\"phase\": \"complete\", \"download_mbps\": 500.2, \"upload_mbps\": 250.1, \"ping_ms\": 12.3}\n```\n\n#### CLI Commands\n\nGonzales includes a comprehensive CLI for scripting and automation:\n\n```bash\n# Run a speed test\ngonzales run\n\n# View statistics\ngonzales stats\n\n# Smart Scheduler commands\ngonzales smart-scheduler status    # View scheduler phase, stability, data usage\ngonzales smart-scheduler enable    # Enable adaptive scheduling\ngonzales smart-scheduler disable   # Disable adaptive scheduling\ngonzales smart-scheduler config    # View/update scheduler configuration\n\n# Root-Cause Analysis commands\ngonzales root-cause analyze        # Full network health analysis\ngonzales root-cause fingerprints   # View detected problem patterns\ngonzales root-cause recommendations # Get actionable recommendations\ngonzales root-cause hops           # View hop-speed correlations\n```\n\n#### Verification\n\n```bash\n# Manual speed test\ncurl -X POST http://localhost:8470/api/v1/speedtest/trigger\n\n# Check latest result\ncurl http://localhost:8470/api/v1/measurements/latest\n\n# Enhanced statistics\ncurl http://localhost:8470/api/v1/statistics/enhanced\n\n# List available servers\ncurl http://localhost:8470/api/v1/servers\n\n# Download CSV\ncurl http://localhost:8470/api/v1/export/csv \u003e results.csv\n\n# System status\ncurl http://localhost:8470/api/v1/status\n\n# Smart scheduler status\ncurl http://localhost:8470/api/v1/smart-scheduler/status\n\n# Root-cause analysis\ncurl http://localhost:8470/api/v1/root-cause/analysis\n```\n\n#### Home Assistant\n\nGonzales integrates with Home Assistant in three ways:\n\n**Option A: Home Assistant Add-on (recommended for HA OS/Supervised)**\n\nOne-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.\n\n[![Add Repository to Home Assistant](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fakustikrausch%2Fgonzales-ha)\n\n1. In HA go to **Settings \u003e Apps \u003e App Store** (three-dot menu) \u003e **Repositories**\n2. Add `https://github.com/akustikrausch/gonzales-ha`\n3. Install **Gonzales Speed Monitor** and start it\n4. The sensor integration is auto-discovered -- confirm setup when prompted\n\n**Option B: HACS Integration (for standalone Gonzales)**\n\nInstall 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.\n\n1. Open **HACS \u003e Integrations**, search for **Gonzales**, and install\n2. Go to **Settings \u003e Devices \u0026 Services \u003e Add Integration**\n3. Search for **Gonzales** and enter host, port, and API key\n\n**Option C: Manual Integration**\n\nCopy `custom_components/gonzales/` from the [gonzales-integration](https://github.com/akustikrausch/gonzales-integration) repository to your HA config directory.\n\n**Sensors** (all options):\n- `sensor.gonzales_download_speed` -- latest download speed (Mbit/s)\n- `sensor.gonzales_upload_speed` -- latest upload speed (Mbit/s)\n- `sensor.gonzales_ping_latency` -- latest ping latency (ms)\n- `sensor.gonzales_ping_jitter` -- latest ping jitter (ms)\n- `sensor.gonzales_packet_loss` -- latest packet loss (%)\n- `sensor.gonzales_last_test_time` -- timestamp of last test\n- `sensor.gonzales_isp_score` -- ISP performance score (0-100)\n- `sensor.gonzales_network_health` -- root-cause network health score (0-100)\n- `sensor.gonzales_smart_scheduler_phase` -- current scheduler phase (normal/burst/recovery)\n- `sensor.gonzales_stability_score` -- network stability score (0-100%)\n- Diagnostic: scheduler status, test in progress, uptime, total measurements, DB size\n\n**Button** (all options):\n- `button.gonzales_run_speed_test` -- manually trigger a speed test from HA\n\n---\n\n## Deutsch\n\n### Gonzales Ecosystem\n\nGonzales besteht aus drei Repositories. Welche du brauchst, haengt von deinem Setup ab:\n\n| Repository | Was es ist | Du brauchst das wenn... |\n|-----------|------------|------------------------|\n| **[gonzales](https://github.com/akustikrausch/gonzales)** | Backend, Web Dashboard, TUI, CLI, API, MCP Server | Du Gonzales standalone betreibst (Docker, Raspberry Pi, Bare Metal) |\n| **[gonzales-ha](https://github.com/akustikrausch/gonzales-ha)** | Home Assistant Add-on (App) | Du HA OS/Supervised nutzt und Ein-Klick-Installation willst |\n| **[gonzales-integration](https://github.com/akustikrausch/gonzales-integration)** | Home Assistant Integration (HACS Default) | Du Gonzales standalone betreibst UND HA-Sensoren willst |\n\n\u003e **Add-on Nutzer** brauchen die HACS-Integration nicht -- das Add-on bringt sie automatisch mit.\n\n---\n\n**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.\n\n### Warum Gonzales?\n\n**Transparenz \u0026 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.\n\n**Umfassende Analysen** — Echtzeit-Dashboard mit historischen Trends, stündlichen/täglichen/wöchentlichen Aufschlüsselungen, Server-Vergleichen, SLA-Compliance-Tracking und 7-Tage-Vorhersagen.\n\n**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.\n\n**100% Lokal \u0026 Privat** — Alle Daten bleiben auf deiner Hardware. Keine Cloud-Konten, keine Abos, keine externen Abhängigkeiten. Selbst gehostet und vollständig offline-fähig.\n\n**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.\n\n### Kernfunktionen\n\n| Kategorie | Funktionen |\n|-----------|------------|\n| **Monitoring** | Geplante Tests (15-240 Min), 10.000+ Ookla-Server, Server-Pinning, Echtzeit-SSE-Streaming |\n| **Smart Scheduling** | Adaptive Intervalle, Anomalie-Erkennung mit Burst-Modus, Stabilitätsanalyse, tägliches Datenbudget (2 GB Standard) |\n| **Analysen** | Stündliche/tägliche/wöchentliche Stats, Server-Vergleich, SLA-Compliance, Zuverlässigkeitsmetriken, Trend-Vorhersage |\n| **Ursachenanalyse** | Netzwerk-Gesundheitsbewertung, Multi-Layer-Diagnose (DNS/Lokal/ISP), Hop-Korrelation, umsetzbare Empfehlungen |\n| **Qualitätsanalyse** | ISP-Bewertung (A+ bis F), QoS-Profile (Gaming/Streaming/Videoanrufe), Netzwerk-Topologie, Latenzanalyse |\n| **Erkennung** | Ausfallerkennung (3-Strike-Retry), Jitter-Monitoring, Paketverlust-Tracking, Performance-Degradation-Alerts |\n| **Export** | CSV-Export, PDF-Berichte mit Diagrammen, API-Zugriff, Datenaufbewahrungskontrolle |\n| **Oberflächen** | Web-Dashboard (React 19), Terminal UI (Textual), CLI (Typer), REST API, MCP-Server |\n| **Integration** | Home Assistant Add-on, HACS-Integration, 10 Sensoren + Diagnose-Entities, Button-Entity |\n| **Sicherheit** | API-Key-Schutz, duales Rate-Limiting (100 Req/Min slowapi-Standard + 120 Req/Min Middleware), CORS-Konfiguration, standardmäßig nur localhost |\n| **Barrierefreiheit** | WCAG 2.1 AA konform, Tastaturnavigation, Screenreader-Unterstützung, Fokus-Management |\n| **Architektur** | Clean Architecture, Domain-Driven Design, async SQLAlchemy, SQLite mit WAL-Modus |\n\n---\n\n### Schnellstart\n\nDu brauchst drei Dinge auf deinem System:\n\n- **Python 3.10+** -- [python.org](https://www.python.org/downloads/)\n- **Node.js 18+** -- [nodejs.org](https://nodejs.org/)\n- **Ookla Speedtest CLI** -- [speedtest.net/apps/cli](https://www.speedtest.net/apps/cli)\n\nAuf Debian/Ubuntu installierst du die Speedtest CLI so:\n\n```bash\nsudo apt-get install curl\ncurl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash\nsudo apt-get install speedtest\n```\n\nDann diese vier Befehle ausfuehren:\n\n```bash\ncd gonzales\nmake install\nmake build\nmake run\n```\n\nDas Web-Dashboard laeuft jetzt unter **http://localhost:8470** -- einfach im Browser oeffnen.\n\n---\n\n### Erweitert\n\n#### Installation ohne Make\n\nFalls `make` nicht vorhanden ist:\n\n```bash\n# Backend installieren\ncd backend\npip install -e .\n\n# Frontend installieren und bauen\ncd ../frontend\nnpm install\nnpm run build\n\n# Gebautes Frontend ins Backend kopieren\ncp -r dist ../backend/gonzales/static\n\n# Server starten\ncd ../backend\npython3 -m gonzales\n```\n\n#### Terminal-Oberflaeche\n\nGonzales hat auch eine Demoscene-Terminal-Oberflaeche:\n\n```bash\nmake tui\n```\n\nTasten: `D` Dashboard, `H` Verlauf, `S` Einstellungen, `T` Test starten, `Q` Beenden\n\n#### Frontend-Entwicklung\n\nFuer Hot-Reloading bei der Frontend-Entwicklung zwei Terminals starten:\n\n```bash\n# Terminal 1: Backend\nmake run\n\n# Terminal 2: Vite Dev-Server\nmake frontend-dev\n```\n\nDer Vite Dev-Server laeuft unter `http://localhost:5173` und leitet API-Anfragen an das Backend weiter.\n\n#### Konfiguration\n\n`.env.example` nach `.env` kopieren und Werte anpassen:\n\n```bash\ncp .env.example .env\n```\n\n| Variable | Standard | Beschreibung |\n|----------|----------|--------------|\n| `GONZALES_HOST` | `127.0.0.1` | Bind-Adresse |\n| `GONZALES_PORT` | `8470` | Server-Port |\n| `GONZALES_TEST_INTERVAL_MINUTES` | `60` | Minuten zwischen Tests (in `.env.example` auf 30 gesetzt) |\n| `GONZALES_MANUAL_TRIGGER_COOLDOWN_SECONDS` | `60` | Abklingzeit zwischen manuellen Tests |\n| `GONZALES_SPEEDTEST_BINARY` | `speedtest` | Pfad zur Speedtest-CLI |\n| `GONZALES_DOWNLOAD_THRESHOLD_MBPS` | `1000.0` | Erwartete Download-Geschwindigkeit (dein Tarif) |\n| `GONZALES_UPLOAD_THRESHOLD_MBPS` | `500.0` | Erwartete Upload-Geschwindigkeit (dein Tarif) |\n| `GONZALES_TOLERANCE_PERCENT` | `15.0` | Akzeptable Abweichung vom Schwellwert (15% = 85% der Vertragsgeschwindigkeit OK) |\n| `GONZALES_DB_PATH` | `gonzales.db` | SQLite-Datenbankdatei |\n| `GONZALES_CORS_ORIGINS` | `localhost:5173,8470` | Erlaubte CORS-Origins (JSON-Array) |\n| `GONZALES_LOG_LEVEL` | `INFO` | Log-Level |\n| `GONZALES_DEBUG` | `false` | API-Docs unter /docs aktivieren |\n| `GONZALES_PREFERRED_SERVER_ID` | `0` | Bevorzugter Speedtest-Server (0 = automatisch) |\n| `GONZALES_API_KEY` | *(leer)* | API-Key fuer schreibende Endpoints. **Pflicht wenn Host != 127.0.0.1** |\n| `GONZALES_THEME` | `auto` | UI-Thema: auto, light oder dark |\n| `GONZALES_CONFIG_PATH` | `config.json` | Pfad zur Laufzeit-Konfigurationsdatei |\n| `GONZALES_HA_ADDON` | `false` | Home Assistant Add-on Modus (Ingress-Header, nur stdout-Logging) |\n| `GONZALES_ISP_NAME` | *(leer)* | Provider-Name fuer Berichte |\n| `GONZALES_DATA_RETENTION_DAYS` | `0` | Daten aelter als N Tage loeschen (0 = unbegrenzt) |\n| `GONZALES_WEBHOOK_URL` | *(leer)* | Webhook-URL fuer Benachrichtigungen (leer = deaktiviert) |\n\nEinstellungen 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).\n\n#### Home Assistant\n\nGonzales laesst sich auf drei Arten mit Home Assistant verbinden:\n\n**Option A: Home Assistant Add-on (empfohlen fuer HA OS/Supervised)**\n\nEin-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.\n\n[![Repository zu Home Assistant hinzufuegen](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fakustikrausch%2Fgonzales-ha)\n\n1. In HA zu **Einstellungen \u003e Apps \u003e App Store** (Drei-Punkte-Menue) \u003e **Repositories**\n2. `https://github.com/akustikrausch/gonzales-ha` hinzufuegen\n3. **Gonzales Speed Monitor** installieren und starten\n4. Die Sensor-Integration wird automatisch erkannt -- Einrichtung bestaetigen\n\n**Option B: HACS Integration (fuer Standalone-Gonzales)**\n\nDie 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.\n\n1. **HACS \u003e Integrations** oeffnen, nach **Gonzales** suchen und installieren\n2. Zu **Einstellungen \u003e Geraete \u0026 Dienste \u003e Integration hinzufuegen**\n3. Nach **Gonzales** suchen und Host, Port und API-Key eingeben\n\n**Option C: Manuelle Integration**\n\n`custom_components/gonzales/` aus dem [gonzales-integration](https://github.com/akustikrausch/gonzales-integration) Repository ins HA Config-Verzeichnis kopieren.\n\n**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.\n\n**Button** (alle Optionen): `button.gonzales_run_speed_test` -- manuell einen Speedtest aus HA starten.\n\n#### CLI-Befehle\n\nGonzales enthaelt eine umfassende CLI fuer Scripting und Automatisierung:\n\n```bash\n# Speedtest starten\ngonzales run\n\n# Statistiken anzeigen\ngonzales stats\n\n# Smart Scheduler Befehle\ngonzales smart-scheduler status    # Phase, Stabilitaet, Datenverbrauch\ngonzales smart-scheduler enable    # Adaptives Scheduling aktivieren\ngonzales smart-scheduler disable   # Adaptives Scheduling deaktivieren\n\n# Ursachenanalyse Befehle\ngonzales root-cause analyze        # Vollstaendige Netzwerk-Gesundheitsanalyse\ngonzales root-cause fingerprints   # Erkannte Problemmuster\ngonzales root-cause recommendations # Umsetzbare Empfehlungen\n```\n\n#### Ueberpruefen\n\n```bash\n# Manuellen Speedtest starten\ncurl -X POST http://localhost:8470/api/v1/speedtest/trigger\n\n# Letztes Ergebnis abrufen\ncurl http://localhost:8470/api/v1/measurements/latest\n\n# Erweiterte Statistiken\ncurl http://localhost:8470/api/v1/statistics/enhanced\n\n# Verfuegbare Server auflisten\ncurl http://localhost:8470/api/v1/servers\n\n# CSV herunterladen\ncurl http://localhost:8470/api/v1/export/csv \u003e ergebnisse.csv\n\n# Systemstatus\ncurl http://localhost:8470/api/v1/status\n\n# Smart Scheduler Status\ncurl http://localhost:8470/api/v1/smart-scheduler/status\n\n# Ursachenanalyse\ncurl http://localhost:8470/api/v1/root-cause/analysis\n```\n\n---\n\n## Runtime Files (not in Git)\n\nThe following files are created automatically at runtime and are excluded from version control via `.gitignore`:\n\n| File / Directory | Created by | Purpose |\n|-----------------|------------|---------|\n| `config.json` | Settings API | Persisted runtime config (test interval, thresholds, theme) |\n| `gonzales.db` | Backend startup | SQLite database with all measurements |\n| `gonzales.db-wal` | SQLite WAL mode | Write-ahead log for concurrent access |\n| `backend/logs/gonzales.log` | Logging setup | Application log file |\n| `.env` | User (from `.env.example`) | Environment variable overrides |\n\nAfter a fresh clone, simply run `make install \u0026\u0026 make build \u0026\u0026 make run`. All runtime files are created automatically on first startup. To customize settings before first run, copy the template files:\n\n```bash\ncp .env.example .env          # Environment variables\ncp config.json.example config.json  # Runtime settings (optional)\n```\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|-----------|\n| Backend | Python, FastAPI, SQLAlchemy 2 (async), APScheduler |\n| Architecture | Clean Architecture, Domain-Driven Design |\n| Speed Engine | Ookla Speedtest CLI |\n| Database | SQLite (WAL mode) |\n| Frontend | React 19, TypeScript, Vite 6, Recharts, Tailwind CSS 4, TanStack Query 5 |\n| Design System | Liquid Glass (CSS custom properties, backdrop-filter) |\n| Accessibility | WCAG 2.1 AA compliant |\n| Terminal UI | Textual + Rich |\n| CLI | Typer + Rich |\n| AI Integration | MCP Server (Model Context Protocol) |\n| Export | CSV, PDF (ReportLab) |\n| Home Assistant | [gonzales-ha](https://github.com/akustikrausch/gonzales-ha) (Add-on) + [gonzales-integration](https://github.com/akustikrausch/gonzales-integration) (HACS Default) |\n\n## Security\n\n### API Key Protection\n\nBy default, the API is open (no authentication required). This is safe when binding to `127.0.0.1` (localhost only).\n\n**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**:\n\n```bash\nexport GONZALES_API_KEY=\"your-secret-key-here\"\n```\n\nWithout 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.\n\nWhen set, all mutating endpoints (config update, speedtest trigger, measurement delete) require the `X-API-Key` header:\n\n```bash\ncurl -X POST http://localhost:8470/api/v1/speedtest/trigger -H \"X-API-Key: your-secret-key-here\"\n```\n\nRead-only endpoints (measurements, statistics, status, export) remain open.\n\n### Rate Limiting\n\nGonzales includes two layers of rate limiting to prevent abuse:\n\n1. **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).\n2. **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.\n\nThe 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.\n\nFor production deployments, consider placing Gonzales behind a reverse proxy (nginx, Caddy) for TLS and additional access control.\n\n---\n\n## License\n\nMIT -- see [LICENSE](LICENSE) for details.\n\n**Important:** Gonzales requires the [Ookla Speedtest CLI](https://www.speedtest.net/apps/cli) as a runtime dependency. The Ookla Speedtest CLI is **proprietary software** licensed under a separate [EULA](https://www.speedtest.net/about/eula):\n\n- **Personal, non-commercial use**: Permitted (free of charge)\n- **Commercial use**: Requires a separate license from Ookla\n- **Redistribution**: Not permitted -- users must install it independently\n\nGonzales itself (this repository) is MIT-licensed. All other dependencies are permissively licensed (MIT/BSD/Apache-2.0).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakustikrausch%2Fgonzales","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakustikrausch%2Fgonzales","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakustikrausch%2Fgonzales/lists"}