Monlet

Monlet is a lightweight event and check monitoring system.

It is split into three independent applications:

• agent/ - a small Go binary installed on monitored hosts.
• server/ - a Python/FastAPI backend that owns inventory, state, incidents, and notifications.
• web/ - a Next.js dashboard with agent admission controls.

All three applications are implemented and run together via Docker Compose. The current release covers agent ingestion with operator admission, server-owned incident lifecycle and notifier outbox, a Next.js dashboard, and partitioned event retention.

Scope

Monlet v1 focuses on local checks, central state, and simple visibility:

• agents run local checks from TOML config;
• agents expose Prometheus metrics and/or push facts to the server;
• server ingests heartbeats and check events idempotently;
• server owns current state, incident lifecycle, and notifier retries;
• web UI reads server APIs and does not mutate state.

Non-goals for v1

• remote command execution;
• remote config push;
• full RBAC;
• multi-tenant enterprise model;
• complex silences or inhibition engine;
• Grafana replacement;
• long-term log storage;
• full incident management platform;
• Kubernetes operator;
• plugin marketplace;
• distributed server cluster.

Repository Map

• docs/ - architecture, ADRs, development, and operations docs.
• plan/ - stage workflow and exit checkpoints.
• api/ - versioned OpenAPI contract.
• agent/ - Go agent: scheduler, runner, spool, metrics.
• server/ - Python/FastAPI backend: ingestion, detector, notifier outbox.
• web/ - Next.js dashboard and agent admission UI.
• deploy/ - local and observability deployment examples.
• examples/ - example checks and configs.

Start Here

Read in this order:

1. docs/README.md
2. docs/architecture/overview.md
3. ROADMAP.md
4. TODO.md
5. plan/README.md
6. AGENTS.md
7. CLAUDE.md

Current Status

Active development. Stages 0–6 are implemented. Run the stack via docker compose up --build from deploy/. See docs/operations/deployment.md and docs/ops/ runbooks.