Monitoring Pangolin Self-Hosted Tunnel Platform with Vigilmon

Pangolin is an open-source self-hosted tunneled reverse proxy and network access platform — a self-hosted alternative to Cloudflare Tunnel and ngrok. It creates encrypted WireGuard tunnels from your origin servers to a public VPS, so your home lab services get real HTTPS URLs without opening firewall ports or managing port forwarding rules. Pangolin manages multiple tunnel sites through a web dashboard and integrates with Newt (its tunnel client) to keep connections alive.

The same architecture that makes Pangolin convenient creates a monitoring challenge. If the Pangolin hub on your VPS goes down — dashboard crash, API failure, or WireGuard endpoint unavailable — all tunnel sites go offline simultaneously. Vigilmon lets you watch Pangolin from the outside, catching failures before visitors do.

What You'll Set Up

• HTTP monitor for the Pangolin web dashboard
• REST API health check confirming the Pangolin API server and database are operational
• TCP port monitor for the WireGuard tunnel endpoint
• SSL certificate expiry alerts for HTTPS dashboard deployments
• Heartbeat monitor verifying active tunnel resources are connected and routing traffic

Prerequisites

• Pangolin running on a VPS (Docker Compose setup)
• Pangolin dashboard accessible at http://YOUR_VPS_IP:3001 or a public domain
• Admin API key for the /api/v1/resources heartbeat check
• A free Vigilmon account

Step 1: Monitor the Pangolin Dashboard Web UI

The Pangolin dashboard runs on port 3001 by default. This is your management interface — if it's unreachable, you can't manage tunnel sites, review connected Newt clients, or adjust access rules.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: http://YOUR_VPS_IP:3001 (or https://pangolin.yourdomain.com if behind a reverse proxy).
4. Set Check interval to 2 minutes.
5. Set Expected HTTP status to 200.
6. Click Save.

Pangolin also exposes a dedicated health check at /health. For a stricter liveness signal, use:

• URL: http://YOUR_VPS_IP:3001/health
• Expected status: 200

The /health route returns quickly and confirms the Go process is responding even if the UI assets are slow to serve.

Step 2: Check the Pangolin REST API Health Endpoint

Pangolin exposes a /api/v1/health REST API endpoint that returns a JSON status response confirming the API server and its database connection are operational. This is more meaningful than a simple port check — a passing API health response means Pangolin can actually serve tunnel management requests.

In Vigilmon:

1. Add Monitor → HTTP / HTTPS.
2. URL: http://YOUR_VPS_IP:3001/api/v1/health
3. Set Expected HTTP status to 200.
4. Under Advanced, add an Expected body contains check: "status" (or "ok" depending on your Pangolin version).
5. Set Check interval to 2 minutes.
6. Click Save.

This catches the case where the Pangolin container is running but the internal database connection has failed — the dashboard port may appear open while tunnel management is completely broken.

Step 3: Monitor the WireGuard Tunnel Endpoint Port

Pangolin's Newt clients connect to the hub via WireGuard on UDP port 51820. While Vigilmon performs TCP probes (not UDP), a TCP check against port 51820 on your VPS confirms the port is reachable through your VPS firewall and that the Pangolin process is listening. Combined with the heartbeat check in Step 5, this gives you a reliable signal that the tunnel layer is operational.

1. Add Monitor → TCP Port.
2. Host: YOUR_VPS_IP (or public hostname).
3. Port: 51820.
4. Set Check interval to 2 minutes.
5. Click Save.

A TCP failure on port 51820 typically means a firewall rule was changed, Docker's network mapping broke, or the Pangolin container exited. All connected Newt clients will have lost their tunnels.

Step 4: SSL Certificate Expiry Alerts

If your Pangolin dashboard is served over HTTPS (strongly recommended for production deployments), add certificate expiry monitoring. Pangolin often sits behind Caddy or nginx for TLS termination, and certificate renewal failures are common when DNS records change or ports are briefly blocked during HTTP challenges.

On the HTTPS HTTP monitor created in Step 1:

1. Open the monitor in Vigilmon.
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 14 days.
4. Click Save.

With a 14-day window you have time to investigate and trigger a manual renewal before users see certificate errors or browsers start blocking access to your Pangolin dashboard.

Step 5: Heartbeat Monitor for Tunnel Resource Availability

Pangolin manages multiple tunnel resources (sites) and their routing status. A heartbeat monitor that periodically queries the Pangolin admin API confirms that all tunnel sites are connected and routing traffic — not just that Pangolin itself is running.

Create a script on your Pangolin VPS:

#!/bin/bash
# pangolin-resource-check.sh
# Confirms all Pangolin tunnel resources are connected

PANGOLIN_API="http://localhost:3001/api/v1"
ADMIN_API_KEY="YOUR_PANGOLIN_ADMIN_API_KEY"
HEARTBEAT_URL="https://vigilmon.online/api/heartbeat/YOUR_HEARTBEAT_ID"

# Fetch resources
response=$(curl -s -w "\n%{http_code}" \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  "$PANGOLIN_API/resources")

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -n -1)

if [ "$http_code" != "200" ]; then
  echo "$(date): Pangolin API returned HTTP $http_code — not pinging heartbeat"
  exit 1
fi

# Check if any resources are disconnected
disconnected=$(echo "$body" | python3 -c "
import json, sys
data = json.load(sys.stdin)
resources = data.get('resources', data) if isinstance(data, dict) else data
disconnected = [r.get('name', r.get('id', 'unknown')) for r in resources if not r.get('connected', True)]
print('\n'.join(disconnected))
" 2>/dev/null)

if [ -n "$disconnected" ]; then
  echo "$(date): Disconnected tunnel resources: $disconnected"
  exit 1
fi

# All resources connected — ping heartbeat
curl -s "$HEARTBEAT_URL" --max-time 10 --retry 2
echo "$(date): All Pangolin tunnel resources connected — heartbeat sent"

Make the script executable and add to crontab:

chmod +x /opt/scripts/pangolin-resource-check.sh
# Add to crontab
crontab -e

*/5 * * * * /opt/scripts/pangolin-resource-check.sh >> /var/log/pangolin-monitor.log 2>&1

Set up the heartbeat in Vigilmon:

1. Monitors → New Monitor → Heartbeat
2. Name: Pangolin Tunnel Resources
3. Interval: 10 minutes
4. Grace period: 5 minutes
5. Click Save and copy the heartbeat URL into the script above.

If any tunnel site loses connection or the Pangolin API becomes unreachable, the heartbeat stops pinging and Vigilmon fires an alert. This is your early warning that a Newt client has disconnected or that Pangolin's routing database is inconsistent.

Step 6: Alert Channels and Notification Routing

Because a Pangolin outage simultaneously affects every tunnel site on your VPS, configure alerts to reach the right people immediately:

1. Go to Alert Channels → Add Channel → choose Slack, email, or webhook.
2. For the WireGuard port monitor and API health check, set Consecutive failures before alert to 2 — brief restarts during updates shouldn't page you.
3. For the tunnel resource heartbeat, set it to alert immediately on the first missed check — a disconnected tunnel site means a service is unreachable for users.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Dashboard UI | :3001 | Container crash, process exit | | API health | :3001/api/v1/health | Database failure, API unresponsive | | TCP port | :51820 | WireGuard endpoint unreachable, firewall change | | SSL certificate | Dashboard HTTPS domain | Certificate expiry, renewal failure | | Tunnel resource heartbeat | /api/v1/resources | Disconnected Newt client, tunnel routing failure |

Pangolin's architecture means a single VPS hosts the hub for all your tunnel sites. Monitoring that hub thoroughly — from the dashboard UI down to the WireGuard port and the routing state of every connected resource — means you'll know about failures before anyone trying to reach your services does.

Start monitoring your Pangolin tunnel platform today at vigilmon.online — free, no credit card required.