Chowkidar

Lightweight Docker health monitor with configurable restart and notification actions.

Chowkidar watches your containers for unhealthy health events and exited states, then reacts automatically — restarting, stopping, or running a custom script — and sends notifications via Discord, Slack, Telegram, email, and more.

Features

• Container monitoring — polls Docker for unhealthy and exited containers; supports Docker-native health checks and custom bash health-check scripts per job
• Configurable actions — restart, start, stop, none, run-script per job
• Per-job health-check script — define a bash script that determines container health (exit 0 = healthy, non-zero = unhealthy); dry-run and template picker included
• Per-job overrides — individual retry count, monitoring interval, action timeout, and post-action wait
• Multi-context job rules — pin each job to one or more Docker contexts; jobs with no context run on all hosts
• Multi-provider notifications — Discord, Slack, Telegram, ntfy, Gotify, Pushover, SMTP/email, raw Apprise URLs
• Notification templates — customise message content per provider per lifecycle event
• Jobs system — define targeted monitoring rules with container name/label/env var filters
• Bash script action — run a custom inline script per job with built-in templates, dry-run execution, and automatic template upgrade detection
• Multi-Docker-host — monitor containers across multiple Docker hosts or sockets; each host individually enabled/disabled with its own monitoring interval, ping timeout, and offline confirm window
• Per-host offline notifications — configure notification agents and custom message templates per Docker host; notifies once on down, once on recovery (no spam)
• Web UI — dashboard, jobs, notification profiles, action history, settings
• Authentication — optional username/password protection with bcrypt hashing
• Encryption — notification credentials encrypted at rest via CHOWKIDAR_SECRET_KEY
• 3 dashboard layouts — Card List, Compact Table, Status Grid; service groups are collapsible with state persisted across reloads
• Dashboard filters — filter by status, tag, job action, Docker host, container name, label, env var, and job name; advanced filters panel for power users
• Maintenance windows — schedule service pauses using six strategies (Manual, Single Window, Cron, Interval, Day of Week, Day of Month); targets jobs or Docker hosts (mutually exclusive); optional effective date ranges; per-window control over queued/in-flight action handling when a window opens (allow-finish / cancel-queued / force-cancel); bell notifications on start and end; auto-prune of expired single-occurrence windows
• Notification bell — persistent system alerts (boot, failed recovery, paused monitoring) with per-alert dismiss and mark-all-read
• Version check — settings sidebar shows running version; background check surfaces a bell alert when a newer release is available
• Light/dark/auto theme
• Persistent config — everything stored under /config (YAML + JSON history + logs)
• Docker socket proxy support for reduced attack surface

Quick Start

docker compose up -d

Open http://localhost:8080

Development

Runs with live reload via Air. Go file changes rebuild the binary automatically; web/ is served directly from disk so HTML/CSS/JS changes are visible on refresh with no rebuild.

docker compose -f docker-compose.dev.yml up --build

Open http://localhost:8080

Docker CLI

docker run -d \
  --name chowkidar \
  --restart unless-stopped \
  -p 8080:8080 \
  -e CHOWKIDAR_SECRET_KEY=your-long-random-secret \
  -v /mnt/user/appdata/chowkidar:/config \
  -v /var/run/docker.sock:/var/run/docker.sock \
  darkmatterforge/chowkidar:latest

Environment Variables

Most settings are configured through the web UI (Settings page) and persisted to /config/config.yaml. The env vars below are the ones you typically set at container creation time. Every env var still overrides the config file if set.

Required at startup

Docker connectivity

Chowkidar connects to Docker via the mounted socket by default. Additional Docker hosts are added through Settings → Docker Hosts in the web UI. Each host can be individually enabled/disabled and has its own monitor interval, ping timeout, and offline notification settings.

Container filtering

Useful to set at the container level so monitoring starts correctly on first boot:

Logging

Advanced overrides

All of these are also configurable via the web UI. Set as env vars only if you need to enforce values that the UI cannot override (e.g. in a managed deployment).

Notification Providers

Configure via the web UI under Settings → Notifications.

Notification Events

Templates can be customised per provider for each lifecycle event:

Template variables: {}, {}, {}, {}, {}, {}, {}

API

Unraid

Install via Community Applications or add the template manually:

https://raw.githubusercontent.com/darkmatterforge/chowkidar/main/unraid/chowkidar.xml

Map /mnt/user/appdata/chowkidar → /config and set CHOWKIDAR_SECRET_KEY.

License

AGPL-3.0 — Copyright (C) 2026 Dark Matter Forge.

You may use and build on this software, but any modified version must remain open source under the same terms. See NOTICE for full usage terms and trademark information.