Homelab Runbook

Scan the host machine and generate a Markdown runbook documenting all running services.

Scripts

All scripts are in scripts/. Run with python3 <script>. All output JSON to stdout.

Generating a Runbook

Quickest — run all scanners inline and print to stdout:

python3 scripts/generate_runbook.py

Save to a file:

python3 scripts/generate_runbook.py --output ~/homelab-runbook.md

Save to workspace:

python3 scripts/generate_runbook.py --output /Users/openclaw/.openclaw/workspace/homelab-runbook.md

Pre-collect then generate (useful for cron or piping):

python3 scripts/scan_docker.py > /tmp/docker.json
python3 scripts/scan_services.py > /tmp/services.json
python3 scripts/scan_ports.py > /tmp/ports.json
python3 scripts/generate_runbook.py --docker /tmp/docker.json --services /tmp/services.json --ports /tmp/ports.json --output ~/homelab-runbook.md

Agent Workflow

When the user asks for a homelab runbook or service inventory:

1. Run generate_runbook.py (all scanners inline, save to workspace file).
2. Read the output file and summarize key findings:
   • How many Docker containers are running and what they are
   • Notable open ports and the processes owning them
   • Any errors or warnings (Docker not found, permission denied, etc.)
3. Offer to save to Obsidian vault if the user wants it persisted.

Use the --output flag to write to the workspace. Do not dump the full raw Markdown at the user — summarize it and offer the file path.

Edge Cases

• Docker not installed: scan_docker.py returns {"error": "Docker not installed or not running", "containers": []} — runbook shows a warning, continues.
• No containers running: Returns empty list, runbook shows "No running containers."
• Port scan permission denied: scan_ports.py returns an error — runbook shows warning. Tell the user to re-run with sudo if full port visibility is needed.
• Linux without systemd: scan_services.py will return an error — acceptable, runbook notes it.

Customization

See references/customization.md for:

• Excluding specific services/containers/ports
• Adding manual service notes (URLs, config paths, restart commands)
• Scheduling with cron
• Modifying output format