Baba

Named after the lookout pirate in the French comic book Astérix, always watching for trouble on the horizon.

Caution

While the app's version is more than 1.x it's still in beta and may contain bugs. It won't impact your system but I can't guarantee it's reliable yet until I have long term data to prove it.

Baba is a lightweight homelab monitor that sends Discord or Telegram alerts when something goes wrong — and tells you when it's fixed.

What it does

• Watches CPU usage, system load, memory, disk, CPU/GPU temperature, and GPU utilization
• Alerts via Discord and/or Telegram (multiple notifiers supported)
• Deduplicates: opens an incident only on the Nth consecutive breach — no per-cycle spam
• Recovery alerts: notifies you when a metric returns to normal
• Reminders: re-alerts at a configurable interval while an incident stays open
• Stores full incident history in a local SQLite database

Quick start

Install script (Linux / macOS)

curl -fsSL https://github.com/orochibraru/baba/releases/latest/download/install.sh | sh

Detects your OS and architecture, installs the binary to /usr/local/bin/baba, creates /var/lib/baba/, and seeds /var/lib/baba/config.json from the default template if one doesn't already exist. Then:

baba setup    # interactive wizard — fill in your notifier credentials and thresholds
baba install  # register as a background service (launchd on macOS, systemd on Linux)

To run in the foreground instead: baba start

To install to a custom location: INSTALL_DIR=~/.local/bin curl -fsSL … | sh

Docker Compose

# 1. Copy and edit config — at minimum, set your notifier webhook URL
curl -o config.json https://raw.githubusercontent.com/orochibraru/baba/main/config.example.json

# 2. Download the compose file
curl -o compose.yaml https://raw.githubusercontent.com/orochibraru/baba/main/compose.example.yaml

# 3. Run
docker compose up -d

Binary (manual)

Download the binary for your platform from the releases page, then:

# 1. Copy and edit config
curl -o config.json https://raw.githubusercontent.com/orochibraru/baba/main/config.example.json

# 2. Run
./baba start

Docker

Docker Compose (recommended)

The included compose.yaml handles all the required flags. Edit config.json, then:

docker compose up -d

docker run

The image has no bundled config — pass it via a volume mount and --config, or configure everything through environment variables.

With a config file:

docker run -d \
  --name baba \
  --restart unless-stopped \
  --privileged --pid=host --network=host \
  -v /sys:/sys:ro \
  -v /dev:/dev:ro \
  -v /path/to/config.json:/config.json:ro \
  -v /path/to/data:/app/tmp \
  orochibraru/baba:latest start --config /config.json

With environment variables only (no config file):

docker run -d \
  --name baba \
  --restart unless-stopped \
  --privileged --pid=host --network=host \
  -v /sys:/sys:ro \
  -v /dev:/dev:ro \
  -v /path/to/data:/app/tmp \
  -e BABA_NOTIFIERS_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/… \
  orochibraru/baba:latest

See the Environment variables section for the full list of BABA_* variables.

Why these flags?

Flag	Reason
--privileged	Full access to hardware sensors (temperature, GPU)
--pid=host	Shares the host PID namespace so /proc reflects host-wide CPU and process stats
--network=host	Network interface stats match the host
-v /sys:/sys:ro	Read-only access to kernel hardware interfaces (hwmon, thermal zones)
-v /dev:/dev:ro	Device access for disk stats
-v …:/app/tmp	Persists the SQLite incident database across restarts

Data directory

All runtime files live in /var/lib/baba/:

File	Purpose
config.json	Active configuration (edit or run baba setup)
config.default.json	Immutable template refreshed on each install — used to restore config.json if it's ever deleted
baba.db	SQLite incident history
baba.log	Service log output (written when running via baba install)

Configuration

All settings live in /var/lib/baba/config.json. The only required field is notifiers — everything else has a sensible default.

{
  "$schema": "https://raw.githubusercontent.com/orochibraru/baba/refs/heads/main/schema/config.schema.json",
  "notifiers": [
    { "type": "discord", "webhookUrl": "https://discord.com/api/webhooks/…" }
  ]
}

The $schema field enables autocomplete and inline validation in VS Code and other editors that support JSON Schema.

Update notifications are enabled by default: when baba start detects a newer release it sends a one-time alert through your configured notifiers. To opt out:

{ "updates": { "notifyEnabled": false } }

See docs/config.md for the full reference.

CLI commands

Command	Description
baba setup	Interactive setup wizard — writes /var/lib/baba/config.json
baba install	Register baba as a background service (launchd on macOS, systemd on Linux)
baba restart	Restart the background service
baba uninstall [--purge]	Remove the background service; --purge also deletes config, database, and logs
baba start	Start the monitoring loop in the foreground
baba logs [-f] [-n N]	Show logs from the background service; -f to follow, -n for line count (default 100)
baba update	Check for a newer release and replace the binary in-place
baba health	Check the service is correctly configured and able to alert
baba validate	Send a test alert to verify your notifiers
baba list incidents [-n N]	List recent incidents (default: 50)
baba get incident <id>	Show details and notifications for an incident
baba version / baba -v	Print the installed version

Running in the background

baba install registers the monitor as a system service so it starts automatically and restarts on crash — no terminal session required.

baba setup    # configure first
baba install  # register and start the service
baba logs -f  # follow live output

macOS — registers a LaunchAgent at ~/Library/LaunchAgents/com.orochibraru.baba.plist. Starts on login, restarts on crash. Logs go to /var/lib/baba/baba.log.

Linux — tries to register a systemd system service at /etc/systemd/system/baba.service (requires sudo). Starts on boot, restarts on crash. If sudo is unavailable, falls back to a user service at ~/.config/systemd/user/baba.service (only runs while logged in). Logs go to /var/lib/baba/baba.log.

To reinstall after changing config or updating the binary, just run baba install again — it replaces the existing service definition and restarts.

Use baba restart to restart the service without touching its definition (e.g. after editing config.json). Use baba uninstall to unregister it — config and data at /var/lib/baba are kept by default so you can reinstall later; pass --purge to remove those too.

Environment variables

Every config value can be overridden with a BABA_* environment variable — useful for containers and secrets managers. Values are applied before validation, so defaults and type coercion still work.

BABA_LOG_LEVEL=debug BABA_CPU_THRESHOLD=80 ./baba start

See docs/env.md for the full list.

Platform notes

Temperature and GPU checks are disabled by default. On macOS (Apple Silicon in particular), systeminformation returns null for most temperature and GPU utilization readings, so enabling them would produce no useful data. On Linux homelab servers these checks work as expected — enable them in config.json:

{
  "checks": {
    "temperature": { "enabled": true },
    "gpu": { "enabled": true }
  }
}

Contributing

See CONTRIBUTING.md.