# vps-forge

> An open Agent Skill that lets AI coding agents set up, harden and audit Debian and Ubuntu VPS servers with automatic rollback on risky changes.

vps-forge is an MIT-licensed Agent Skill, published under the GitHub handle mountain-beaver, that teaches AI coding agents to set up and harden Debian and Ubuntu VPS servers. It covers SSH, firewall, fail2ban, updates, Docker, TLS, backups and phone alerts. The latest listed release is v1.1.1.

## What It Is

vps-forge follows the Agent Skills (SKILL.md) format and works with agents that can load skills and run shell commands, such as Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. The user describes the server in plain language, for example a new VPS for a Docker app with backups and alerts. The agent asks a few short questions, shows a plan and works through it phase by phase. It can also run read-only audits, or do only a narrow request such as moving SSH to another port.

## The dead-man switch

Every SSH, firewall, sudo or PAM change runs inside a dead-man switch. The switch snapshots the configuration and starts a systemd timer, 5 minutes by default. The agent then makes and validates the change and logs in again over a new connection. Only a successful login disarms the timer; otherwise the snapshot is restored, including after a reboot. The README notes that it cannot undo changes made outside the server, such as a provider's firewall panel. The switch is a plain bash script that can also be used without an agent.

## What the finished server looks like

- Key-only SSH with an admin user, root and password logins off, and modern SSH crypto.
- A default-deny firewall (ufw or nftables) with IPv4/IPv6 parity and Docker-aware rules.
- fail2ban, unattended security updates, and Caddy or nginx with TLS.
- restic backups with a restore test, phone alerts through ntfy, Telegram or webhook, and a SERVER.md documenting open ports.

Three hardening levels (baseline, hardened, paranoid) and profiles (web, docker, vpn, db, worker, game) control how far it goes.

## Benchmark and limits

The author reports 120 runs of Claude Opus 5.5 on real QEMU VMs, scored from outside by a judge written by the same author. The README states that most of the score gap comes from the skill's own defaults. It also notes that the skill makes runs slower and costlier, and that other agents and models have not been fully tested.

## Setup path

Install with the open skills installer (npx skills add mountain-beaver/vps-forge -g), as a Claude Code plugin, through the GitHub CLI, by uploading a zip to Claude.ai, or by copying the folder. In chat apps without a shell it works in script mode, where the user runs the scripts. The bundled scripts (audit.sh, deadman.sh, external-check.sh, install-alerts.sh) also run standalone.

## Features
- Agent Skill for Debian and Ubuntu VPS setup, hardening and audits
- Dead-man switch that automatically rolls back risky SSH, firewall, sudo and PAM changes
- Read-only audit script with 70+ checks, score and JSON output
- SSH hardening with key-only access and ssh-audit-clean crypto
- Firewall setup with ufw or nftables and Docker-aware rules
- fail2ban configuration with recidive jail
- Unattended security updates
- Caddy or nginx with TLS and security headers
- restic backups with a tested restore
- Phone alerts via ntfy, Telegram or webhook
- Outside-in external check script
- Hardening levels: baseline, hardened, paranoid
- Profiles: web, docker, vpn, db, worker, game
- Script mode for chat apps without shell access
- SERVER.md documentation and cloud-init export

## Integrations
Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Antigravity, Windsurf, Cline, Amp, Roo Code, Claude.ai, Docker, Caddy, nginx, fail2ban, restic, Tailscale, CrowdSec, ntfy, Telegram, Coolify, Dokploy, CapRover, Kamal, Dokku

## Platforms
MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v1.1.1

## Links
- Website: https://github.com/mountain-beaver/vps-forge
- Documentation: https://github.com/mountain-beaver/vps-forge#readme
- Repository: https://github.com/mountain-beaver/vps-forge
- EveryDev.ai: https://www.everydev.ai/tools/vps-forge