Documentation

bewitch is a monitoring daemon (bewitchd) and a TUI (bewitch) for Linux. It reads /proc and /sys, stores what it finds in DuckDB, and gives you charts, alerts, remote access, and a SQL console over the lot. These pages cover installing it, configuring it, and getting at your data — locally or over TLS.

Architecture🔗

bewitchd (daemon)
├── Collectors (procfs/sysfs, parallel goroutines) → Store (DuckDB)
├── Alert Engine (threshold + predictive + variance → notifications)
├── Pruner / Compactor / Archiver
└── API Server
    ├── Unix socket (always, plain HTTP)
    └── TCP listener (optional, TLS by default)

bewitch (TUI)
└── Daemon Client (unix socket or TCP+TLS)

bewitch repl (SQL console)
└── Daemon Client (POST /api/query)

• Installation
  One-line installer, the Debian APT repo, or prebuilt binaries — plus the systemd unit.
• Configuration
  Every TOML option, what it does, and the defaults you can usually leave alone.
• Collectors
  The nine collectors — CPU, memory, disk, network, ECC, temperature, power, GPU, process — and how to tune their intervals.
• Custom Sources
  Point bewitch at a local service's HTTP API and chart its numbers alongside everything else — no Go required.
• TUI Guide
  Views, keybindings, time-range scrubbing, process pinning, and debug mode.
• Alerts
  Threshold, predictive, and variance rules, delivered by email or shell command.
• SQL REPL
  The SQL console over your own metrics: dot-commands, multi-line editing, tab completion, and export.
• Remote Access
  TLS by default, trust-on-first-use fingerprint pinning, and optional bearer-token auth.
• API Reference
  The HTTP endpoints behind it all — metrics, history, query, export, snapshots, alerts.
• Storage & Archival
  Retention, compaction, Parquet archival, and standalone snapshots for the long haul.
• Changelog
  What changed, version by version.