{"id":35211131,"url":"https://github.com/m4r1k/eneru","last_synced_at":"2026-05-10T23:18:22.809Z","repository":{"id":329158396,"uuid":"1080796778","full_name":"m4r1k/Eneru","owner":"m4r1k","description":"⚡ Eneru—Intelligent UPS monitoring daemon for NUT (Network UPS Tools) with configurable multi-system shutdown orchestration, Discord notifications, and enterprise-grade power event handling.","archived":false,"fork":false,"pushed_at":"2026-04-21T12:30:37.000Z","size":7880,"stargazers_count":66,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-21T14:47:04.520Z","etag":null,"topics":["apprise","automation","devops","docker","homelab","infrastructure","kvm","libvirt","linux","monitoring","network-ups-tools","nut","power-management","proxmox","self-hosted","ups","vmware-esxi","xcp-ng"],"latest_commit_sha":null,"homepage":"https://eneru.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/m4r1k.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-21T22:05:40.000Z","updated_at":"2026-04-21T12:17:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/m4r1k/Eneru","commit_stats":null,"previous_names":["m4r1k/eneru"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/m4r1k/Eneru","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m4r1k%2FEneru","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m4r1k%2FEneru/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m4r1k%2FEneru/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m4r1k%2FEneru/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m4r1k","download_url":"https://codeload.github.com/m4r1k/Eneru/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m4r1k%2FEneru/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32230421,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["apprise","automation","devops","docker","homelab","infrastructure","kvm","libvirt","linux","monitoring","network-ups-tools","nut","power-management","proxmox","self-hosted","ups","vmware-esxi","xcp-ng"],"created_at":"2025-12-29T18:25:08.527Z","updated_at":"2026-05-10T23:18:22.803Z","avatar_url":"https://github.com/m4r1k.png","language":"Python","funding_links":["https://buymeacoffee.com/m4r1k"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# ⚡ Eneru\n\n**UPS monitoring and shutdown orchestration for NUT**\n\n\u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-e8e8ed?style=for-the-badge\u0026labelColor=090909\" alt=\"MIT\"\u003e\u003c/a\u003e\n\u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Python-3.9+-e8e8ed?style=for-the-badge\u0026labelColor=090909\" alt=\"Python 3.9+\"\u003e\u003c/a\u003e\n\u003ca href=\"https://codecov.io/gh/m4r1k/Eneru\"\u003e\u003cimg src=\"https://img.shields.io/codecov/c/github/m4r1k/Eneru?style=for-the-badge\u0026labelColor=090909\u0026color=e8e8ed\u0026label=Coverage\" alt=\"Coverage\"\u003e\u003c/a\u003e\n\u003ca href=\"https://eneru.readthedocs.io/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Docs-Read%20The%20Docs-e8e8ed?style=for-the-badge\u0026labelColor=090909\" alt=\"Documentation\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/eneru/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/eneru?style=for-the-badge\u0026labelColor=090909\u0026color=e8e8ed\u0026label=PyPI\" alt=\"PyPI\"\u003e\u003c/a\u003e\n\u003ca href=\"https://buymeacoffee.com/m4r1k\"\u003e\u003cimg src=\"https://img.shields.io/badge/Buy%20Me%20a%20Coffee-FFDD00?style=for-the-badge\u0026labelColor=090909\u0026logo=buymeacoffee\u0026logoColor=e8e8ed\" alt=\"Buy Me a Coffee\"\u003e\u003c/a\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/m4r1k/Eneru/main/docs/images/eneru-diagram.svg\" alt=\"Eneru Architecture\" width=\"600\"\u003e\n\u003c/p\u003e\n\nA Python-based UPS monitoring daemon for [Network UPS Tools (NUT)](https://networkupstools.org/). Monitors one or more UPSes, orchestrates shutdown of VMs, containers, and remote servers during power events, and exposes read-only API, Prometheus, MQTT, and Grafana observability.\n\n[Documentation](https://eneru.readthedocs.io/) •\n[Getting Started](https://eneru.readthedocs.io/latest/getting-started/) •\n[Configuration](https://eneru.readthedocs.io/latest/configuration/) •\n[Changelog](https://eneru.readthedocs.io/latest/changelog/) •\n[Roadmap](https://eneru.readthedocs.io/latest/roadmap/)\n\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/m4r1k/Eneru/main/docs/images/eneru-mon.gif\" alt=\"Eneru Monitor Dashboard\" width=\"400\"\u003e\n\u003c/p\u003e\n\n---\n\n## Why Eneru?\n\nMost UPS shutdown tools handle one machine. If you have more than one, things get complicated fast:\n\n| Challenge | Eneru Solution |\n|-----------|----------------|\n| Multiple UPSes powering different servers | ✅ Multi-UPS monitoring from a single instance |\n| Multiple servers need coordinated shutdown | ✅ Orchestrated multi-server shutdown via SSH |\n| VMs and containers need graceful stop | ✅ Libvirt VM and Docker/Podman container handling |\n| Network mounts hang during power loss | ✅ Timeout-protected unmounting |\n| No visibility during power events | ✅ Real-time TUI dashboard + notifications via 100+ services |\n| Different systems need different commands | ✅ Per-server custom shutdown commands |\n| Hypervisors need VM shutdown before host | ✅ Pre-shutdown actions (Proxmox, ESXi, XCP-ng, libvirt) |\n| Battery estimates are unreliable | ✅ Multi-vector shutdown triggers |\n| Network down during outage | ✅ Non-blocking notifications with persistent retry |\n| Firmware recalibrates battery silently | ✅ Battery anomaly detection and alerts |\n| Need power-quality telemetry | ✅ API, Prometheus, MQTT, Grafana, JSON logs, and SQLite events |\n\n---\n\n## How Eneru is different\n\nNUT's `upsmon` shuts down one machine with two triggers (low battery, forced shutdown). apcupsd does the same for APC hardware. PeaNUT and NUTCase provide dashboards but no shutdown logic. Enterprise tools (Eaton IPM, PowerChute) add virtualization support but are vendor-locked and proprietary.\n\nEneru sits on top of NUT and adds what these tools lack:\n\n- **Orchestrated multi-resource shutdown**, VMs, compose stacks, containers, remote servers, filesystems, and local system in a coordinated sequence\n- **6 independent shutdown triggers**, including depletion rate (computed from observed battery data, not UPS estimates) and extended time on battery. NUT's 2 triggers miss these failure modes\n- **Multi-UPS coordination**, monitor multiple UPSes with per-group triggers and shutdown policies, each with independent failure handling\n- **Battery anomaly detection**, catches firmware recalibrations and battery degradation with vendor-specific jitter filtering (APC, CyberPower, Ubiquiti)\n\nSee the [full comparison](https://eneru.readthedocs.io/latest/#how-eneru-compares) in the documentation.\n\n---\n\n## Use cases\n\nHomelabs, virtualization hosts (Proxmox, ESXi, libvirt), Docker/Podman container hosts, NAS systems (Synology, QNAP, TrueNAS), multi-UPS environments with multiple server groups, and mixed physical/virtual setups.\n\n---\n\n## Quick start\n\n### Installation\n\n**PyPI:**\n```bash\npip install eneru[notifications]\n```\n\n**Debian/Ubuntu:**\n```bash\ncurl -fsSL https://m4r1k.github.io/Eneru/KEY.gpg | sudo gpg --dearmor -o /usr/share/keyrings/eneru.gpg\necho \"deb [arch=all signed-by=/usr/share/keyrings/eneru.gpg] https://m4r1k.github.io/Eneru/deb stable main\" | sudo tee /etc/apt/sources.list.d/eneru.list\nsudo apt update \u0026\u0026 sudo apt install eneru\n```\n\n**RHEL/Fedora:**\n```bash\nsudo dnf install -y epel-release\nsudo curl -o /etc/yum.repos.d/eneru.repo https://m4r1k.github.io/Eneru/rpm/eneru.repo\nsudo dnf install eneru\n```\n\n### Configuration\n\n```bash\n# Edit configuration\nsudo nano /etc/ups-monitor/config.yaml\n\n# Validate and start\neneru validate --config /etc/ups-monitor/config.yaml\nsudo systemctl enable --now eneru.service\n\n# Monitor in real time\neneru monitor --config /etc/ups-monitor/config.yaml\n```\n\n### Single UPS\n\n```yaml\nups:\n  name: \"UPS@192.168.1.100\"\n  display_name: \"Main UPS\"\n\ntriggers:\n  low_battery_threshold: 20\n  critical_runtime_threshold: 600\n\nlocal_shutdown:\n  enabled: true\n```\n\n### Multiple UPSes\n\n```yaml\nups:\n  - name: \"UPS1@192.168.1.10\"\n    display_name: \"Rack A UPS\"\n    is_local: true\n    remote_servers:\n      - name: \"Proxmox Node\"\n        enabled: true\n        host: \"192.168.1.20\"\n        user: \"root\"\n\n  - name: \"UPS2@192.168.1.11\"\n    display_name: \"Rack B UPS\"\n    remote_servers:\n      - name: \"NAS\"\n        enabled: true\n        host: \"192.168.1.30\"\n        user: \"admin\"\n```\n\nSee the [full documentation](https://eneru.readthedocs.io/) for complete configuration options.\n\n---\n\n## Features\n\n- Monitor one or more UPSes from a single instance, each with its own shutdown group\n- Real-time TUI dashboard (`eneru monitor`) with color-coded status\n- Shutdown triggers: battery %, runtime, depletion rate, time on battery, FSD flag\n- Battery anomaly alerts for unexpected charge drops while on line power, with jitter filtering for APC, CyberPower, and Ubiquiti UniFi UPS units\n- Shuts down VMs, containers, remote servers, filesystems, and the local system in order\n- Notifications to 100+ services (Discord, Slack, Telegram, ntfy, email) via [Apprise](https://github.com/caronc/apprise/wiki)\n- Power quality monitoring: voltage, AVR, bypass, overload\n- Read-only API, Prometheus metrics, outbound MQTT, JSON/syslog logs, and Grafana dashboard\n- Dry-run mode for safe testing\n- Comprehensive test suite across multiple Linux distros, with E2E tests against real NUT, SSH, Docker, and libvirt on every commit\n\n---\n\n## Why a systemd daemon? (No Docker)\n\nEneru runs as a systemd daemon, not a container. It shuts down Docker/Podman containers during power events, so running inside a container would mean getting killed during its own shutdown sequence.\n\nSee the [documentation](https://eneru.readthedocs.io/#why-a-systemd-daemon-no-docker) for the full explanation.\n\n---\n\n## The name\n\n\u003cimg src=\"https://raw.githubusercontent.com/m4r1k/Eneru/main/docs/images/eneru.jpg\" alt=\"Eneru from One Piece\" width=\"120\" align=\"right\"\u003e\n\nNamed after [Eneru (エネル)](https://onepiece.fandom.com/wiki/Enel) from *One Piece*, the self-proclaimed God of Skypiea who ate the Goro Goro no Mi (Rumble-Rumble Fruit) and can control electricity. When the power from the grid fails, this tool takes over and shuts everything down safely. *Unlimited power... management!*\n\n---\n\n## Documentation\n\nFull documentation at [eneru.readthedocs.io](https://eneru.readthedocs.io/):\n\n- [Getting Started](https://eneru.readthedocs.io/latest/getting-started/) - installation and basic setup\n- [Configuration](https://eneru.readthedocs.io/latest/configuration/) - full config reference\n- [Shutdown Triggers](https://eneru.readthedocs.io/latest/triggers/) - how shutdown decisions work\n- [Notifications](https://eneru.readthedocs.io/latest/notifications/) - Discord, Slack, Telegram, etc.\n- [Remote Servers](https://eneru.readthedocs.io/latest/remote-servers/) - SSH setup for NAS and other servers\n- [Testing](https://eneru.readthedocs.io/latest/testing/) - testing strategy and coverage\n- [Troubleshooting](https://eneru.readthedocs.io/latest/troubleshooting/) - common issues and solutions\n\n---\n\n## Support the project\n\nEneru is free and MIT-licensed and will stay that way. If it has saved your homelab or rack from a dirty shutdown and you'd like to chip in toward UPS hardware, NUT testing, and the maintainer's coffee budget, [Buy Me a Coffee](https://buymeacoffee.com/m4r1k) — always optional, much appreciated.\n\n---\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm4r1k%2Feneru","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm4r1k%2Feneru","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm4r1k%2Feneru/lists"}