ai-monitor-api

Lightweight REST API for infrastructure monitoring — health checks, system metrics, alerting. Zero dependencies, pure Node.js.

Features

• 🔍 HTTP health checks — verify URLs return 2xx/3xx with latency tracking
• 🌐 TCP port checks — test reachability of any host:port
• 📊 System metrics — CPU usage, memory, load average, uptime, network interfaces
• 🔔 Alert rules — define threshold rules (CPU > 90%, RAM > 85%, etc.) with history
• 📦 Zero dependencies — pure Node.js stdlib, no npm install needed
• 🔑 Optional API key auth — secure with API_KEY env variable
• 🚀 Single file — server.js is self-contained, easy to audit

Quick Start

# Install globally
npm install -g ai-monitor-api

# Start the server
ai-monitor start --port=7420

# Or with auth
API_KEY=mysecret ai-monitor start --port=7420

# Check server status
ai-monitor status

# Check an HTTP endpoint
ai-monitor check http https://example.com

# Check TCP port
ai-monitor check tcp 192.168.1.1 22

# Show system metrics
ai-monitor metrics

API Endpoints

GET /ping

Simple liveness check.

{ "pong": true, "version": "1.0.0", "ts": "2026-02-24T20:00:00.000Z" }

GET /health

Returns 200 (healthy) or 503 (degraded) based on CPU/memory thresholds.

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": "2h 14m 33s",
  "cpu_pct": 12,
  "memory_pct": 45
}

GET /metrics/system

Full system metrics snapshot.

{
  "hostname": "homelab",
  "cpu": { "cores": 16, "usage_pct": 12, "load_avg": { "1m": 0.8, "5m": 1.2, "15m": 1.1 } },
  "memory": { "total_mb": 65536, "used_mb": 29491, "free_mb": 36045, "usage_pct": 45 },
  "uptime": { "seconds": 86400, "human": "1d 0h 0m" }
}

POST /check/http

Check an HTTP/HTTPS endpoint.

// Request
{ "url": "https://myapp.example.com/health", "timeout_ms": 5000 }

// Response
{ "ok": true, "url": "...", "status_code": 200, "latency_ms": 123 }

POST /check/tcp

Check TCP port reachability.

// Request
{ "host": "db.internal", "port": 5432, "timeout_ms": 3000 }

// Response
{ "ok": true, "host": "db.internal", "port": 5432, "latency_ms": 2 }

POST /check/multi

Batch check up to 20 targets.

// Request
{
  "targets": [
    { "url": "https://app1.example.com" },
    { "url": "https://app2.example.com" },
    { "type": "tcp", "host": "redis.internal", "port": 6379 }
  ]
}

// Response
{
  "all_ok": true,
  "count": 3,
  "ok_count": 3,
  "results": [...]
}

Alert Rules

# Register a rule: alert when CPU > 80%
curl -X POST http://localhost:7420/alerts/rule \
  -H "Content-Type: application/json" \
  -d '{"name": "High CPU", "metric": "cpu", "op": ">", "threshold": 80}'

# List rules and alert history
curl http://localhost:7420/alerts

# Delete a rule
curl -X DELETE http://localhost:7420/alerts/rule/rule_1

Available metrics: cpu, memory, load1m
Available operators: >, >=, <, <=

Authentication

Set the API_KEY environment variable to enable bearer token auth:

API_KEY=mysecrettoken ai-monitor start

# Then pass the key in requests:
curl http://localhost:7420/health -H "X-Api-Key: mysecrettoken"
# or
curl http://localhost:7420/health -H "Authorization: Bearer mysecrettoken"

Use Cases

• 🏠 Homelab monitoring — keep an eye on Proxmox containers, VMs, services
• 🤖 AI agent health checks — let agents verify their own infrastructure
• 🔄 CI/CD gate checks — verify services are up before deploying
• 📱 Uptime monitoring — poll from external service (UptimeRobot, Healthchecks.io)
• 🏗️ Microservices watchdog — check dependent services before starting

Library Usage

const { checkHttp, checkTcp, getSystemMetrics } = require('ai-monitor-api');

// Check HTTP endpoint
const result = await checkHttp('https://example.com', 5000);
console.log(result.ok, result.latency_ms);

// Check TCP port
const tcp = await checkTcp('db.internal', 5432, 3000);
console.log(tcp.ok, tcp.latency_ms);

// Get system metrics
const metrics = getSystemMetrics();
console.log(`CPU: ${metrics.cpu.usage_pct}%, RAM: ${metrics.memory.usage_pct}%`);

Self-Hosting with systemd

# /etc/systemd/system/ai-monitor.service
[Unit]
Description=AI Monitor API
After=network.target

[Service]
Type=simple
User=nobody
WorkingDirectory=/opt/ai-monitor-api
ExecStart=/usr/bin/node server.js
Environment=PORT=7420
Environment=API_KEY=changeme
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

systemctl enable --now ai-monitor

License

MIT — free for personal and commercial use.

Built by OpenClaw — AI agent infrastructure automation.