kvm-pilot

kvm-pilot

为 AI Agent 提供现场操作能力。 一个支持写操作的多平面 （KVM + BMC + SSH）MCP 服务，可控制物理机器 — 设有门控、经过验证、全程审计。

kvm-pilot 让 Agent 无需在目标机器上运行 Agent，即可驱动无头设备完成从 POST、固件、引导加载程序到 OS 安装的整个过程：它通过 IP-KVM（PiKVM、GL.iNet GLKVM 分支 GL-RM1 / GL-RM1PE、BliKVM）在像素层面操作；通过 BMC（iDRAC/iLO/OpenBMC 上的 Redfish，以及早于 Redfish 的 BMC 上的 IPMI）读取结构化状态；通过 Intel AMT/vPro 在固件层面操作（可在一台商务笔记本上获取 BIOS/POST/GRUB 截图、控制电源并使用 SOL，而 HDMI 采集式 KVM 无法看到其启动过程）；OS 启动后则通过 SSH 操作。可插拔的视觉子系统会读取 KVM 截图并告知机器所处的启动阶段 — bios_menu、grub_menu、installer_progress、login_prompt、crash_screen 等；安全层则要求操作员主动启用，并对每次调用进行批准，以此门控所有破坏性操作。

视觉功能可使用 Claude，也可使用任何兼容 OpenAI 的本地 VLM（LM Studio、 Ollama、vLLM、llama.cpp）。将其指向自有 GPU 上的模型，截图就不会离开你的网络，而且每帧都无需付费。

工作原理

kvm-pilot 运行一个观察 → 决策 → 执行循环，屏幕是它唯一的传感器： 它从 KVM 获取截图，由视觉模型对启动阶段进行分类，然后 kvm-pilot 通过 KVM 的键盘和电源功能执行操作。由于它在像素层面工作，目标机器上无需运行 Agent — 同一个循环可驱动 POST、固件、引导加载程序和 OS 安装。

这是在家庭设备集群中的 GLKVM 上运行的一次真实、未经编辑的演示 — 诚实的预检、无头快照（看它唤醒按需编码器）、设有门控的干运行电源循环，以及 Agent 实际看到的启动控制台：

快速开始

安装一次即可获取完整产品 — kvm-pilot CLI、kvm-pilot-mcp MCP 服务和内置的 Claude 技能 — 无需克隆。

pip install kvm-pilot                          # CLI + skill + MCP server + WebSocket events
pip install "kvm-pilot[totp]"                  # + 2FA / TOTP support (pyotp)
kvm-pilot install-skill                        # optional: put the bundled skill where Claude Code loads it

使用 AI Agent 驱动 KVM（MCP）

claude mcp add kvm-pilot -s user \
    -e KVM_PILOT_PROFILE=mykvm -e KVM_PILOT_MCP_READ_ONLY=1 -- \
    kvm-pilot-mcp

KVM_PILOT_MCP_READ_ONLY=1 是信任阶梯上推荐的第一步 ——Agent 可以查看所有内容，但不能进行任何操作，直到你验证硬件。 入门指南 介绍了凭据、Claude Desktop JSON 配置、示例提示词，以及如何逐步提升权限。该服务已发布到官方 MCP 注册表， 名称为 io.github.DustinTrap/kvm-pilot，因此支持注册表的主机可以按名称发现并安装它。Agent：仓库根目录中附有 llms.txt 文档索引。

使用 Python 编写脚本

from kvm_pilot import KVMClient
from kvm_pilot.vision import ScreenAnalyzer, make_backend

kvm = KVMClient("192.168.8.1", "admin", "secret")

# Classify the current screen with Claude (model auto-resolved at runtime)
analyzer = ScreenAnalyzer(kvm, make_backend("anthropic"))
print(analyzer.classify().phase)

# Or run entirely on a local VLM — nothing leaves your network
local = make_backend("local", base_url="http://127.0.0.1:1234/v1", model="qwen2.5-vl-7b")
analyzer = ScreenAnalyzer(kvm, local)

# Block until the box reaches the GRUB menu, then pick the first entry
analyzer.wait_for_state("grub_menu", timeout=120)
kvm.press_key("Enter")

对于最新的未发布代码：

pip install "kvm-pilot[totp] @ git+https://github.com/DustinTrap/kvm-pilot"

命令行界面

