monlet/README.md

English | Русский

Monlet

Monlet 0.1.0 is a small self-hosted monitoring system for local checks, host heartbeats, incidents, and notification delivery state.

Monlet is built for the gap between ad-hoc shell checks and a full observability platform. Agents run checks on the hosts where the facts live, push only structured observations to the server, and leave incident and notification lifecycle decisions to one central backend.

Why Monlet?

Simple infrastructure often starts with cron jobs, shell probes, and a chat webhook. That works until you need to answer basic operational questions:

• Which hosts are alive, stale, or dead?
• Which local checks are currently degraded?
• Did this failure open an incident, resolve one, or get deduplicated?
• Were notifications sent, retried, or failed?
• Can agents survive a server outage without creating duplicate events?

Monlet keeps that model explicit without adding remote command execution, remote config push, or a heavyweight incident-management platform.

What It Does

• A Go agent runs configured local commands from TOML.
• Agents send heartbeats and check events to the server over the /api/v1 API.
• The FastAPI server owns inventory, current check state, incidents, retention, and notifier outbox retries.
• The Next.js UI shows agents, checks, incidents, events, and notification delivery state.
• Operator admission is required before a new agent key can affect monitoring state.
• Server and agents expose Prometheus metrics for the monitoring system itself.

Screenshots

Agents and admission state:

Current check states:

Open and resolved incidents:

Notifier outbox state:

Features in 0.1.0

• Local command checks with ok, warning, critical, and unknown states.
• Heartbeat-based agent liveness with alive, stale, and dead status.
• Durable on-disk agent spool for server outages.
• Idempotent event ingestion and duplicate-safe replay.
• Server-owned incident open/resolve lifecycle.
• Notification outbox with retry and failure state.
• Debug, webhook, Telegram, and Alertmanager notifier implementations.
• Agent admission and blacklist controls.
• Partitioned PostgreSQL event storage and bounded retention.
• Docker Compose local stack and showcase stand.
• Prometheus metrics for server and agent runtime behavior.

Quick Start

Run the local stack:

cd deploy
MONLET_AUTH_TOKEN=$(openssl rand -hex 16) docker compose up --build

Services:

• Web UI: http://127.0.0.1:3000
• Server API: http://127.0.0.1:8000
• Readiness: http://127.0.0.1:8000/api/v1/ready
• Metrics: http://127.0.0.1:8000/metrics

Run the full demo stand:

SHOWCASE_KEEP=1 bash deploy/e2e-showcase.sh

The showcase starts PostgreSQL, the server, the web UI, a mock webhook, and several demo agents. It drives mixed check states, liveness transitions, resolved incidents, notifier retries/failures, and spool replay.

Architecture

Monlet is a monorepo with three independent applications:

• agent/ - Go binary installed on monitored hosts.
• server/ - Python/FastAPI backend with PostgreSQL storage.
• web/ - Next.js operator dashboard.

The server owns incident and notification lifecycle. The agent sends facts only. The web UI is read-only for monitoring state; agent admission and blacklist controls are the v1 mutation surface.

Public API contracts live in api/openapi.yaml. Design and operations docs live under docs/.

Non-Goals

Monlet 0.1.0 is intentionally not:

• a remote command runner;
• a remote config-push system;
• a Grafana replacement;
• a full incident-management platform;
• a multi-tenant RBAC product;
• a Kubernetes operator;
• a distributed server cluster.

Development

Start with:

1. deploy/README.md
2. agent/README.md
3. server/README.md
4. web/README.md
5. api/README.md

Dependency caches and virtual environments are kept inside the repository. See the component READMEs for current local development commands.

Status

Monlet is active early-stage software. The 0.1.0 release is usable for local development, demos, and controlled internal deployments. Internal contracts may still change while the public API remains versioned under /api/v1.

0.1.0 is the product release version. /api/v1 is the API namespace.

License

MIT.