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.
| Script | Purpose |
|---|
| INLINECODE2 | Running containers: name, image, ports, mounts, status |
| INLINECODE3 |
System services via launchd (macOS) or systemd (Linux) |
|
scan_ports.py | Open TCP listening ports with process and PID |
|
generate_runbook.py | Combine all scans → formatted Markdown runbook |
Generating a Runbook
Quickest — run all scanners inline and print to stdout:
CODEBLOCK0
Save to a file:
CODEBLOCK1
Save to workspace:
CODEBLOCK2
Pre-collect then generate (useful for cron or piping):
CODEBLOCK3
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). - 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
Homelab Runbook
扫描宿主机并生成一份记录所有运行服务的 Markdown 运行手册。
脚本
所有脚本位于 scripts/ 目录下。使用 python3 <脚本名> 运行。所有输出均为 JSON 格式到标准输出。
| 脚本 | 用途 |
|---|
| scandocker.py | 运行中的容器：名称、镜像、端口、挂载、状态 |
| scanservices.py |
通过 launchd (macOS) 或 systemd (Linux) 管理的系统服务 |
| scan_ports.py | 监听中的 TCP 端口及其进程和 PID |
| generate_runbook.py | 合并所有扫描结果 → 格式化的 Markdown 运行手册 |
生成运行手册
最快捷方式——内联运行所有扫描器并输出到标准输出：
bash
python3 scripts/generate_runbook.py
保存到文件：
bash
python3 scripts/generate_runbook.py --output ~/homelab-runbook.md
保存到工作区：
bash
python3 scripts/generate_runbook.py --output /Users/openclaw/.openclaw/workspace/homelab-runbook.md
预先收集再生成（适用于 cron 或管道操作）：
bash
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
代理工作流程
当用户请求 homelab 运行手册或服务清单时：
- 1. 运行 generate_runbook.py（内联所有扫描器，保存到工作区文件）。
- 读取输出文件并总结关键发现：
- 有多少个 Docker 容器正在运行及其详情
- 值得注意的开放端口及其所属进程
- 任何错误或警告（Docker 未找到、权限被拒绝等）
- 3. 如果用户希望持久保存，提供保存到 Obsidian 知识库的选项。
使用 --output 参数写入工作区。不要向用户展示完整的原始 Markdown——应进行总结并提供文件路径。
边界情况
- - Docker 未安装： scandocker.py 返回 {error: Docker 未安装或未运行, containers: []}——运行手册显示警告，继续执行。
- 没有容器运行： 返回空列表，运行手册显示没有运行中的容器。
- 端口扫描权限被拒绝： scanports.py 返回错误——运行手册显示警告。如果需要完整的端口可见性，告知用户使用 sudo 重新运行。
- Linux 没有 systemd： scan_services.py 将返回错误——可接受，运行手册会注明。
自定义
参见 references/customization.md 了解：
- - 排除特定服务/容器/端口
- 添加手动服务备注（URL、配置路径、重启命令）
- 使用 cron 进行调度
- 修改输出格式
