How do I install the Infra Runbook skill?

Run npx skillmds@latest add kevinzai/infra-runbook in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Infra Runbook safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Infra Runbook?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Infra Runbook free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Infra Runbook?

KevinZai (@kevinzai) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Infra Runbook by kevinzai — Agent Skill

Name: Infra Runbook
Author: KevinZai

Infra Runbook

Infrastructure runbooks for Kevin's self-hosted stack. Covers common failure modes, diagnosis steps, and recovery procedures for: OpenClaw Gateway, Paperclip, BlueBubbles, n8n, Langfuse, Caddy, Ollama, PM2, Docker, and Tailscale. Use when something is down, slow, or behaving unexpectedly.

KevinZai 890be74 2.7 KB Updated Sep 17, 2026

File contents

Infrastructure Runbook

Quick Diagnosis

# What's running?
pm2 jlist | jq -r '.[] | "\(.name)\t\(.pm2_env.status)\t\(.pm2_env.restart_time)"'

# What's listening?
lsof -iTCP -sTCP:LISTEN -nP | grep -E ":(18789|3110|5678|3100|11434|1234)" | awk '{print $1, $9}'

# Disk pressure?
df -h /System/Volumes/Data | tail -1

Service-Specific Runbooks

OpenClaw Gateway (:18789)

Symptom: Agents not responding, messages not flowing

# Check status
curl -s http://localhost:18789/health  # NOTE: /health not /api/health
# Check logs
openclaw gateway status
# Restart (REQUIRES KEVIN'S APPROVAL)
openclaw gateway restart

Common causes: Config error after patch, OOM, node crash

Paperclip (:3110)

Symptom: Tickets not creating, API 500s

pm2 show paperclip
pm2 logs paperclip --lines 30 --nostream
# Restart
pm2 restart paperclip

Common causes: SQLite lock, port conflict (OrbStack), migration needed

BlueBubbles (:1234)

Symptom: iMessage not working, 401 errors (normal — needs auth), no response at all (bad)

# Check if alive
curl -s http://localhost:1234/api/v1/server/info -H "Authorization: Bearer $BB_PASSWORD"
# Force restart
killall -9 BlueBubbles; sleep 2; open -a BlueBubbles

Common causes: macOS killed it, port stuck after crash

n8n (:5678)

Symptom: Workflows not triggering

pm2 show n8n 2>/dev/null || docker ps | grep n8n
pm2 logs n8n --lines 20 --nostream

Langfuse (:3100)

Symptom: Observability blind

curl -s http://localhost:3100/api/health
docker ps | grep langfuse
docker logs langfuse-web --tail 20

Caddy (Reverse Proxy)

Symptom: HTTPS not working, domains not resolving

# Check config
cat ~/your-infra/caddy/Caddyfile | grep -E "^[a-z].*\{" | head -20
# Reload
caddy reload --config ~/your-infra/caddy/Caddyfile
# Check TLS certs
caddy validate --config ~/your-infra/caddy/Caddyfile

Common causes: Cloudflare DNS token expired, config syntax error

Ollama (:11434)

Symptom: Local models not responding

curl -s http://localhost:11434/api/tags | jq '.models[].name'
ollama list
# Restart
killall ollama; sleep 1; ollama serve &

Escalation

If you can't fix it:

Write diagnostic output to ~/reports/architecture/incident-YYYYMMDD.md
Post to #morpheus with findings
Tag Kevin if it's blocking work

---name: infra-runbookdescription: Infrastructure runbooks for Kevin's self-hosted stack. Covers common failure modes, diagnosis steps, and recovery procedures for: OpenClaw Gateway, Paperclip, BlueBubbles, n8n, Langfuse, Caddy, Ollama, PM2, Docker, and Tailscale. Use when something is down, slow, or behaving unexpectedly.---# Infrastructure Runbook## Quick Diagnosis```bash# What's running?pm2 jlist | jq -r '.[] | "\(.name)\t\(.pm2_env.status)\t\(.pm2_env.restart_time)"'# What's listening?lsof -iTCP -sTCP:LISTEN -nP | grep -E ":(18789|3110|5678|3100|11434|1234)" | awk '{print $1, $9}'# Disk pressure?df -h /System/Volumes/Data | tail -1```## Service-Specific Runbooks### OpenClaw Gateway (:18789)**Symptom:** Agents not responding, messages not flowing```bash# Check statuscurl -s http://localhost:18789/health # NOTE: /health not /api/health# Check logsopenclaw gateway status# Restart (REQUIRES KEVIN'S APPROVAL)openclaw gateway restart```**Common causes:** Config error after patch, OOM, node crash### Paperclip (:3110)**Symptom:** Tickets not creating, API 500s```bashpm2 show paperclippm2 logs paperclip --lines 30 --nostream# Restartpm2 restart paperclip```**Common causes:** SQLite lock, port conflict (OrbStack), migration needed### BlueBubbles (:1234)**Symptom:** iMessage not working, 401 errors (normal — needs auth), no response at all (bad)```bash# Check if alivecurl -s http://localhost:1234/api/v1/server/info -H "Authorization: Bearer $BB_PASSWORD"# Force restartkillall -9 BlueBubbles; sleep 2; open -a BlueBubbles```**Common causes:** macOS killed it, port stuck after crash### n8n (:5678)**Symptom:** Workflows not triggering```bashpm2 show n8n 2>/dev/null || docker ps | grep n8npm2 logs n8n --lines 20 --nostream```### Langfuse (:3100)**Symptom:** Observability blind```bashcurl -s http://localhost:3100/api/healthdocker ps | grep langfusedocker logs langfuse-web --tail 20```### Caddy (Reverse Proxy)**Symptom:** HTTPS not working, domains not resolving```bash# Check configcat ~/your-infra/caddy/Caddyfile | grep -E "^[a-z].*\{" | head -20# Reloadcaddy reload --config ~/your-infra/caddy/Caddyfile# Check TLS certscaddy validate --config ~/your-infra/caddy/Caddyfile```**Common causes:** Cloudflare DNS token expired, config syntax error### Ollama (:11434)**Symptom:** Local models not responding```bashcurl -s http://localhost:11434/api/tags | jq '.models[].name'ollama list# Restartkillall ollama; sleep 1; ollama serve &```## EscalationIf you can't fix it:1. Write diagnostic output to `~/reports/architecture/incident-YYYYMMDD.md`2. Post to #morpheus with findings3. Tag Kevin if it's blocking work

Frequently asked questions