Agent skill

vps

Direct VPS operations via SSH MCP. Manage Docker containers, check logs, run commands, and troubleshoot services on registered VPS servers.

View SKILL.md on GitHub Repository
Stars 6
Forks 3

Install this agent skill to your Project

npx add-skill https://github.com/BerryKuipers/claude-code-toolkit/tree/main/.claude/skills/infrastructure/vps

SKILL.md

VPS Operations Skill

Direct SSH access to VPS servers for container management and troubleshooting.

Usage

bash
/vps                           # Show VPS status for current project
/vps status                    # Container status + resource usage
/vps logs <service>            # View service logs (tail -100)
/vps logs <service> --follow   # Stream logs
/vps exec '<command>'          # Execute arbitrary command on VPS
/vps restart <service>         # Restart specific container
/vps health                    # Run health checks on all services
/vps resources                 # Show CPU, memory, disk usage
/vps backup                    # Backup database to NAS

Project Detection

Reads project from:

  1. Current git remote URL
  2. deployments.registry.json lookup

Common Operations

Container Management

bash
# List all containers
ssh ${USER}@${HOST} "docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"

# Restart service
ssh ${USER}@${HOST} "docker compose -f ${COMPOSE_PATH} restart ${SERVICE}"

# View logs
ssh ${USER}@${HOST} "docker logs ${CONTAINER} --tail 100"

# Execute in container
ssh ${USER}@${HOST} "docker exec ${CONTAINER} npm run db:migrate"

Health Monitoring

bash
# System resources
ssh ${USER}@${HOST} "free -h && df -h && uptime"

# Docker resource usage
ssh ${USER}@${HOST} "docker stats --no-stream"

# Nginx status
ssh ${USER}@${HOST} "sudo systemctl status nginx"

# Active connections
ssh ${USER}@${HOST} "netstat -an | grep ESTABLISHED | wc -l"

Database Operations

bash
# Backup database
ssh ${USER}@${HOST} "docker exec ${DB_CONTAINER} pg_dump -U postgres ${DB} > /backup/${DB}_$(date +%Y%m%d).sql"

# Copy backup to NAS
scp ${USER}@${HOST}:/backup/${DB}_*.sql berry@10.0.0.23:/volume1/backups/

# Check database connections
ssh ${USER}@${HOST} "docker exec ${DB_CONTAINER} psql -U postgres -c 'SELECT count(*) FROM pg_stat_activity;'"

Troubleshooting

bash
# Check for OOM kills
ssh ${USER}@${HOST} "dmesg | grep -i 'out of memory' | tail -10"

# Check docker events
ssh ${USER}@${HOST} "docker events --since '1h' --until 'now'"

# Check failed services
ssh ${USER}@${HOST} "docker ps -a --filter 'status=exited' --format '{{.Names}}: {{.Status}}'"

Safety

  • NEVER run pkill node - will kill Claude Code
  • NEVER run destructive commands without confirmation
  • ALWAYS check what you're about to do with --dry-run first
  • Use docker compose restart instead of killing containers

MCP Tool Reference

mcp__project-vps__exec    # Execute commands on project VPS
mcp__home-nas__exec       # Execute commands on home NAS

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

BerryKuipers/claude-code-toolkit

validate-typescript

Run TypeScript compiler type-checking (tsc --noEmit) to validate type safety and catch type errors. Returns structured output with error counts, categories (type/syntax/import errors), and affected files. Used for quality gates and pre-commit validation.

6 3
Explore
BerryKuipers/claude-code-toolkit

validate-coverage-threshold

Validate test coverage meets minimum thresholds (default 80% overall, 80% statements, 75% branches, 80% functions). Parses coverage reports from coverage/coverage-summary.json or test output. Returns pass/fail status with detailed metrics and identifies uncovered files.

6 3
Explore
BerryKuipers/claude-code-toolkit

quality-gate

Comprehensive quality validation for TypeScript/JavaScript projects - runs TypeScript checks, tests, coverage analysis, build validation, and linting with structured JSON results

6 3
Explore
BerryKuipers/claude-code-toolkit

run-comprehensive-tests

Execute comprehensive test suite (Vitest/Jest) with coverage reporting and failure analysis. Returns structured output with test counts (total/passed/failed), coverage percentage, duration, and detailed failure information. Used for quality gates and CI/CD validation.

6 3
Explore
BerryKuipers/claude-code-toolkit

validate-build

Run production build validation (npm run build, vite build, tsc) to ensure code compiles and builds successfully. Returns structured output with build status, duration, size metrics, and error details. Used for quality gates and deployment readiness checks.

6 3
Explore
BerryKuipers/claude-code-toolkit

validate-lint

Run ESLint and Prettier validation to check code style, formatting, and best practices. Returns structured output with error/warning counts, rule violations, and affected files. Used for code quality gates and pre-commit validation.

6 3
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results