内容
# UTM 监控
**UTM 虚拟机管理** — 自动 IP 发现、远程执行、远程调试和自动升级。内置 MCP 服务器允许任何 AI 代理（Claude Code、Codex、Gemini CLI 等）通过自然语言管理您的虚拟机。
使用 Zig 0.16.0 编写。单个二进制文件，双模式。零外部依赖。
## AI 代理集成（MCP + 技能）
主要功能。经过快速的一次性设置，您的 AI 代理可以通过标准 MCP 协议管理您的虚拟机：
| 工具 | 您的 AI 代理可以执行的操作 |
|------|--------------------------|
| `vm_status` | 发现所有虚拟机：主机名、IP、操作系统/架构、版本、可升级？ |
| `vm_exec` | 在 Linux/macOS/Windows 虚拟机上运行任何 shell 命令 |
## 每日使用示例
```
“启动 lldb 远程调试应用程序“
"检查所有虚拟机的状态"
"在 linuxvm 上运行测试套件"
"将最新版本部署到所有虚拟机"
"显示 windowsvm 上日志的最后 50 行"
"macvm 是否运行最新版本？"
"linuxvm 上什么占用了 CPU？"
"linuxvm 是否可以通过网络访问 windowsvm？"
"在 linuxvm 上创建测试脚本并运行它"
"将配置文件上传到 linuxvm"
"从 windowsvm 下载应用程序日志"
```
## 功能
- **MCP 服务器 + 技能** — AI 驱动的虚拟机管理：发现、执行 — 所有操作均通过自然语言。适用于任何与 MCP 兼容的代理
- **自动 IP 发现** — 访客每秒广播主机名+IP；主机自动监听，忽略 VPN/隧道接口
- **自动 /etc/hosts 同步** — 主机在 IP 更改时更新 hosts 文件标记块，以便 `linuxvm` 始终解析
- **远程命令执行** — `--exec` 向任何虚拟机发送命令，自动适应 macOS/Linux/Windows shell
- **自动版本升级** — 主机通过 UDP 广播检测访客版本不匹配，自动通过 HTTP 推送新二进制文件 — 无需访客轮询
- **HTTP 文件服务** — 访客内置 HTTP 服务器（每个连接一个线程）；文件上传/下载/执行均通过 HTTP
- **文件上传/下载** — `--upload` 和 `--download` 命令替换 curl 进行手动文件传输
- **开机自动启动** — 支持 launchd / systemd / 任务计划程序
- **单个二进制文件，双模式** — 默认访客模式；`--host` 切换到主机模式
## 一次性设置
### 1. 下载和安装（macOS / Linux）
```bash
# 一键安装：下载 utmm.zip，解压到 /opt/utmm/，创建符号链接
curl -fsSL https://raw.githubusercontent.com/fixnet-ai/utm-monitor/main/install.sh | sh
```
安装脚本：
- 从 GitHub Releases 下载 `utmm.zip`（包含所有 8 个平台二进制文件）
- 解压到 `/opt/utmm/`（可通过 `INSTALL_DIR` 配置）
- 为主机创建 `/opt/utmm/utmm` → `utmm-{arch}-{os}` 符号链接
- 创建 `/usr/local/bin/utmm` → `/opt/utmm/utmm` 便捷符号链接
### 2. 下载技能（可选，用于更丰富的代理上下文）
```bash
cd ~/utmm
# 下载技能文件（SKILL.md + MANUAL.md 参考）
mkdir -p utm-vm
curl -o utm-vm/SKILL.md \
https://raw.githubusercontent.com/fixnet-ai/utm-monitor/main/utm-vm/SKILL.md
curl -o utm-vm/MANUAL.md \
https://raw.githubusercontent.com/fixnet-ai/utm-monitor/main/utm-vm/MANUAL.md
```
> 技能文件为您的 AI 代理提供有关虚拟机管理工作流的更丰富上下文。路径约定因代理而异 — 请参阅您的代理文档以设置技能目录。
### 3. 注册 MCP 服务器
`utmm` 二进制文件通过 `--mcp` 内置 MCP 服务器。注册命令取决于您的 AI 代理：
```bash
# Claude Code
claude mcp add utmm -- utmm --mcp
# Codex / 其他与 MCP 兼容的代理 — 配置为 stdio MCP 服务器：
# 命令：utmm
# 参数：["--mcp"]
```
> **集成模式（一体化）：** 使用 `utmm --host --mcp` 代替 — 在单个进程中运行完整的主机 + MCP，无需单独的主机守护进程。
### 4. 启动主机
```bash
sudo utmm --host
```
保持此运行。主机默认从 `/opt/utmm/` 提供二进制文件（所有 8 个平台二进制文件已经存在）。要开机自动启动：
```bash
sudo utmm --install
```
### 5. 验证
```bash
# CLI 测试
utmm --host --status
# MCP 内置 — 使用 ping 测试
printf 'Content-Length: 50\r\n\r\n{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}\n' | utmm --mcp
# → Content-Length: 47
# → {"jsonrpc":"2.0","id":1,"result":{}}
```
完成！现在询问您的 AI 代理：“检查所有虚拟机的状态”。
> **替代：源代码构建** — 如果您更喜欢从源代码构建，请参阅 [MANUAL.md §2](./utm-vm/MANUAL.md#2-installation) 以获取 Zig 构建说明。
## 快速入门（仅 CLI）
```bash
# ─── 主机（您的 Mac）— 始终先部署主机 ───
# 一键安装（下载 utmm.zip，解压到 /opt/utmm/，创建符号链接）
curl -fsSL https://raw.githubusercontent.com/fixnet-ai/utm-monitor/main/install.sh | sh
# 启动主机（需要 sudo 权限以同步 /etc/hosts）
sudo utmm --host --install # 开机自动启动
sudo utmm --host # 或立即运行
# ─── 访客（每个虚拟机内部）— 每个访客一个命令 ───
# 无需互联网 — install.sh 通过默认网关自动检测主机
# Linux 访客（以 root 用户身份）
curl http://$(ip route | grep default | awk '{print $3}'):2121/bin/install.sh | sh -s -- --guest --hostname linuxvm
# macOS 访客（以 root 用户身份 — 注意：macOS 使用 'route' 而不是 'ip route'）
GW=$(route -n get default 2>/dev/null | awk '/gateway/{print $2}')
curl "http://$GW:2121/bin/install.sh" | sh -s -- --guest --hostname macvm
# Windows 访客（以管理员身份）
curl -o install.bat "http://<gateway>:2121/bin/install.bat" && install.bat --guest --hostname windowsvm
# ─── 验证 ───
utmm --host --status # 检查所有虚拟机状态
utmm --host --exec linuxvm "uname -a" # 在虚拟机上运行命令
utmm --host --upload ./f.txt linuxvm # 上传文件到虚拟机（无需 curl）
utmm --host --download linuxvm f.txt ./f.txt # 从虚拟机下载文件（无需 curl）
```
## 文档
| 文档 | 适用于 |
|----------|-----|
| **[MANUAL.md](./utm-vm/MANUAL.md)** | 完整手册：安装、日常使用、故障排除、MCP 设置 |
| **[CLAUDE.md](./CLAUDE.md)** | 开发指南（构建命令、架构、代码风格） |
## 依赖项
- **预编译二进制文件**：零依赖项 — 下载并运行
- **MCP**：通过 `--mcp` 标志内置于二进制文件中。零外部依赖项。
- **源代码构建**：[Zig](https://ziglang.org) 0.16.0
## 架构
```
访客（linuxvm） ──UDP 广播──┐
访客（macvm） ──UDP 广播──┤──→ 主机监听器（12345）
访客（windows） ──UDP 广播──┘ │
├─ /etc/hosts 同步
├─ HTTP 服务器（2121）
├─ IPC（127.0.0.1:12347）
│ ↑
└─ MCP JSON-RPC（stdio）
↑
AI 代理（Claude Code、Codex、...）
```
## 许可证
MIT
