内容
普罗希莫
[](https://github.com/john-broadway/proximo/actions/workflows/ci.yml)
[](https://github.com/john-broadway/proximo/actions/workflows/codeql.yml)
[](https://github.com/john-broadway/proximo/releases)
[](https://pypi.org/project/proximo-proxmox/)
[](./LICENSE)
[](./py)
> **您可以罗希莫钥匙>
> 其他工具在只读检查和完全控制之间做出选择。希莫拒绝这种权所有危险操作都规划**（查看影响验证**（都有不可篡改的记录），并且**可撤销**（在支持快照的平台上）。信任内置，而后添加。 **AI代理钥匙凭证。**
*命名为角斗士中的普罗——他为斗士提供了恰到好处的装备过多，并且对中的每一步都负责就是整个设计：员（人类或代理行动的权限，而不是控制权，并且对所有。*
> *"赢得民众的心，你就会自由。"*
---
##希莫存在xmox VE 拥有完整的 REST API 和简 CLI，但围绕它的 MCP 工具分散且不完整- **基于 API 的** 提供丰富的管理节点、虚拟机、存储），但 **无法在 LXC 中运行命令** ——结构性的缺陷：Pro REST API **没有** 容器执行端点（它存在于 `lxc-attach`、内核命名空间中，没有 REST 接口）。
- **基于 SSH 的 MCP 服务器** 可以在容器中执行命令，但依赖于广泛的 shell 访问权限，缺乏范围控制。
**很少有人构建有原则的 MCP 工具** —— 两个部分都在一个干净上，权限最小化，信赖到足以控制您关心的超平台。 这是普罗希莫的目标。 普罗希莫特定的赌注通过构建** 在整个控制建立信任。
没有 **官方的 Proxmox MCP** （可能在也不会有 —— Prox 提供 API+CLI，并将集成留给社区，就像没有官方的 Terraform 提供商一样）。普罗希莫是一个社区项目，独立存在。
## 它能做什么
用简单的语言询问， *"为什么 ct 105 出现故障？"* —— AI 代理会拉取节点和虚拟机状态，跟踪日志，并在容器内运行诊断程序来查找问题。 如果有修复方法，它会显示计划，然后在修改前进行快照，应用修改，并为您提供一份包含确切更改的签名凭证。
这是产品：**一个 AI 可以操作而不会破坏的超虚拟化平台。** 默认情况下为只读。 没有计划和凭证的修改是不允许的。 它会在修改前进行快照，并在支持快照的平台上提供凭证。
在底层，有两个后端：
| 后端 | 机制 | 适用场景 |
---|
| **管理 Proxmox REST API + 限定范围的 | 节点状态出/检查虚拟机，生命周期（启动/停止） |
| ** | `ssh` → exec` | 在运行命令，`` 便利功能， —— API 无法 |
这两个后端非常 任何人都可以调用 **产品是建立之上的信任层## 信任层 ——罗希莫与
已经有其他针对 Proxmox执行。普罗希莫的独特之处在于 **针对 AI 驱动的基础设施层** —— 四柱：
| 支柱 | 功能 | 状态 |
|---|---|---|
| **计划 默认情况下进行演练：每次返回预览准确的更改机的实时状态，影响范围和风险评估 —— 记录到中。 修改操作无法在计划和记录之前执行。 （这是一个记录的**预览**，而不是单独的人工审批步骤：一个 `confirm=true` 调用记录计划**和**执行更改 —— 因此在代理循环中，您可以自己审查预览。） | ✅ 已构建 + 红队测试 |
验证** | 审计账本；计划都记录在 `audit_verify` 是**防篡改 —— 它可以检测编辑、重新排序和插入账本**默认情况下使用密钥（HMAC-S）**（`IMO_AUDIT_KEY；使用 `off` 退出）。 要捕获截断/伪/完全清除，需要锚点：audit_verify` 的 `" 值在框无法重将其作为_head` 传递设置 `PROXIMOIT_EXPECTED_HEAD—— 这是强有力的保证。 参见下面的说明。 |构建 + 红队测试 |
| **撤销** |构，故障选择性自动快等待，故障关闭，如果存储无法快照）；配置恢复用于虚拟机配置；`pve_rollback` + 完整的虚拟机快照生命周期。 并非所有 PVE 平面都是可快照的 —— 防火墙/SDN/ACL/令牌没有回滚基元 —— 因此撤销覆盖了可快照的表面，而不是每个突变。 撤销点不会自动修剪 —— 使用 `pve_snapshot_delete` 删除。 （快照/回滚是异步的 —— 使用 `pve_task_status` 轮询。） | ✅ 已构建 + 红队测试 |
| **诊断** | 只读证据电池（失败的单元，磁盘，错误，内存，监听端口）+ 节点健康状态（存储/任务）→ 咨询标志。 标志显示**不完整性**，因此空列表从不读取为假阳性。 | ✅ 已构建 + 红队测试 |
> **诚实说明（负载承载）：** 计划的风险评估是一种**咨询启发式**，而不是沙盒。 `LOW` 表示“不更改状态”，**不是**“安全” —— 读取仍然可能造成数据泄露。 没有 `HIGH` 标志**不是**安全信号；破坏模式签名是策划的，而不是详尽的。 自己审查每项更改。
## 大规模应用
一个容器是演示。集群是目标。
- **整个集群在一个调用中。** `pve_cluster_resources` 返回集群中的所有虚拟机、节点、存储池和 SDN 对象 —— 因此代理在一次调用中回答“所有对象的状态是什么？”，而不仅仅是节点。
- **每个节点上的每个更改都有一个防篡改记录。** 这是用户在 CLI 上永远不会得到的：普罗希莫进行的每个更改 —— 任何节点，任何操作员或代理 —— 都记录在一个单一的哈希链 PROVE 账本中，并且 `audit_verify` 证明它没有被编辑、重新排序或截断。 *"显示我这个月集群上的所有状态更改操作，并证明日志没有被篡改"* 成为一个可以实际回答的查询。
## 原则（座右铭，内置 - 不是附加的）
- **合乎道德** —— 最小特权姿态（默认执行关闭；由您范围的令牌限制），每个操作都经过审计，突变确认门控，PVE 令牌仅在调用时读取，绝不记录或持久保存。
- **坚实** —— 真实的测试（单元测试 + 实时测试），类型化，文档齐全，无静默故障。
- **强大** —— 清洁地完成困难的事情（容器执行），最小特权（故障关闭 CTID 允许列表，选择加入）。 （容器执行并不独特 —— 行业领袖也有；区别在于下面的信任层，而不是执行。）
- **热情 + 工艺** —— 在交付前经过红队测试和检查；自豪地交付 —— 文档，许可证，社区就绪。
## 安装和运行
> 🧭 **普罗希莫新手？** 从 **[SETUP.md](SETUP.md)** 开始 —— 一个适合初学者的，基于令牌的逐步指南：
> 创建一个最小特权（只读）令牌，使用 `proximo doctor` 验证它可以/不可以做什么，然后
> 在您准备好时授予限定范围的。 令牌是您的密钥的基准，离开。
> **`0.7` — 已发布 在 [PyPI://pypi.org/project/proxmoxproximo-proxmox`)，
> [](https://githubohn-broadway/proximo/releases/tag/v0.7.4) （CI 通过），和
> [GHCR](https://github.com/john-broadway/proximo/pkgs/container/proximo) （签名多架构镜像）—— 三者都已上线 0.7.4 新增内容：**安全强化** — 私人漏洞报告SECURITY.md以及
> 供应链扫描（pip-audit，Trivy，OpenSSF Scorecard，范围限定 CodeQL）—— 以及 **8 维
> 对抗性信任脊柱审计**，其修复已在此。 **重大** API 后端现在拒绝
> 未验证的 TLS —— 请参阅 [CHANGELOG](./CHANGELOG普罗希在您的机器上运行您的 MCP 客户端所在的位置），**按** —— 就像xmox MCP。
> pip 包是 **`proximo-prox`** （PyPI 的裸 `proximo` 保留）；命令和导入
> 保持 **`` 不变** `[a2a额外功能，您还可以获得 `proximo-a2a` 服务器。
**安装```bash
proximo-proxmox # 零需运行
# 或 install proximo-proxmox `proximo` + `proximo-a2 命令）
# 或 install "proximo-proxmox[a2a]" （还安装 A2A 接口将它连接到您的客户端（Claude Desktop/Code，Cursor，…）作为 `proximo`或 `python -ximo`）， `PROXIMO_*` 环境变量 —— 请 `packaging/proximo.env.example`。
**从源代码：**
```git clone https://github.com/john-broadway/proximo.git && cd proximo
uv pip install -e . # 或：pip install -e .
```
**Docker（）：** `dockeri --rmcr.io/johnway/proximo:latest需运行 stdio —— 无守护开放端口。 多架构（amd64 + arm64），附带 SBOM 和签名存储签名出处证明（`gh attestation verify oci://ghcr.io/john-broadway/proximo --owner john-broadway`）。
> **默认安全：**希莫**默认情况下仅限 API**。 容器执行接口**按需启用**（`PROXIMO_ENABLE_EXEC=1并明确告知您主机上的近权限。
>
> 默认路径**从不触及化主机**通过 Proxmox **API** （令牌）进行。 选择加入的执行接口：它使用您现有的 **ssh**VE 运行 `pct 作为主机上的根用户。 这就是为什么它默认关闭并明确说明 状态 - 竞记录
🩸 **0.7 — 已发布**PyPI](https://pypi.org/project/proximo-proxmox/) (`pip install proximo-proxmox`)， [GitHub](https://ohn-broadway/proximo)，和 [GHCR](https://github.com/john-broadway/proximo/pkgs/container/proximo) （签名多架构镜像）。 _(0.1.1 “Spaniard” 是第一个公开版本，发布于 2026-06-10.)_
所有四个信任支柱（计划 · 验证 · 撤销 · 已构建并经过测试。 **145 个 MCP 工具。2600+ 测试，跳过，ruff + pyright clean** ——**模拟/进程（无套接字）；CI 在 GitHub 运行商上运行它们。 **下面的真实 P证明是一个单独的实时烟套件 —— 不此次数，不在 CI 中。** （计算的爆炸半径引擎涵盖破坏性工具表面 —— 个操作类，
命名特定的虚拟机、节点、ACL 主体或磁盘，一个危险的操作会损害，以便不回落
裸确认。 在 0.5.签名 A2A 卡 + 原生异步任务等待之上。）
**针对真实 Proxmox 证明（非模拟）：**
- 信任脊柱端到端，核心配置/变异循环和 PBS 读取形状。
- **治理/危险平面** —— 身份（角色/组/用户/ACL），存储，**SDN 待处理
对象**（区域/虚拟网络/子网创建→读取→删除），领域创建（LDAP/AD/OpenID 通过 `选项`
字典）—— 完整的创建→读取→删除周期针对真实的 **PVE 9.2** API，整个过程验证 PROVE 账本。
**（SDN/网络 *应用* — 主机网络重载 — 被故意从未在实时中触发；
它带有不可恢复的风险。）**
- **0.2.0 对象平面** —— 防火墙对象（别名/IP 集/安全组/选项），HA
**规则** （PVE 9 替换 HA 组），以及 SDN 区域/虚拟网络/子网（待处理，预应用）—
在真实的 **PVE 9.2** 节点上创建→读取→删除实时证明；TFA 管理员读取证明（TFA
突变由 PVE 而非令牌访问控制）。
- **离线虚拟机迁移** （包括本地磁盘）和 **HA 配置** 生命周期在 3 节点 PVE 9.2 测试集群上。
- 两个协议面由真实客户端端到端驱动：MCP 通过 stdio，A2A 由官方 a2a-sdk 驱动。
**尚未证明 — 明确说明：** 大多数 145 工具表面仍然针对模拟运行；真正的 HA
*隔离*（需要硬件看门狗），*在线* 热迁移（需要共享存储），以及生产规模的行为。
**A2A 接口（实验性，需选择加入）：** `pip install 'proximo-proxmox[a2a]'`，然后 `proximo-a2a` — 一个精选
16 技能切片通过 Agent2Agent **路由经过相同的信任核心** （继承的计划/验证/撤销；没有
第二个代码路径可以绕过）。 故障关闭周界：非 localhost 绑定在没有
承载令牌的情况下被拒绝（`PROXIMO_A2A_TOKEN_FILE`）；主机头允许列表防御 DNS 重绑定。 账本注意：
账本**默认情况下使用密钥（HMAC-SHA256）**（`PROXIMO_AUDIT_KEYED`，选择退出使用 `off`）—
**防篡改**，而非防篡改 — 而外部 `head()` 锚点（`PROXIMO_AUDIT_EXPECTED_HEAD`）是针对尾部攻击的强有力保证。
`ct_psql` 记录 SQL 正文和 `ct_exec` 运行的命令 argv（操作员自己的输入）以实现
完整的；设置 `IMO_LEDGER_RE1`（sha256 + 类型 + 长度，当 SQL/命令可能密/个人身份信息。 PVE API 令牌从未写入账本。
### 下一步
- [ ] 剩余生命周期表面的实时测试（PBS 变异）；HA 隔离 + 在硬件到位之前在线迁移
- [ ] PBS 证书指纹线强制执行
- [可选)_ 面 原生人群的 Debian 软件包
完整的构建历史记录 —— 每个支柱，每个红队修复 —— 都 [`CHANGELOG.md`](./CHANGELOG.md) 中。
## 许可证-2.0 — 因其专利授权选用，适用于基础设施工具。完整文本位于 [`LICENSE`](./LICENSE) 中。
## 致谢
由 **** 与 **Cl 和 **M 合作构建 ——与 AI 的合作伙伴关系，以及我们首先为世界提供的东西。
克劳德的贡献跨越多个时代，诚实记录：**克劳德·奥普斯 4.8** 构建了信任支柱和工具表面（2026-06-07 → 06-09）；**克劳德·尔 5了 101 代理发布审计和发布
（2026-06-10）。 每个提交都有其共同作者的追踪记录。
---
*"你们不感到娱乐吗？"* —— 欢迎各位贡献代码、问题和交流伙伴。 **力量与荣誉。** ⚔️