kvm-pilot info     --host 192.168.8.1 --user admin --ask-passwd   # prompt (no echo)
kvm-pilot capabilities --profile homelab                 # what this driver supports
kvm-pilot snapshot screen.jpg --profile homelab
kvm-pilot --timeout 60 power-cycle --profile homelab --dry-run   # log, don't send
kvm-pilot eject --profile homelab                        # detach virtual media
kvm-pilot events --profile homelab --count 5             # stream device events
kvm-pilot watch grub_menu --profile homelab \
    --backend local --vision-url http://127.0.0.1:1234/v1 --vision-model qwen2.5-vl-7b

在执行任何破坏性操作之前，命令行界面都会要求确认（电源、虚拟介质——包括上传——键盘/鼠标注入、GPIO）。自动化场景中可使用 --yes 跳过提示，或使用 --dry-run 记录计划执行的操作而不实际发送——dry-run 会在提示之前短路，因此不会阻塞等待输入。--timeout（HTTP 单次请求超时）是全局标志，必须放在子命令之前；watch 自带 --timeout，用于设置视觉等待期限。

homelab 等配置文件位于 ~/.config/kvm-pilot/config.toml。完整命令表（每个子命令、所需能力及其门控方式）请参阅 docs/cli.md， 配置文件格式、所有 KVM_PILOT_* 环境变量，以及标志、环境变量和配置文件之间的优先级，请参阅 docs/configuration.md。

