VPS Guardian

Autonomous VPS monitoring and auto-remediation — kills runaway procs, frees disk, restarts dead services, hardens security. Not alerts. Action.

VPS Guardian — Self-Healing Server Agent

What It Does

VPS Guardian doesn't just alert you when something's wrong — it fixes it. An autonomous agent that monitors your VPS and takes action: killing runaway processes, freeing disk space, restarting dead services, and hardening security.

Philosophy: Alerts are for humans. Guardians act.

Quick Start

Install

bash

# Download
sudo curl -o /usr/local/bin/vps-guardian https://raw.githubusercontent.com/vps-guardian/guardian/main/src/guardian.py
sudo chmod +x /usr/local/bin/vps-guardian

# Configure (optional — defaults are sensible)
sudo cp /usr/local/bin/vps-guardian.conf.example /etc/vps-guardian.conf

Run

bash

# One-shot scan + remediate
vps-guardian --scan

# Daemon mode (continuous monitoring)
vps-guardian --daemon

# Dry run (report only, no action)
vps-guardian --dry-run

Schedule with Cron

bash

# Every 5 minutes
*/5 * * * * /usr/local/bin/vps-guardian --scan >> /var/log/vps-guardian.log 2>&1

What It Fixes

1. Runaway Processes

• Detects processes consuming >90% CPU for 5+ minutes
• Identifies zombie processes (state Z)
• Finds OOM candidates (highest RSS on low memory)
• Action: SIGTERM, then SIGKILL after 10s if unresponsive
• Logs PID, command, CPU%, memory%, and duration before killing

2. Disk Space Recovery

• Warns at 80% usage, acts at 90%
• Rotates logs older than 7 days (gzip)
• Clears /tmp files older than 3 days
• Removes orphaned apt caches
• Truncates journal logs >500MB
• Action: Sequential cleanup until below threshold
• Logs bytes freed and what was cleaned

3. Dead Service Restart

• Monitors critical systemd services
• Detects failed/inactive states
• Attempts systemctl restart up to 3 times
• Escalates to alert after 3 failures
• Action: Auto-restart with exponential backoff (5s, 30s, 120s)

4. Security Hardening

• Detects unexpected listening ports (diffs against baseline)
• Identifies brute-force SSH attempts (fail2ban integration)
• Flags world-writable files in /etc, /root
• Checks for suspicious processes (crypto miners, reverse shells)
• Action: Blocks IPs via iptables, chmods files, kills suspicious processes
• Never auto-blocks — always requires approval (prevents lockout)

5. Memory Recovery

• Detects memory pressure (available <10%)
• Identifies top memory consumers
• Clears page cache, dentries, inodes
• Action: Cache drop first, process kill as last resort

Configuration

ini

# /etc/vps-guardian.conf

[thresholds]
cpu_kill_percent = 90
cpu_kill_duration = 300
disk_warn_percent = 80
disk_act_percent = 90
memory_act_percent = 90
zombie_kill = true

[services]
# Services to auto-restart when down
critical = ssh, cron, systemd-resolved, rsyslog
# Services to monitor but NOT auto-restart
watched = nginx, docker, fail2ban

[security]
block_bruteforce = true
max_ssh_failures = 10
scan_suspicious_procs = true
auto_block = false    # Always requires approval

[cleanup]
rotate_logs_days = 7
tmp_max_age_days = 3
journal_max_size_mb = 500
apt_cache_clean = true

[alerts]
telegram_bot_token =
telegram_chat_id =
webhook_url =

Exit Codes

Code	Meaning
0	Healthy — no issues found
1	Remediated — fixed issues, all clear now
2	Critical — unrecoverable issues remain
3	Error — guardian itself failed

Logging

All actions are logged with before/after state:

text

[2026-04-17T06:30:00Z] RUNAWAY pid=4523 cmd="node server.js" cpu=94.2% mem=1.2G duration=420s → SIGTERM → exited
[2026-04-17T06:30:05Z] DISK / 92% → rotated /var/log/syslog.1 (freed 340MB) → 87%
[2026-04-17T06:30:10Z] SERVICE ssh: inactive → restarted → active
[2026-04-17T06:30:15Z] SECURITY 5 SSH failures from 45.33.xx.xx → blocked via iptables

Safety Mechanisms

• Protected processes: Never kills pid 1, kernel threads, or self
• Protected services: Never restarts systemd itself
• Rate limiting: Max 5 process kills per scan cycle
• Dry run mode: --dry-run shows what would happen without acting
• Whitelist: Exclude processes/services from remediation
• Approval gate: Security actions always require confirmation

Requirements

• Linux (systemd-based)
• Python 3.8+
• Root or sudo access
• No external dependencies (stdlib only)

Differences from Monitoring Tools

Feature	Traditional Monitoring	VPS Guardian
Detects issues	Yes	Yes
Sends alerts	Yes	Yes
Fixes issues	No	Yes
Requires human	Yes	No (configurable)
Runs autonomously	No	Yes
Learns baselines	Sometimes	Yes (over time)

Support

• Issues: https://github.com/vps-guardian/guardian/issues
• Docs: https://vps-guardian.io/docs