tutorial

Monitoring Cobalt Media Downloader with Vigilmon

Cobalt is a self-hosted media download API — but a stale yt-dlp install or crashed tunnel service silently breaks downloads. Here's how to monitor Cobalt availability, download processing, yt-dlp health, and API authentication with Vigilmon.

Cobalt is a self-hosted media downloader API that converts video and audio URLs from YouTube, TikTok, Twitter/X, Instagram, and dozens of other platforms into clean downloadable files — no ads, no tracking, no login required. But "self-hosted" means you own the uptime. A stale yt-dlp version breaks YouTube downloads overnight when Google updates their API. A crashed tunnel service breaks direct stream downloads. An unconfigured rate limiter gets your server blocked. Vigilmon monitors every layer of Cobalt so you know the moment downloads stop working.

What You'll Set Up

  • HTTP uptime monitor for the Cobalt API server (port 9000)
  • Server info endpoint health check
  • Download processing endpoint probe
  • yt-dlp subprocess version and execution health
  • Stream tunnel service availability
  • Rate limiting and API key authentication health
  • SSL certificate expiry alerts

Prerequisites

  • Cobalt running and accessible (default API port 9000)
  • A free Vigilmon account

Step 1: Monitor the Cobalt API Server

Cobalt's Node.js API server listens on port 9000. Add a Vigilmon HTTP monitor for the server info endpoint, which returns version and status information:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Cobalt API URL: https://cobalt.yourdomain.com/api/serverInfo.
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Optionally set Response must contain to "version" to validate the response body.
  7. Click Save.

The /api/serverInfo endpoint is a lightweight GET that confirms the Node.js process is alive and the API is initialized.

Step 2: Monitor the Main Download Endpoint

The core Cobalt endpoint (POST /api/) does the actual download processing. An API server that responds to /api/serverInfo but crashes on download requests is still broken. Test the download path with a known-good short URL:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to https://cobalt.yourdomain.com/api/.
  3. Set Request method to POST.
  4. Set Request headers: Content-Type: application/json, Accept: application/json.
  5. Set Request body: 
    {"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","downloadMode":"audio"}
  6. Set Expected HTTP status to 200.
  7. Optionally set Response must contain to "status" to validate Cobalt's response envelope.
  8. Set Check interval to 5 minutes.
  9. Click Save.

A 200 with a status field confirms the download pipeline is operational. A 500 indicates yt-dlp subprocess failure or a platform-side change.

If you have API key authentication enabled, add your key:

  • Set Request headers: Authorization: Api-Key YOUR_API_KEY.

Step 3: Monitor yt-dlp Health with a Heartbeat

Cobalt shells out to yt-dlp for most platform downloads. yt-dlp updates frequently — YouTube in particular changes their API format regularly, requiring yt-dlp updates within days. A stale yt-dlp version causes download failures even though the Cobalt API itself is running.

Create a yt-dlp version check script that pings Vigilmon when yt-dlp is current and functional:

#!/bin/bash
# ytdlp-health.sh — checks yt-dlp is installed and executable

# Verify yt-dlp can run and return version info
VERSION=$(yt-dlp --version 2>/dev/null)
if [ -z "$VERSION" ]; then
  echo "yt-dlp not found or not executable" >&2
  exit 1
fi

# Verify yt-dlp can extract info from a known short video (no download)
yt-dlp --simulate --no-warnings \
  'https://www.youtube.com/watch?v=dQw4w9WgXcQ' >/dev/null 2>&1

if [ $? -eq 0 ]; then
  curl -s https://vigilmon.online/heartbeat/ytdlp-heartbeat-url
else
  echo "yt-dlp failed to extract info — may be outdated" >&2
fi
  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set expected interval to 30 minutes.
  3. Schedule with cron: */30 * * * * /opt/cobalt/ytdlp-health.sh.

A failed yt-dlp info extraction almost always means yt-dlp is outdated and needs yt-dlp -U to update. Set up an auto-updater cron alongside this monitor:

# Auto-update yt-dlp daily at 3 AM
0 3 * * * yt-dlp -U >> /var/log/ytdlp-update.log 2>&1

Step 4: Monitor the Stream Tunnel Service

For platforms where Cobalt proxies the media stream directly (rather than returning a redirect URL), a tunnel service runs alongside the API. If the tunnel endpoint is unavailable, stream-mode downloads fail while redirect-mode downloads still work — making the failure mode subtle and hard to spot.

Add a TCP monitor for the tunnel port:

  1. Click Add Monitor → TCP Port.
  2. Set Hostname to your Cobalt server.
  3. Set Port to 9001 (default tunnel port — check your Cobalt TUNNEL_PORT environment variable).
  4. Set Check interval to 1 minute.
  5. Click Save.

