warden

README

Warden

Open-source, self-hosted uptime monitoring built to be operated directly or through an AI assistant. Warden helps agencies and teams monitor HTTP endpoints, TCP ports, ICMP hosts and DNS records, publish status pages, and deliver alerts — from a single binary with no external dependencies.

Warden also learns the normal latency of every monitor. It can detect that a healthy response became unusually slow without forcing a 20 ms health check and a 450 ms remote storefront to share the same threshold.

Warden also learns the normal latency of every monitor. It can detect that a healthy response became unusually slow without forcing a 20 ms health check and a 450 ms remote storefront to share the same threshold.

Operate Warden through your AI

Warden includes a role-scoped MCP server, so an MCP-compatible assistant can answer questions such as:

• "What is down right now?"
• "What happened while I was asleep?"
• "Was the checkout API getting slower before it failed?"
• "Create monitors for these client domains and put them in a new group."

Use a viewer key for everyday investigation. An editor key additionally lets the assistant create, group, move, pause and resume monitors; destructive deletion is deliberately unavailable through MCP. Agencies can group monitors by client and publish a focused status page for each group.

Quick Start

docker run -d -p 9090:9090 \
  -v warden_data:/data \
  ghcr.io/projecthelena/warden:latest

Open http://localhost:9090 and create your admin account.

Environment Variables

Variable	Default	Description
LISTEN_ADDR	:9090	Port Warden listens on. Change it if 9090 is already taken.
DB_TYPE	sqlite	sqlite or postgres. Warden uses SQLite by default — no setup needed. Set to postgres if you want to use PostgreSQL. Takes precedence over DB_URL auto-detection.
DB_PATH	/data/warden.db	Where the SQLite database file is stored. Only matters when using SQLite.
DB_URL	—	PostgreSQL connection string (e.g. postgres://user:pass@host:5432/warden). Setting this automatically switches to PostgreSQL.
COOKIE_SECURE	false	Set true if you serve Warden over HTTPS. Tells browsers to only send login cookies over secure connections, preventing them from leaking on plain HTTP.
TRUST_PROXY	false	Set true if Warden runs behind a reverse proxy (nginx, Traefik, Caddy). Lets Warden see users' real IPs for rate limiting. Leave false if Warden is exposed directly — otherwise anyone can fake their IP.
ADMIN_SECRET	—	For development and testing only. Enables the database reset endpoint and disables rate limits. Do not set in production.

Docker Compose

Ready-to-use compose files in deploy/:

• SQLite — simplest, no extra services
• PostgreSQL — for larger deployments

Documentation

See the docs/ folder for detailed guides:

• Monitor Types — HTTP, TCP, ping and DNS checks, and the permissions ICMP needs
• API — REST API and Swagger docs
• MCP Server — inspect and safely operate Warden from an AI assistant
• Notifications — Slack, webhook and email channels, and how to configure SMTP
• Adaptive Latency — how Warden learns each monitor's normal response time and detects regressions
• Notification Fatigue — confirmation windows, reminders, correlation and alert damping
• Database — SQLite vs PostgreSQL configuration
• PostgreSQL Migration — move a complete Warden installation to another PostgreSQL instance
• Password Recovery — reset a password or get back in after a lockout
• Load Testing (coming soon)

Markdown style

Markdown prose stays unwrapped: one source line per paragraph. Run npm run format:markdown to fix every tracked Markdown file or npm run check:markdown to verify it. The pre-push hook and CI run the same check.

License

AGPL-3.0 — Project Helena