bewitch

bewitch monitors homelab servers, Raspberry Pis and VPSes. It has two binaries:

• bewitchd, a daemon that collects metrics from /proc, /sys and the hardware, stores them in a local DuckDB database, and evaluates alert rules.
• bewitch, a client with a terminal UI (live views, history charts, hardware health, alerts), a SQL console, and maintenance commands.

Each machine runs its own daemon; there is no central server. The packaged daemon runs as an unprivileged, sandboxed systemd service and caps DuckDB's memory use at 512 MB by default.

Install

curl -fsSL https://bewitch.dev/install.sh | sudo sh

On Debian and Ubuntu this adds the signed APT repository, so updates arrive with apt upgrade. On other distributions it installs a prebuilt binary and a systemd service. Builds are available for amd64 and arm64. See Installation for the manual APT setup, the dev channel, and tarballs.

Use

bewitch                       # the TUI: 1–9 switch views, < > change the time range
bewitch repl                  # SQL over your own metrics
bewitch -addr myhost:9119     # a remote daemon, over TLS with fingerprint pinning

What it does

• System metrics: CPU (per core, including steal), memory, disk space and I/O, network, temperatures, power (Intel/AMD RAPL), GPUs (Intel, NVIDIA, AMD), ECC memory, and every process, with per-process disk and network I/O.
• Disk health: SMART data for SATA, NVMe and ZFS pool disks, stored over time so you can track wear and alert on reallocated sectors, errors or failed health checks.
• History: every sample is stored, and the TUI charts any time range. Optional retention pruning and Parquet archival keep the database small.
• Alerts: threshold, predictive (a disk projected to reach 90% within 48 hours), variance and process rules, created in the TUI. Notifications go to email, a shell command, or Discord, Telegram, ntfy, Slack and other services, with a second notification when an alert resolves. A built-in alert fires if metric collection stops.
• Custom sources: poll Pi-hole, Home Assistant, Docker, Proxmox VE or any JSON HTTP API and chart the values. Sources are configured in TOML.
• SQL and export: a REPL over all stored data, export to CSV, Parquet or JSON, and a Prometheus /metrics endpoint.
• Remote access: the TUI and REPL can connect to a daemon on another machine over TLS, with certificate fingerprint pinning and optional token authentication.

Screenshots

Processes	Hardware
Alerts	Services
CPU	Disk

Documentation

Full documentation is at bewitch.dev/docs:

• Configuration and Collectors
• TUI guide and Alerts
• Custom sources and Running on Proxmox VE
• SQL REPL, Storage & archival and the API
• Remote access

Development

bewitch targets Linux, but builds and runs on macOS too: mock mode generates synthetic data for every view, so you can work on the TUI anywhere. You need Go (see go.mod) and a C toolchain, because DuckDB is linked through cgo.

make build              # bin/bewitchd and bin/bewitch
make test               # unit tests (make test-integration for the DuckDB ones)

To run against mock data, use a config like this:

[daemon]
mock = true
socket = "/tmp/bewitch.sock"
db_path = "/tmp/bewitch.duckdb"

bin/bewitchd -config dev.toml &
bin/bewitch -config dev.toml

CLAUDE.md has detailed architecture notes for contributors.

License

Apache 2.0