tutorial

Monitoring Pinchflat with Vigilmon: Uptime, Health & Heartbeat Alerts for Your YouTube Downloader

How to monitor a self-hosted Pinchflat instance with Vigilmon — using the built-in healthcheck endpoint, ping monitors, heartbeat checks for scheduled downloads, and SSL certificate alerts when running behind a reverse proxy.

Pinchflat is a self-hosted YouTube subscription and download manager built on yt-dlp, designed for Apple Silicon Macs and Linux. It quietly runs in the background, syncing your subscribed channels and downloading new content on a schedule — no manual intervention required. But self-hosting means you're the reliability layer. If Pinchflat's web process crashes, yt-dlp loses network access to YouTube, or your media storage fills up, you'll only notice when you go looking for a video that was never downloaded. Vigilmon gives you external monitoring that watches Pinchflat from the outside and alerts you the moment something breaks.

What You'll Build

  • A Vigilmon HTTP monitor on Pinchflat's built-in /healthcheck endpoint
  • A keyword assertion to confirm Pinchflat is genuinely healthy
  • A heartbeat monitor to verify scheduled download jobs are completing
  • SSL certificate monitoring if you're proxying Pinchflat over HTTPS

Prerequisites

  • A running Pinchflat instance (default port: 8945)
  • A reverse proxy (Caddy or Nginx) with HTTPS — required for Vigilmon monitors
  • A free account at vigilmon.online

Step 1: Verify the Healthcheck Endpoint

Pinchflat exposes a /healthcheck endpoint on its default port 8945. Test it directly:

curl http://localhost:8945/healthcheck

A healthy Pinchflat instance returns HTTP 200 with a simple OK body. If Pinchflat is running but its internal job queue has stalled, the endpoint may still respond — which is why pairing it with a heartbeat monitor (Step 4) is important.

HTTPS first: Vigilmon monitors require HTTPS. Put Pinchflat behind Caddy or Nginx before proceeding. A minimal Caddy config:

pinchflat.yourdomain.com {
  reverse_proxy localhost:8945
}

Step 2: Create a Vigilmon HTTP Monitor

An HTTP monitor pings your Pinchflat endpoint on a schedule and alerts you if it fails to respond or returns a non-200 status.

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: https://pinchflat.yourdomain.com/healthcheck.
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds (Pinchflat may be briefly busy during active downloads).
  5. Expected status: 200.
  6. Click Save.

Vigilmon now probes Pinchflat every 60 seconds from an external network location — completely independent of your server's local monitoring.

Step 3: Add a Keyword Assertion

A 200 status confirms the HTTP server responded, but it doesn't guarantee Pinchflat's internals are healthy. Add a keyword check to catch partial failures:

In the monitor settings, add a Keyword assertion:

  • Keyword: ok (or whatever Pinchflat returns in its healthcheck body)
  • Keyword must be present: yes

This catches scenarios like a reverse proxy returning a 200 "Service Unavailable" HTML page while Pinchflat itself is down, or a partial startup that serves the HTTP server but hasn't initialized yt-dlp yet.

Step 4: Monitor Scheduled Download Jobs with Heartbeats

Pinchflat's real value is its scheduled download jobs. The HTTP monitor confirms the web UI is running, but it won't tell you if downloads have silently stopped. A Vigilmon heartbeat monitor solves this.

Create a Heartbeat monitor in Vigilmon:

  1. Add Monitor → Heartbeat.
  2. Expected interval: 60 minutes (or match your Pinchflat sync schedule).
  3. Grace period: 15 minutes.
  4. Copy the heartbeat URL (e.g., https://vigilmon.online/api/heartbeat/YOUR-ID).

Configure Pinchflat to ping the heartbeat after each sync:

Pinchflat supports custom post-download hooks. In your Pinchflat configuration, add a command that POSTs to your heartbeat URL after each successful sync cycle:

curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-HEARTBEAT-ID

If downloads stall — because yt-dlp can't reach YouTube, your storage is full, or Pinchflat's scheduler has crashed — the heartbeat stops arriving and Vigilmon alerts you within the grace period.

Step 5: Monitor yt-dlp Connectivity (Indirect)

Pinchflat relies on yt-dlp to reach YouTube. If YouTube changes its API, your server's IP gets rate-limited, or there's a network routing issue, downloads silently fail. The heartbeat monitor catches this indirectly: no successful downloads means no heartbeat pings.

For a more direct check, add a second HTTP monitor pointing at Pinchflat's web UI root:

  1. Add Monitor → HTTP.
  2. URL: https://pinchflat.yourdomain.com/ (the main dashboard).
  3. Expected status: 200.
  4. Keyword: Pinchflat (appears in the page title).

This confirms the full application stack — not just the healthcheck endpoint — is serving correctly.

Step 6: Monitor SSL Certificate Expiry

If you're proxying Pinchflat over HTTPS, an expired certificate locks you out of the web UI. Vigilmon monitors your SSL certificate automatically when you create an HTTP monitor on an HTTPS URL.

In your existing HTTP monitor:

  • SSL certificate alert: enable it.
  • Alert days before expiry: 14 days (gives you time to renew before anything breaks).

Caddy and Certbot both auto-renew certificates, but auto-renewal can fail silently if the renewal process is blocked by a firewall rule or a stale ACME challenge. Vigilmon's certificate expiry alert acts as a backstop.

Step 7: Configure Alerting

In Vigilmon under Settings → Notifications, configure your channels:

| Trigger | Action | |---|---| | Healthcheck non-200 | Email + push notification — Pinchflat process likely crashed | | Response timeout | Email — check if yt-dlp is blocking the web process | | Keyword missing | Email — reverse proxy misconfiguration | | Heartbeat missed | Email — scheduled downloads have stopped; check Pinchflat logs | | SSL expiry < 14 days | Email — force certificate renewal |

Alert after: 1 consecutive failure. Pinchflat is a single-process application; transient flapping is rare.

Re-notify: every 30 minutes while the issue persists — download jobs miss their windows quickly.

What Vigilmon Catches That Pinchflat Logs Miss

| Scenario | Pinchflat logs | Vigilmon | |---|---|---| | Process crash, systemd restart fails | Crash logged, then silent | HTTP monitor fires within 60–120 s | | yt-dlp can't reach YouTube | Error in download logs | Heartbeat stops arriving | | Storage disk full, downloads failing | Write errors in logs | Heartbeat stops arriving | | SSL certificate expires | Not monitored internally | Certificate expiry alert fires | | Reverse proxy misconfiguration | Nginx/Caddy error logs | Keyword assertion catches wrong response |

Pinchflat makes YouTube archival effortless — but only when it's actually running. Vigilmon ensures you know within minutes when something breaks, so your download queue never silently falls behind.

Set up monitoring for your Pinchflat instance in under 5 minutes — register free at vigilmon.online.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles