Monitoring Puter with Vigilmon

Puter is an open source cloud desktop operating system that runs entirely in the browser — giving users a full desktop experience with file storage, apps, and a cloud environment, all hosted on your own server (Node.js, default port 4100). Running Puter yourself means your users' files, sessions, and desktop state live on infrastructure you control. But that control comes with an uptime responsibility: if the Puter server goes down, every user's desktop disappears. Vigilmon monitors Puter's web server, API endpoints, file system service, and session backends so you know the instant something breaks.

What You'll Set Up

HTTP uptime monitor for the Puter web server (port 4100)
API endpoint health check for the Puter backend
File system service availability verification
Heartbeat monitor for the user session backend
SSL certificate expiry alerts

Prerequisites

Puter running on a server (default port 4100)
A domain or IP accessible over HTTP/HTTPS
A free Vigilmon account

Step 1: Monitor the Puter Web Server

Puter serves the full desktop UI over HTTP. The root URL loading successfully means the web server, static assets, and initial rendering pipeline are all healthy.

Log in to vigilmon.online and click Add Monitor.
Set Type to HTTP / HTTPS.
URL: https://puter.yourdomain.com (or http://your-server-ip:4100 for local installs)
Set Expected HTTP status to 200.
Set Check interval to 1 minute.
Optionally enable Keyword match and enter Puter — the Puter HTML shell includes this in the page title, confirming the real UI loaded rather than a proxy error page.
Click Save.

For production deployments, put Puter behind nginx:

server {
    listen 443 ssl;
    server_name puter.yourdomain.com;

    location / {
        proxy_pass http://localhost:4100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_http_version 1.1;
    }
}

Step 2: Monitor the Puter API Endpoint

Puter's backend API handles file operations, user auth, app management, and session state. Even if the web UI loads, a crashed API means no files can be read or written.

Click Add Monitor → HTTP / HTTPS.
URL: https://puter.yourdomain.com/api/v1/
Set Expected HTTP status to 200 or 404 — the API returns a structured response on the root that confirms it's alive.
Set Check interval to 2 minutes.
Click Save.

If you want a dedicated health endpoint, add one to your Puter server configuration:

// In your Puter server entry point
app.get('/healthz', (req, res) => {
    res.json({
        status: 'ok',
        uptime: process.uptime(),
        timestamp: Date.now()
    });
});

Then monitor https://puter.yourdomain.com/healthz with Keyword match "status":"ok" for a cleaner health signal.

Step 3: File System Service Availability

Puter's value proposition is cloud file storage — if the file system service is unavailable, users can't open, save, or share files even if the web UI appears healthy. Add a check that exercises the file system layer:

Click Add Monitor → HTTP / HTTPS.
URL: https://puter.yourdomain.com/api/v1/filesystem/ (or the appropriate Puter FS endpoint)
Set Expected HTTP status to 401 — an unauthenticated request to a protected endpoint returns 401, confirming the route is live and the auth middleware is running.
Set Check interval to 5 minutes.
Click Save.

For a more proactive file system check, use a service account to ping the FS API on a schedule:

#!/bin/bash
# /opt/puter/fs-check.sh
PUTER_URL="https://puter.yourdomain.com"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_FS_HEARTBEAT_ID"

# Attempt an authenticated FS list
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $PUTER_SERVICE_TOKEN" \
  "$PUTER_URL/api/v1/filesystem/?path=/")

if [ "$HTTP_STATUS" = "200" ]; then
    curl -s "$HEARTBEAT_URL" > /dev/null
else
    echo "FS check failed: HTTP $HTTP_STATUS"
    # No ping — Vigilmon alerts on missed heartbeat
fi

Run this every 5 minutes via cron. Create a Push / Heartbeat monitor in Vigilmon with a 10 minute expected interval to give yourself a 5-minute grace window.

Step 4: TCP Port Monitor

A TCP monitor catches failures that HTTP monitors miss — such as a crashed Node.js process where the port is no longer bound.

Click Add Monitor → TCP Port.
Set Host to your Puter server hostname or IP.
Set Port to 443 (nginx) or 4100 (Node.js direct).
Set Check interval to 1 minute.
Click Save.

To monitor both layers independently:

Port 443 → nginx proxy layer
Port 4100 (from inside your network) → Node.js process

If 443 fails but 4100 responds, nginx is the problem. If both fail, Node.js crashed.

Step 5: Session Backend Heartbeat

Puter manages user sessions that persist desktop state across page loads. If the session backend fails (Redis crash, database connectivity issue, corrupted session store), users are logged out or see stale desktop states — even if the API appears healthy.

Create a session health check script:

// /opt/puter/session-check.js
const https = require('https');
const http = require('http');

const HEARTBEAT_URL = 'https://vigilmon.online/heartbeat/YOUR_SESSION_HEARTBEAT_ID';

// Check that the session endpoint responds correctly
https.get('https://puter.yourdomain.com/api/v1/auth/whoami', {
    headers: { 'Authorization': `Bearer ${process.env.PUTER_SERVICE_TOKEN}` }
}, (res) => {
    if (res.statusCode === 200 || res.statusCode === 401) {
        // Either authenticated or properly rejecting — session layer is alive
        https.get(HEARTBEAT_URL, () => {}).on('error', () => {});
    } else {
        console.error(`Session check failed: ${res.statusCode}`);
    }
}).on('error', (err) => {
    console.error('Session check error:', err.message);
});

Add to cron:

*/5 * * * * /usr/bin/node /opt/puter/session-check.js

In Vigilmon, create a Push / Heartbeat monitor with 10 minute expected interval.

Step 6: SSL Certificate Expiry Alerts

Puter loads in the browser, which enforces TLS strictly. An expired certificate means users see a browser security warning and cannot connect.

Open the HTTP monitor from Step 1.
Enable Monitor SSL certificate.
Set Alert when certificate expires in less than 21 days.
Click Save.

Verify your certificate renewal setup:

# Check current certificate expiry
echo | openssl s_client -connect puter.yourdomain.com:443 2>/dev/null | \
  openssl x509 -noout -enddate

# Test Certbot auto-renewal
certbot renew --dry-run

# Or check Caddy logs
journalctl -u caddy -n 50 | grep -i "certificate\|renew\|error"

Step 7: Configure Alert Channels

Go to Alert Channels in Vigilmon and connect Slack, email, or a webhook.
Set Consecutive failures before alert to 2 on the web server and API monitors — Node.js startup and garbage collection can cause brief gaps.
Alert on the first failure for SSL and heartbeat monitors.
Pause alerts during Puter upgrades:

# Create maintenance window before updating
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "YOUR_MONITOR_ID", "duration_minutes": 10}'

# Pull and restart Puter
git -C /opt/puter pull
npm install --prefix /opt/puter
pm2 restart puter

# Window expires automatically after 10 minutes

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web server | Root URL | Node.js crash, UI unavailable | | API endpoint | /api/v1/ | Backend failure, users can't open files | | File system | FS API heartbeat | Storage layer failure | | TCP port | :443 or :4100 | Proxy or process down | | Session backend | Session heartbeat | Auth/session store failure | | SSL certificate | Puter domain | TLS expiry blocking browser access |

Puter gives users a full cloud desktop experience on your own infrastructure. Vigilmon makes sure that infrastructure stays online — so your users' desktops, files, and sessions are there whenever they open a browser tab.