pulsecheck

English · فارسی

Self-hosted uptime monitor. It checks HTTP(S) endpoints, TCP ports and hosts (ping) on a schedule, tracks up / down / slow state, and sends alerts through shoutrrr (Slack, Telegram, Discord, email, ntfy and 20+ more). One YAML file, one state file, no dashboard, no git history.

Features

• HTTP checks: method, headers, body, expected status, redirect limit, max response time, "slow" (degraded) threshold
• TLS certificate expiry warnings (ssl_warn_days) and expired-certificate failures
• TCP and ping checks
• Alerts only on change, down_after to ignore blips, optional repeat reminders (remind_every)
• Per-site tags, intervals and alert routing; UTC maintenance windows
• Editable alert texts by key (messages:)
• status (text, JSON, markdown) and report (uptime %, response times) without a dashboard
• OpenTelemetry push (OTLP/HTTP JSON metrics and logs) to any collector or webhook
• Guided setup: init (config, .env, shoutrrr, cron), env, validate, test-notify to every channel, update
• ${ENV} substitution, so secrets stay out of the config
• Runs from GitHub Actions, GitLab CI, cron, or serverless on Vercel and Cloudflare Workers (see the limits)
• Python 3.12–3.15 (3.15 preferred), managed with uv

Install

uv tool install pulsecheckcli     # or: pipx install pulsecheckcli   (once the first release is on PyPI)
pulsecheck init                   # config + .env + shoutrrr + cron job (Linux)
pulsecheck env                    # add your tokens
pulsecheck validate && pulsecheck test-notify

The package is pulsecheckcli; the command is pulsecheck, and pck is a short alias for it. All commands: Commands.

Or: one line from GitHub (Linux)

curl -fsSL https://raw.githubusercontent.com/arian24b/pulsecheck/main/install.sh | bash

It installs the PyPI package pulsecheckcli with uv tool (from GitHub until the first release) and runs pulsecheck init. Then run pulsecheck env, pulsecheck validate and pulsecheck test-notify.

Quick start (from a clone)

uv sync
cp pulsecheck.example.yml pulsecheck.yml     # edit it
uv run pulsecheck validate
uv run pulsecheck test-notify
uv run pulsecheck run [--force] [--fail-on-down] [--tag prod]
uv run pulsecheck status [--json|--md]
uv run pulsecheck report [--json]

shoutrrr runs from its docker image when Docker works, otherwise from the shoutrrr binary on PATH. ping is needed for type: ping.

Use Use this template to get your own copy with the GitHub Actions workflow ready. Keep your copy private: your pulsecheck.yml lists your hostnames.

Documentation (wiki)

Questions: Discussions. Contributing: CONTRIBUTING. Security: SECURITY.

Development

uv run pytest -q && uv run ruff check . && uv run ruff format --check .

Commit messages follow Conventional Commits (feat:, fix:, ...): the version, CHANGELOG.md, the GitHub release and the PyPI upload are generated from them by python-semantic-release.

License

MIT