If your tunnel runs as a separate process or Docker container, this TCP check will catch restarts and port binding failures.

Step 5: Monitor Rate Limiting Middleware

Cobalt includes configurable rate limiting per IP to prevent abuse. If the rate limit state store (in-memory or Redis-backed) corrupts, rate limiting may reject all requests regardless of origin. Check that normal requests still pass through:

The download endpoint monitor in Step 2 doubles as a rate limit health check — if it returns 429 Too Many Requests, your own health check IP has been rate-limited. To avoid this, configure Cobalt's allowlist to exempt your Vigilmon probe IP, or use a dedicated API key that bypasses rate limits:

# In Cobalt's .env — exempt monitoring IP from rate limiting
RATELIMIT_EXEMPT_IPS=your-monitoring-probe-ip

If Vigilmon probes start returning 429, add your Vigilmon probe IPs (shown in your Vigilmon account settings) to the Cobalt rate limit exemption list.

Step 6: Monitor API Key Authentication

If you've configured Cobalt to require API key authentication (API_KEY_URL environment variable), verify the auth layer is working by probing with an invalid key:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to https://cobalt.yourdomain.com/api/.
  3. Set Request method to POST.
  4. Set Request headers: Content-Type: application/json, Authorization: Api-Key invalid-key.
  5. Set Request body: {"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}.
  6. Set Expected HTTP status to 401.
  7. Set Check interval to 5 minutes.

A 401 confirms the auth middleware is alive and correctly rejecting invalid keys. A 200 means auth has been bypassed (misconfiguration). A 500 or timeout means the auth layer has crashed.

Step 7: Check External Platform Reachability

Cobalt downloads from external platforms — if your server's outbound network has issues or YouTube/TikTok changes their CDN routing, downloads fail at the source rather than in Cobalt. Spot-check platform reachability from Vigilmon:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to https://www.youtube.com (a simple connectivity check).
  3. Set Expected HTTP status to 200.
  4. Set Check interval to 5 minutes.

If this monitor alerts, the problem is outbound network connectivity from your server to the platform CDN — not a Cobalt or yt-dlp issue.

Step 8: Monitor FFmpeg for Output Conversion

If your Cobalt deployment uses FFmpeg for audio extraction or video remuxing (converting from one container format to another), FFmpeg availability is critical. A missing FFmpeg binary causes conversion requests to fail silently.

Add an FFmpeg health check heartbeat:

#!/bin/bash
# ffmpeg-health.sh
ffmpeg -version >/dev/null 2>&1
if [ $? -eq 0 ]; then
  curl -s https://vigilmon.online/heartbeat/ffmpeg-heartbeat-url
else
  echo "FFmpeg not found or not executable" >&2
fi
  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set expected interval to 10 minutes.
  3. Schedule: */10 * * * * /opt/cobalt/ffmpeg-health.sh.

Step 9: SSL Certificate Expiry Alerts

Add SSL monitoring to your main Cobalt API monitor:

  1. Open the Cobalt HTTP monitor created in Step 1.
  2. Enable Monitor SSL certificate.
  3. Set Alert when certificate expires in less than 21 days.
  4. Click Save.

An expired certificate causes every Cobalt client to receive SSL errors, breaking all downloads from HTTPS-only clients.

Step 10: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, email, or webhook.
  2. Set Consecutive failures before alert to 2 on the API server and download endpoint monitors.
  3. Set Consecutive failures to 1 on the yt-dlp and FFmpeg heartbeats — a single missed ping means the subprocess is broken.
  4. For platform reachability monitors (YouTube, etc.), set Consecutive failures to 3 — platforms have brief transient outages.

Summary

| Monitor | Target | What It Catches | |---|---|---| | API server | GET /api/serverInfo | Node.js crash, port binding failure | | Download endpoint | POST /api/ with test URL | yt-dlp failure, platform breakage | | yt-dlp health | Heartbeat every 30 min | Outdated yt-dlp, subprocess crash | | Stream tunnel | TCP port 9001 | Tunnel process crash | | Rate limiting | POST /api/ → not 429 | Rate limiter blocking all requests | | API key auth | POST /api/ → 401 | Auth middleware crash or bypass | | Platform reachability | https://www.youtube.com | Outbound network failure | | FFmpeg | Heartbeat every 10 min | Missing binary, broken conversion | | SSL certificate | API domain | Let's Encrypt renewal failure |

Cobalt removes the friction of downloading media from any platform — Vigilmon removes the friction of knowing when Cobalt itself has stopped working. With yt-dlp heartbeats, download endpoint probes, and tunnel service checks, you'll catch the most common Cobalt failure modes automatically.

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