Installation

Bewitch runs on Linux (amd64 and arm64). It uses procfs and sysfs for metric collection.

Supported Platforms #

Architectures: amd64 and arm64 (Raspberry Pi 4/5, AWS Graviton, etc.)

Quick Install #

The fastest way to install on any Linux distribution:

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

On Debian/Ubuntu, this adds the APT repository, imports the signing key, and installs the package. Updates are handled through apt upgrade.

On other distributions, it downloads a pre-built binary tarball, verifies its signed checksum, installs the binaries to /usr/local/bin/, creates a system user, and sets up and starts the systemd units (bewitchd.service and bewitch-smart.timer).

APT Repository (Debian/Ubuntu) #

To add the repository manually:

# Import signing key
curl -fsSL https://bewitch.dev/gpg | sudo gpg --dearmor -o /usr/share/keyrings/bewitch.gpg

# Add repository
echo "deb [signed-by=/usr/share/keyrings/bewitch.gpg] https://bewitch.dev/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/bewitch.list

# Install
sudo apt update && sudo apt install bewitch

Dev channel #

To track the latest development builds (published on every push to main):

# Replace "stable" with "dev" in the repository line
echo "deb [signed-by=/usr/share/keyrings/bewitch.gpg] https://bewitch.dev/apt dev main" \
  | sudo tee /etc/apt/sources.list.d/bewitch.list

sudo apt update && sudo apt install bewitch

Dev builds use versions like 0.1.3~dev.20260314.abcdef1. The ~ prefix means APT treats them as older than the corresponding release, so switching back to stable and running apt upgrade will move you to the latest release automatically.

Or use the quick install script with the dev channel:

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

Binary Tarball (Any Linux) #

Download and install pre-built binaries directly:

# Download (replace ARCH with amd64 or arm64)
curl -LO https://bewitch.dev/releases/bewitch-0.9.1-linux-${ARCH}.tar.gz
tar xzf bewitch-0.9.1-linux-*.tar.gz

# Install binaries
sudo install -m 755 bewitch-0.9.1-linux-*/bewitchd /usr/local/bin/
sudo install -m 755 bewitch-0.9.1-linux-*/bewitch /usr/local/bin/

# Set up system user, data directory and config (the config holds secrets: keep it 0640)
sudo useradd -r -s /usr/sbin/nologin bewitch
sudo mkdir -p /var/lib/bewitch
sudo chown bewitch:bewitch /var/lib/bewitch
sudo install -m 640 -o root -g bewitch bewitch-0.9.1-linux-*/bewitch.example.toml /etc/bewitch.toml

# Install systemd units (they expect /usr/bin, so point them at /usr/local/bin)
for unit in bewitchd.service bewitch-smart.service bewitch-smart.timer; do
  sed 's#/usr/bin/bewitchd#/usr/local/bin/bewitchd#' bewitch-0.9.1-linux-*/$unit \
    | sudo tee /etc/systemd/system/$unit > /dev/null
done
sudo systemctl daemon-reload
sudo systemctl enable --now bewitchd bewitch-smart.timer

Direct .deb Download #

Download and install the .deb package directly (Debian/Ubuntu only):

# Replace ARCH with amd64 or arm64
curl -LO https://bewitch.dev/apt/pool/main/b/bewitch/bewitch_0.9.1-1_${ARCH}.deb
sudo dpkg -i bewitch_0.9.1-1_*.deb

The .deb package automatically:

• Creates the bewitch system user and group
• Installs binaries to /usr/bin/
• Sets up /var/lib/bewitch/ with correct ownership
• Installs, enables, and starts bewitchd.service, and enables bewitch-smart.timer (the NVMe SMART helper)
• Copies the example config to /etc/bewitch.toml as root:bewitch, mode 0640, if you don't have one already
• Grants the service the capabilities and groups it needs for SMART, power, GPU and per-process I/O

Build from Source #

Requires Go 1.26.9 or newer (as set in go.mod) and a C compiler (for CGO/DuckDB).

git clone https://github.com/duggan/bewitch
cd bewitch
make build
sudo make install          # installs to /usr/bin
sudo useradd -r -s /usr/sbin/nologin bewitch
sudo mkdir -p /var/lib/bewitch
sudo chown bewitch:bewitch /var/lib/bewitch
sudo install -m 640 -o root -g bewitch bewitch.example.toml /etc/bewitch.toml
sudo cp debian/bewitch.bewitchd.service /etc/systemd/system/bewitchd.service
sudo cp debian/bewitch.bewitch-smart.service /etc/systemd/system/bewitch-smart.service
sudo cp debian/bewitch.bewitch-smart.timer /etc/systemd/system/bewitch-smart.timer
sudo systemctl daemon-reload

systemd Service #

The install script and .deb package automatically enable and start the daemon. For build-from-source installs, start it manually:

sudo systemctl enable --now bewitchd bewitch-smart.timer

The service uses RuntimeDirectory=bewitch which creates /run/bewitch/ automatically. The default socket path is /run/bewitch/bewitch.sock. It is world-accessible (0666) so any local user can run the TUI; see the local socket for what that allows.

The service runs as the unprivileged bewitch user in a systemd sandbox. It can only write to /var/lib/bewitch/, and holds only the capabilities its collectors need (CAP_SYS_RAWIO, CAP_PERFMON, CAP_SYS_PTRACE, CAP_BPF).

Service management #

sudo systemctl status bewitchd     # check status
sudo systemctl restart bewitchd    # restart after config changes
sudo journalctl -u bewitchd -f     # follow logs

Optional Dependencies #

The installer detects hardware and offers to install optional monitoring tools. These can also be installed manually:

• smartmontools — enhanced SMART disk health via smartctl (installed automatically on Debian/Ubuntu)
• intel-gpu-tools — Intel iGPU monitoring via intel_gpu_top
• NVIDIA driver — provides nvidia-smi for NVIDIA GPU monitoring

Use BEWITCH_NONINTERACTIVE=1 to auto-install all detected optional dependencies without prompting.

File Locations #

Verify Installation #

# Check the daemon is running
sudo systemctl status bewitchd

# Launch the TUI
bewitch

# Or query the API directly
curl --unix-socket /run/bewitch/bewitch.sock http://localhost/api/status

Uninstall #

Run the uninstall script to remove bewitch, the systemd service, config, data, and system user:

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

On Debian/Ubuntu, this removes the APT package and repository. On other systems, it removes the files installed by the tarball.

To keep the database and archives in /var/lib/bewitch/:

curl -fsSL https://bewitch.dev/uninstall.sh | sudo KEEP_DATA=1 sh