GLKVM 设置说明：在 GL.iNet 固件上，PiKVM REST API 默认处于禁用状态，固件升级后也可能再次将其禁用——请先启用该 API，参阅 每个 /api/* 调用都返回 404。

按控制平面划分的工具范围

相同的能力协议覆盖三个操作平面，因此一个 Agent 工作流可以混合使用像素、结构化 BMC 状态和 Shell 访问——每种破坏性操作都按类别进行门控：

平面	读取	执行（需操作员授权）
KVM — 像素与 HID（PiKVM · GLKVM · BliKVM）	snapshot · classify_screen · wait_for_state · power_state · logs · list_virtual_media	power · type_text / press_key / send_shortcut / mouse · calibrate_mouse · mount_iso / eject
BMC — 结构化状态（Redfish · IPMI）	info · boot_options · logs（SEL）· 传感器（命令行界面）	power · set_boot_device · SOL 控制台（命令行界面 console）
固件 — Intel AMT/vPro（跨两个平面）	info · snapshot（固件 BIOS/POST/GRUB）· boot_options · power_state	power · set_boot_device · type/mouse · SOL（console）· amt_enable（打开 SOL/KVM 侦听器）
SSH — 带内与设备端	ssh_reachable · appliance_status · access_paths	ssh_exec · host_exec（自动选择 ssh/winrm）· wake（WoL）· appliance_reboot
元信息 — 证据与提交	capabilities · support_matrix · healthcheck	file_firmware_report

完全没有 KVM 和 BMC 的机器本身也是一类一等目标： driver = "ssh" 加上 ssh_host（机器自身的地址，#248）， 使 kvm-pilot 位于恢复阶梯的带内一阶——所有设备能力都如实标记为不可用，健康检查也会明确指出该机器没有带外恢复路径。

每个工具的权威参考——注释、效果门控、审批生命周期——请参阅 MCP 服务 README； 命令行界面涵盖了完整功能范围，详见 docs/cli.md。

状态与成熟度

状态：1.0，正式发布——此结论以运行记录为依据，不超出记录所支持的范围。三种设备类型已进行过现场运行（GL-RM1PE、通过 iDRAC6/IPMI 连接的 Dell R710、通过 Intel AMT 连接的 Dell Latitude 5411）；七个设备驱动中有三个（redfish、pikvm、blikvm）只在模拟器上运行过。请参阅 硬件兼容性列表，了解实际测试过的内容——也欢迎补充。（确切版本请见 CHANGELOG。） 核心路径已从仅使用模拟对象测试，提升为经过现场验证：一批 GL-RM1PE 设备已在两个固件版本系列上运行过 snapshot/healthcheck/logs/power_state/virtual_media/info——在 V1.9.1 上，随 wheel 提供的运行记录将 info/logs/healthcheck/power_state 标记为 ga，snapshot 标记为 rc，virtual_media 标记为 beta——评级源自真实运行，绝非手动修改；一台 Dell iDRAC6 也已通过 IPMI 驱动完成端到端现场测试 （电源、启动设备、传感器、事件日志、SOL 串行控制台）。可能造成损害的路径都已加固：传输层绝不会再次发送破坏性请求，MCP 审批采用签名的一次性回执并保留审计记录，每种破坏性操作——电源、HID、介质、启动配置、设备、SSH、外部写入——都有各自的操作员选择启用门槛。近期的 beta 版本新增了远程启动设备控制（Redfish、IPMI 和带内 efibootmgr）、Wake-on-LAN、适用于早于 Redfish 的 BMC 的 IPMI 驱动、串行（SOL）控制台、鼠标自动校准，以及无头模式下的原生分辨率 GLKVM 快照；kvm-pilot test-report 可通过一条命令汇总贡献的证据，固件注册表也会自动更新（firmware-check 会自动提交注册表更新）。 现在我们需要你的硬件。 PiKVM、BliKVM、其他 GLKVM 型号和 Redfish BMC（iDRAC/iLO/OpenBMC）是兼容性矩阵最需要的组合——无论成功还是失败，一份 硬件报告 只需两分钟，之后每小时的采集流程会处理其余工作。硬件兼容性列表 中未列为已测试的内容仍未经过验证：1.x 系列会保持公共 API 稳定，但只有现场运行结果发生变化时，评级才会随之更新；请注意，GL-RM1PE 上远程刷写固件会无操作地返回 （#94/#95），也不要对你无法承受意外断电的机器执行破坏性操作。请参阅兼容性。

启动阶段检测

视觉分类器会将每张屏幕截图映射到一个阶段——bios_menu、 grub_menu、installer_progress、login_prompt、crash_screen 等。 wait_for_state() 会轮询屏幕并阻塞，直到出现你指定的阶段（或超时），因此无人值守安装可以拆解为几次等待，并在其间穿插相应操作：

感知模型

视觉是读取屏幕最昂贵的方式——每帧都要调用一次模型——而它推断出的许多信息（电源状态、启动阶段、运行状态、崩溃）也可以通过字段、事件或文本行获取。kvm-pilot 的发展方向是将分类视为一个层级：优先使用设备提供的成本最低的信号进行判断，只有在没有更低成本的方式时，才依次使用 OCR，最后才调用视觉模型。

PiKVM/GLKVM 客户端已提供低成本信号——ATX 和 HID LED、视频信号和分辨率、设备端 OCR（?ocr=true）、日志、Prometheus 指标，以及 WebSocket 事件流。能力协议将 Logs、BootProgress、Sensors、SerialConsole、Watchdog 和 BootConfig 作为 BMC 驱动（Redfish/IPMI）的接入点。在这里，启动阶段是结构化枚举（BootProgress.LastState），而控制台是串口文本流，而不是像素。不同设备类型的优势几乎互补：采集设备擅长处理像素，BMC 擅长提供结构化状态和串口文本。

安全模型

关机、硬重置、连接/断开虚拟媒体及上传映像、键盘/鼠标注入（type_text、press_key、快捷键、点击）、GPIO、启动配置更改，以及 Redfish/IPMI 重置，都被归类为破坏性操作，并经过安全层：

• dry-run 会最先短路：记录计划调用并完全跳过执行——永远不会调用确认回调，因此 dry run 不会提示确认或阻塞。
• 确认——一个可否决任何实际要发送的破坏性调用的回调。库的默认设置是允许所有操作（因此普通脚本可以正常运行）；CLI 会安装交互式 y/N 提示，除非你传入 --yes。

破坏性操作集合在 kvm_pilot.safety.DESTRUCTIVE_OPS 中明确定义，便于审计，而不是靠猜测。视觉分类本身永远不会触发破坏性操作——需要由你自行编写相关逻辑，且安全层仍会生效。在 MCP 侧，每种破坏性效果类别还需要操作员选择启用环境变量开关，并通过有签名的单次使用回执进行逐次调用审批——信任阶梯（READ_ONLY → DRY_RUN → 按效果划分的 ALLOW_*）见 MCP 服务 README。

此软件可控制真实硬件，并可能对正在运行的机器执行电源循环或造成中断。在将 KVM 暴露到互联网之前，请阅读 SECURITY.md。

不硬编码模型版本

代码中没有任何模型版本字符串。Anthropic 后端会在运行时通过 Models API 查找最新的视觉能力模型并缓存；设置 KVM_PILOT_VISION_MODEL 或传入 model= 即可指定固定模型。本地后端使用你在服务器上加载的模型。后端、端点和模型由你自行提供。

与其他客户端的区别

pikvm-lib 是一款出色的通用 PiKVM 客户端。kvm-pilot 则面向不同的用途：

• 基于视觉的启动阶段检测 — 从屏幕截图中识别 BIOS/GRUB/安装程序/崩溃状态，并通过阻塞式 wait_for_state 循环等待。这是其核心功能，而 pikvm-lib 没有同等功能。
• 可插拔的本地或云端 VLM — 可在自己的 GPU 上运行推理，无需承担逐帧费用，也可使用 Claude。
• 针对破坏性操作的安全层（试运行 + 确认）。
• 了解 GLKVM 分支特性 — 说明启用 API 的前置要求，以及会影响 GL-RM1PE 用户的 GL 硬件特性。
• 仅依赖标准库的客户端核心 — 驱动和视觉代码仅导入标准库（捆绑的 MCP 服务需要 mcp SDK；功能扩展需选择性启用）。

如果你只想对原版 PiKVM 编写电源和 HID 控制脚本，并不需要视觉层，那么 pikvm-lib 可能是更简单的选择。

在 BMC 方面，sushy、DMTF 的 python-redfish-library 和 pyghmi（IPMI）都是成熟且功能全面得多的 BMC 管理 SDK。如果你需要配置账户/固件/网络、EventService 订阅，或经过硬件验证的成熟方案，请使用它们。kvm-pilot 以此换取跨设备类别（使用相同协议的 IP-KVM 和 BMC）的统一能力接口、为每个破坏性调用把关的同一安全层，以及适用于带有像素设备的视觉循环。

兼容性

设备	状态
GL-RM1PE（Comet PoE）	主要目标 — 已实机测试：已在固件 V1.5.1 release2 和 V1.9.1 release1 上验证 read/healthcheck/logs；已在 V1.9.1 上验证 snapshot（在 V1.5.1 上会失败并给出明确错误 — H.264 帧无法解码，#107/#151）；远程刷写不执行任何操作（#94/#95）；编码器在分辨率超过 1080p 时会卡死（#107）
Dell iDRAC6 — IPMI（PowerEdge R710）	已实机测试：已通过 ipmitool lanplus（固件 1.95）验证电源、启动设备、传感器、事件日志（SEL）和 SOL 串行控制台
Dell Latitude 5411 — Intel AMT/vPro	已实机测试（AMT 14.1.67）：已验证 WS-Man 电源 / 信息 / 单次启动、远程 SOL + KVM 启用，以及通过 KVM 重定向截取的 1920×1080 BIOS/POST 屏幕截图 — 这是 HDMI 采集式 KVM 无法捕捉到的笔记本固件界面。仅捕捉图形界面（不支持传统 VGA 文本模式）
GL-RM1（Comet）	预计可用（同一固件系列）；尚未测试
PiKVM v3 / v4	预计可用（上游 API）；尚未测试
BliKVM	预计可用（兼容 PiKVM 的 API）；尚未测试
Redfish BMC（iDRAC7+、iLO、OpenBMC）	已通过模拟器验证（仓库内模拟器 + CI 中的 DMTF sushy-tools）；待实机 BMC 验证（#29）

目前已实机测试的组合包括 GL-RM1PE（读取 / 截图路径）、通过 IPMI 连接的 Dell iDRAC6，以及通过 Intel AMT 连接的 Dell Latitude 5411 — 其他设备均为“预计可用”，尚待验证。 硬件兼容性列表 是权威的、按功能记录的兼容性清单。要控制 ATX 电源，必须将 ATX 适配器接到目标设备的前面板接头：在 GL Comet 系列 （GL-RM1 / GL-RM1PE）中，需要另行购买 GL.iNet 的 ATX 板（GL-ATXPC）； PiKVM v3/v4 套件随箱附带 ATX 适配器，而 BliKVM 的配件则因型号而异 — 请确认自己的套件。未接入 ATX 线路时，设备会在收到 ATX 调用后返回错误。无论哪种硬件的成功或失败报告，都是本项目所需要的 — 请提交 硬件报告。

架构

kvm-pilot 采用模块化的驱动插件架构构建，可扩展对多种 KVM/BMC 设备（PiKVM 系列、Redfish BMC、IPMI BMC、JetKVM，……）的支持。每种设备只实现其硬件支持的能力协议；CLI、安全层和视觉子系统则与设备无关。make_driver(kind) 注册表（与 make_backend 相对应）可按名称构建驱动，而无需硬件的 FakeDriver 则让你无需设备即可测试整个流程——包括能力、安全门控和分析器（kvm-pilot capabilities --driver fake）。有关设计和示意图，请参阅 docs/architecture.md。

RedfishDriver（make_driver("redfish")）通过 DMTF Redfish API 与服务器 BMC 通信，支持 Dell iDRAC、HPE iLO、Supermicro、Lenovo XCC 和 OpenBMC，并使用一个仅依赖标准库的客户端。它体现了能力分段的意义：BMC 的能力与 PiKVM 的能力互补（擅长结构化状态——电源、启动阶段、传感器、日志、虚拟媒体——但不支持键盘、鼠标或截图），而驱动通过遵循 Redfish 超媒体规范，而非硬编码厂商 ID，保持可移植性：

from kvm_pilot.drivers import make_driver

bmc = make_driver("redfish", host="idrac.lan", user="root", passwd="…")
bmc.get_boot_progress()        # 'os_running'  — structured, no screenshot
bmc.read_sensors()["temperatures"]
bmc.power_off(wait=True)       # mapped to the target's actual ResetType, gated

IpmiDriver（make_driver("ipmi")）通过系统中的 ipmitool 支持早于 Redfish 的 BMC（例如 Dell iDRAC6），提供电源控制、启动设备控制、传感器、SEL 事件日志和 SOL 串行控制台（kvm-pilot console）。两者也都可通过 CLI 使用，例如 kvm-pilot info --driver redfish --host idrac.lan …。BMC 无法提供的特定能力子命令（type、snapshot、events）会正常报错，而不会导致崩溃。对于没有 SessionService 的端点（模拟器，或禁用了会话身份验证的 BMC），可添加 --redfish-auth basic。

AmtDriver（make_driver("amt")）通过 AMT 的三种原生协议——WS-Man（电源 / 信息 / 单次启动）、SOL（kvm-pilot console）和KVM 重定向——在带外管理 Intel AMT/vPro 笔记本电脑和台式机，且完全仅依赖标准库。它是首个具备 Video + HID 能力的非 PiKVM 驱动：在 HDMI 采集 KVM 无法看到启动过程的笔记本上，snapshot 可返回真实的固件级 BIOS/POST/GRUB 截图。SOL 和 KVM 监听器可通过 WS-Man 远程开启（kvm-pilot amt enable-sol / enable-kvm），无需进入 MEBx。

帮助完善它——这正是你可以出力的地方

kvm-pilot 以开源方式开发。1.0 版基于三种设备类型的证据发布；它目前需要的不是代码，而是更多真实硬件。七个驱动中有三个（redfish、pikvm、blikvm）从未在实体设备上运行过，只在模拟器中测试过。你看到的每项评级都来自随软件包一同发布的运行记录，绝非手动设定，因此只有有人在真实硬件上运行测试，兼容性矩阵才会扩展。这个人可以是你。

**你能提供的最有价值的东西：**一份 硬件报告。 kvm-pilot test-report --profile <name> 可将其变成一条命令即可完成的操作，默认只读，每小时运行的任务会将结果汇总到已发布的兼容性矩阵中。失败和成功同样受欢迎——如果某个驱动在你的 BMC 上给出了很肯定却错误的答案，这份报告比一切正常的报告更有用；它会被视为重要发现，而不会被忽略。

我们也真诚欢迎：

• ⭐ 如果你觉得这个想法对你有用，请为仓库点星。这是表明这个问题值得解决的最简单方式，也能吸引那些拥有矩阵仍然需要测试的硬件的运维人员。
• 🐛 遇到任何问题都可以提交 issue：错误、行为异常的设备、令人困惑的报错，或误导了你的文档。这个仓库采用 每项发现一个 issue 的方式——issue 是记录的基本单位，而“错误消息没告诉我该怎么做”也是合理的报告。
• 💬 **告诉我们它哪里做错了。**审阅安全模型、审批流程和工具接口。对默认设置提出异议。如果某个 Agent 在你的机器上做了让你意外的事，这正是能让其他所有人用得更安全的反馈。
• 🔌 **提出对设备的支持请求。**缺少驱动、不受支持的 BMC，或我们从未听说过的 KVM？请提交驱动请求——插件架构的存在，正是为了让新增驱动不必分叉项目；docs/plugin-development.md 说明了相关约定。
• 🛠️ 提交 PR。docs/CONTRIBUTING.md 列出了 PR 提交前的完整检查清单；适合新手的问题已添加标签。

这里没有任何数据会自动发送回项目。项目没有会主动上报数据的遥测功能——兼容性矩阵中的每一行，都是有人主动选择提交的。这就是我们的原则，也正因如此，你的报告确实重要。

文档

完整的用户和开发者文档位于 docs/（架构、设计决策、Redfish 参考文档、 故障排查与常见问题、 贡献指南和安全政策）。项目 wiki 是该文件夹自动生成、格式清晰的镜像；仓库根目录还提供了供 AI Agent 使用的 llms.txt 文档索引。

许可证

Apache License 2.0——详见 LICENSE 和 NOTICE。kvm-pilot 是独立项目，与 PiKVM 项目、GL.iNet 或 Anthropic 均无关联，也未获其认可；提及这些名称仅用于说明兼容性。