🐱 LurkKit

Lightweight host monitoring agent — silently watching, loudly alerting.

LurkKit is a zero-friction host monitoring agent. Drop it on any host, point it at a config file, and get system metrics, process health, HTTP probing, and log tail alerts forwarded to Slack, PagerDuty, Datadog, or OpsGenie.

Quick Start

pip install lurkkit
lurkkit --init      # generate config
lurkkit             # run

Commands

lurkkit --status                        # one-shot system snapshot
lurkkit --validate --config lurkkit.yaml  # validate config
lurkkit --config /etc/lurkkit/lurkkit.yaml
lurkkit --log-level DEBUG
lurkkit --version

Installation Options

User Install (no root)

pip install --user lurkkit
lurkkit --init

Config auto-detected from (first found wins):

• $LURKKIT_CONFIG env var
• ./lurkkit.yaml
• ~/.config/lurkkit/lurkkit.yaml
• /etc/lurkkit/lurkkit.yaml

systemd (root)

sudo bash scripts/install.sh
journalctl -u lurkkit -f

Docker

docker run -v $(pwd)/lurkkit.yaml:/etc/lurkkit/lurkkit.yaml ghcr.io/SREportal/lurkkit

Alert Routing

CRITICAL → PagerDuty + OpsGenie  (pages on-call)
WARNING  → Slack + Datadog        (no 3am calls)
INFO     → Slack + Datadog

Configurable via paging_severities and non_paging_severities in your config.

Monitors

Metrics Reference

Extending LurkKit

Custom Collector

from lurkkit import LurkKitAgent
from lurkkit.collectors.base import BaseCollector
from lurkkit.models import Metric, Alert, Severity

class MyCollector(BaseCollector):
    def collect(self):
        return [Metric("myapp.value", {"count": 42}, self._base_tags())], []

agent = LurkKitAgent.from_config("lurkkit.yaml")
agent.register_collector("myapp", MyCollector({"interval": 15}, agent.hostname))
agent.start()

Development

git clone https://github.com/SREportal/lurkkit
cd lurkkit
pip install -e ".[dev]"
pytest tests/ -v

See CONTRIBUTING.md for the full guide.

License

MIT — see LICENSE.