vpsbot

Owner-only Discord bot that reports local host metrics and service-catalog probes (Docker stacks, HTTP/DNS/Minecraft, deploy timers) via slash commands. Intended to run on the VPS you want to monitor — it reads the machine it is installed on (psutil, optional docker / systemctl / dig / sensors).

Service-aware commands and the YAML catalog are documented in docs/SERVICE-COMMANDS.md.

Requirements

• Python 3.11+
• uv
• Discord bot token

Optional (features degrade gracefully if missing):

• docker CLI — /docker, /status, /stack, /mc
• systemctl — /services, /deploys
• dig — /dns and catalog DNS checks
• Host temperature sensors (via psutil; often needs lm-sensors) and/or nvidia-smi — /temp
• Repo-root or /opt/vpsbot/services.yaml — service catalog for stack probes

Environment

Copy .env.example to .env and fill in:

Variable	Required	Description
DISCORD_TOKEN	yes	Bot token from the Discord Developer Portal
OWNER_DISCORD_ID	yes	Your Discord user ID (snowflake). Only this user can run commands
DISCORD_GUILD_ID	no	Guild ID for fast slash-command sync during development. Omit for global sync
STATUS_GUILD_ID	no	Guild for the live status board + error alerts. Default: 1169989749415616512. Set off to disable
STATUS_CHANNEL_ID	no	Channel for the live status board + error alerts. Default: 1533247191890661439. Set off to disable
STATUS_INTERVAL_SECONDS	no	Live board refresh interval (default 300, min 60)
WATCH_SERVICES	no	Comma-separated systemd unit names without .service. Default: ssh,docker,cdn-webhook,vpsbot
WATCH_TIMERS	no	Comma-separated timer unit names. Default: cdn-autodeploy.timer,farmr-autodeploy.timer,certbot.timer
SERVICES_CATALOG	no	Path to services.yaml. Defaults to /opt/vpsbot/services.yaml or repo-root services.yaml

Local development

uv sync
cp .env.example .env   # then edit
uv run vpsbot

Discord setup

1. Create an application at Discord Developer Portal → Bot → Reset/Copy Token → set DISCORD_TOKEN.
2. Enable Developer Mode in Discord (User Settings → Advanced). Right-click your user → Copy User ID → set OWNER_DISCORD_ID.
3. Invite the bot with scopes applications.commands and bot (no privileged intents required; default intents only).

Slash commands

All commands are ephemeral and restricted to OWNER_DISCORD_ID.

Command	Description
/vps	Overview: host, uptime, load, CPU, RAM, root disk; stack ok count when catalog loaded
/cpu	Overall / per-core usage, frequency, load averages
/memory	RAM and swap
/disk	Disk usage by mount
/network	Interfaces (IPv4, RX/TX) and public IP (ipify)
/docker	Containers via docker ps / docker stats, grouped by catalog
/services	WATCH_SERVICES units and WATCH_TIMERS
/top	Top processes by CPU and by memory
/temp	Hardware temperatures (psutil sensors + optional NVIDIA)
/status	Traffic-light status for all catalog services
/stack	Detailed status for one catalog service
/http	All catalog HTTP health probes
/mc	Minecraft Pumpkin health
/deploys	Autodeploy timers and recent deploy logs
/dns	Authoritative DNS dig summary

See docs/SERVICE-COMMANDS.md for catalog schema, probe URLs, and VPS permissions.

VPS systemd install

Install under /opt/vpsbot using deploy/vpsbot.service.

# Create service user (docker group for /docker via docker.sock)
sudo useradd --system --home /opt/vpsbot --shell /usr/sbin/nologin vpsbot
sudo usermod -aG docker vpsbot

# Deploy code and deps
sudo mkdir -p /opt/vpsbot
sudo rsync -a --exclude .venv ./ /opt/vpsbot/   # or git clone into /opt/vpsbot
sudo chown -R vpsbot:vpsbot /opt/vpsbot
sudo -u vpsbot bash -c 'cd /opt/vpsbot && uv sync'
sudo -u vpsbot cp /opt/vpsbot/.env.example /opt/vpsbot/.env
# edit /opt/vpsbot/.env as root/vpsbot

# Unit
sudo cp /opt/vpsbot/deploy/vpsbot.service /etc/systemd/system/vpsbot.service
sudo systemctl daemon-reload
sudo systemctl enable --now vpsbot
sudo systemctl status vpsbot

The unit runs /opt/vpsbot/.venv/bin/vpsbot as user vpsbot, loads /opt/vpsbot/.env, and adds supplementary group docker.

Layout

pyproject.toml          # package metadata, script entry `vpsbot`
.env.example
services.yaml           # service catalog (stacks, HTTP/DNS/MC probes)
docs/SERVICE-COMMANDS.md
deploy/vpsbot.service   # systemd unit for /opt/vpsbot
src/vpsbot/
  __main__.py           # entry point
  bot.py                # Discord client + command sync
  config.py             # env + catalog loading
  catalog.py            # services.yaml parser
  status.py             # traffic-light aggregation
  checks.py             # owner-only predicate
  formatting.py         # embed helpers
  cogs/stats.py         # host metric slash commands
  cogs/stacks.py        # /status /stack /http /mc /deploys /dns
  collectors/           # system, docker, http, dns, minecraft, deploy logs, …