Proximo

进入角斗场 ↗ · 快速入门 · 设置 · 信任层 · 演示 · 工具 · 安装 · 安全 · 文档

以《角斗士》中角斗士经纪人 Proximo 的名字命名。故事就是设计，一环扣一环。

他只给斗士配备恰到好处的装备，绝不多给。竞技场上的每个动作，他都承担责任。他是经纪人，不是狱卒。西班牙人以行动赢得自己的名字，一切都有据可查；头盔摘下：坦然说出真相，不惜代价。他最后的行动打开了牢笼，手中握着象征自己自由的木剑。工具也该盼望有这样一个好结局。

“赢得观众，你就能赢得自由。”

其他方案逼你二选一：只读玩具，或交出全部密钥然后听天由命。Proximo 不会这样。每个危险操作都会先规划：执行前明确判定结果、当前目标和将要做出的变更。每个操作都有凭证：防篡改记录。并且，只要平台提供了相应机制，就能撤销：变更会捕获即将修改的记录，并通过供应商自身的写入接口将其还原；有风险的容器内命令可以先创建快照，如果无法创建，就拒绝运行。

信任融入底层，而非事后补上。把密钥交给 AI Agent，收好凭证。

自主掌控，兼容各种 Agent。 你的硬件、你的令牌、由你掌控的账本。无需云端，不会回传数据，也不会常驻运行服务，除非你选择启用。

功能介绍

用通俗的英语提问：“为什么 ct 105 一直卡顿？” AI Agent 会获取节点和虚拟机的状态，查看日志尾部；如果你启用了该通道，还会在容器内运行诊断来查明原因。

如果有修复方案，它会先向你展示计划，然后才会执行任何操作：判断结果、目标当前状态以及具体变更。你可以要求它先创建快照；如果做不到，它就不会运行。执行修复后，它会提供一份带密钥的收据，准确记录所做的变更，并保存变更前的状态，以便恢复。

这一切都通过六个工具完成，覆盖 4 款 Proxmox 产品公开的所有地址。没有包装层，没有需要翻查的目录，也没有为每个端点单独配备工具：找到地址、制定计划、读取或调用地址，并验证记录。整个接口面都能放进小型本地模型的上下文窗口。

这就是我们的产品：让 AI 能够操作、却无法搞垮的虚拟机管理程序。

默认只读。首次调用不会执行任何变更：它会先返回影响范围计划供你查看。每项变更都有防篡改收据。

要比较的不是 Proximo 和图形界面，而是Proximo 和把 root 令牌交给 LLM 然后祈祷它别出错。

别光听我们说。亲自验证。

# 1. The tool count is real. Ask the door itself, cold (=> 6).
#    (in a clone of this repo, after `uv sync`)
uv run python -c "import asyncio; from proximo.core.doors.mcp import build_server; \
print(len(asyncio.run(build_server().list_tools())))"

# 2. The container image is what the repo built. Sigstore provenance (exit 0 = verified):
gh attestation verify oci://ghcr.io/john-broadway/proximo:latest --owner john-broadway

# 3. The security posture is graded by a third party, not by us:
#    https://scorecard.dev/viewer/?uri=github.com/john-broadway/proximo

_{每种传输方式都会进入同一个受治理的分发层，并经过同一条信任主干；其下方的令牌底线由 Proxmox 自身强制执行。
在演示中观看它如何经受考验。}

// your MCP client config (Claude Desktop / Claude Code / Cursor / …)
{
  "mcpServers": {
    "proximo": {
      "command": "uvx",
      "args": ["proximo-proxmox"],
      "timeout": 60,                                     // startup is ~3.5s; a 3s client default drops the server silently
      "env": {
        "PROXIMO_API_BASE_URL": "https://your-pve:8006/api2/json",
        "PROXIMO_TOKEN_PATH": "/path/to/token-file"   // USER@REALM!TOKENID=SECRET, by reference, never inlined
      }
    }
  }
}

Claude Code，一行命令：

claude mcp add proximo --env PROXIMO_API_BASE_URL=https://your-pve:8006/api2/json \
  --env PROXIMO_TOKEN_PATH=/path/to/token-file -- uvx proximo-proxmox

或一键安装：

_{两种方式都会提示输入令牌文件的路径；密钥不会进入客户端配置。还没有令牌？运行 uvx proximo-proxmox mint pve，即可查看遵循最小权限原则的操作手册。}

然后预检令牌实际可执行的操作（只读）：

uvx proximo-proxmox doctor

请从只读令牌开始。即使不授予写入权限，Proximo 也很有用。 完整的令牌优先操作指南：docs/SETUP.md · 更多安装方式：安装与运行。

Proximo 的存在意义

Proxmox MCP 领域各自为政。基于 API 的服务可以管理节点和 VM，但在架构上无法在 LXC 内执行命令：REST API 没有 exec 端点。基于 SSH 的服务则可以通过权限范围很宽的 Shell 访问来执行命令，几乎没有权限限制。

Proximo 以原则为基础，将两者合二为一。一套经过审计的界面，兼顾两种能力，并遵循最小权限原则。安全性由架构保障：

（各类型列描述的是上述不同方案，并不指代任何特定项目。Proxmox 没有官方 MCP；Proximo 是独立的社区项目。）

信任层：Proximo 的不同之处

主干由六大支柱组成。其中四项默认启用：

另外两项按设计需由你自行启用，在其状态路径建立之前保持关闭，因为只有这些路径位于 Agent 的控制范围之外，它们才有价值。由 Proximo 替你启用的支柱，也会是 Agent 可以自行关闭的支柱：

proximo doctor 会报告主干状态：哪些支柱已启用、哪些配置接口为空，以及如何准确填充这些接口。另有四项控制会在配置前保持关闭：ARM（只有当服务所用令牌就是写入令牌时，才会执行变更操作）、FORBID/RATE ENVELOPE、TAINT（提示词注入缓解措施），以及 PRINCIPAL（记录请求者归属）。作用范围和租约不再由 Proximo 管理：写入令牌自身的 ACL 就是作用范围，其自身的 expire 就是租约，两者都由 Proxmox 执行；proximo mint 会打印创建此类令牌所需的命令。各项控制的防护范围见：SECURITY.md。

坦诚说明（关键）： 风险评级是启发式建议，并非沙箱——LOW 表示“不会改变状态”，并不表示“安全”；没有 HIGH 标记也不能作为安全信号。请自行审查每一项变更。 这一切的基础是你创建的令牌： 即使 Proximo 进程完全遭到入侵，Proxmox RBAC 仍然有效——这比 Proximo 自身代码所能提供的任何保障都更强。请将作用范围精确限定为你想授予的权限：SECURITY.md。

任何工具都应接受这项检验，包括本工具：The Keys Test。在向 AI Agent 提供真实基础设施的访问权限之前，先问这十个问题。Proximo 已公布自身的评分卡，包括未完全通过的项目。

演示

记录会自证：

_{三个 Agent 操作写入带密钥的账本；其中一条记录被原地编辑；audit_verify() 在精确行处报告哈希链断裂，ok=False；正向遍历会漏掉的截断操作，会通过固定的头部捕获。真实代码，真实加密，没有摆拍，记录于 0.30.0。 亲手伪造一个字节，看看哈希链如何拒绝：VERIFY.md，第 2 节。}

接口与工具：一个控制平面

这些后端刻意保持简单，谁都可以调用。产品真正的价值，在于覆盖其上的信任层。

六个工具，覆盖每个地址。厂商发布 API；Proximo 完整提供这些 API，并根据每个地址的性质实施治理：四款产品共发布 1,804 个地址，其中 884 个读取地址、785 个变更地址向已启用的操作员开放，且每个都有编写好的影响范围等级；32 个地址需由操作员通过开关启用（来宾 Agent、容器和节点 Shell）；5 个位于下载通道；20 个有意保留，并附有说明；78 个因不是 JSON 调用而被排除。记录由厂商自己的架构生成，过时的副本无法通过测试套件：docs/arena.md。

操作员实际开始使用时，可以采用这套六工具语法：

六个工具的类型化输入：docs/TOOLS.md · 操作指南：docs/SETUP.md。

安装与运行

仅核心，不涉及模型： 同一安装包提供 proximo-core pve GET /nodes/pve1/status（或在任意地址上使用 --plan：给出判定和已发布的架构，不触碰任何内容）。它的导入闭包只有 httpx（经测试测得）；涵盖全部四种产品上的每个已发布地址；与 MCP 入口使用相同的启用门槛、分级和审计账本。核心有自己的网络入口，每个入口都是 0.44 版界面外围加上其后的核心：proximo-mcp-http（通过可流式传输的 HTTP 使用 MCP）、proximo-http（REST，POST /tools/{name}，附带 OpenAPI 文档）以及 proximo-a2a（Agent2Agent 卡片，技能为六种工具）。

📦 0.49.1：可从 PyPI、GitHub 和 GHCR 获取（已签名的多架构镜像）。

0.49.1 新增内容（跨集群执行 Shell 调用，以及运维人员的等待时间）。 命名的 PVE 目标可以将每个节点名称映射到一个 ssh 目标（[targets.<name>.nodes]），因此 Shell 行可以触达集群中的每个节点；如果缺少映射，会在读取或消耗任何内容之前拒绝执行，而且远端仍必须作为该路径对应的节点响应。PROXIMO_SHELL_TIMEOUT 设置单次 Shell 调用的等待时长，范围为 1 到 600 秒。节点路由由 RavenLiao 贡献（PR #107）。

近期更新：0.49.0 在每个入口的单一出口处，为所有面向模型的回答设置了严格的字节上限，并在回滚前先创建安全快照。有关每项控制实际能保障什么，请参阅 SECURITY.md。

Proximo 按需在你的机器上运行。无需守护进程，也不会开放端口。

uvx proximo-proxmox            # zero-install run (PyPI package: proximo-proxmox; command stays `proximo`)
# or: pip install proximo-proxmox            the MCP core
# or: pip install "proximo-proxmox[a2a]"     + the optional A2A face
# or: pip install "proximo-proxmox[http]"    + the optional HTTP/OpenAPI face
# or: pip install "proximo-proxmox[mcp-http]" + the optional MCP-over-streamable-HTTP face
# or, from source:  git clone https://github.com/john-broadway/proximo.git && cd proximo && uv pip install -e .

在 MCP 客户端中将其配置为命令 proximo，并设置 PROXIMO_* 环境变量；请参阅 packaging/proximo.env.example。

Docker（GHCR）： docker run -i --rm … ghcr.io/john-broadway/proximo:latest。支持多架构，附带 SBOM 和 sigstore 签名的来源证明（gh attestation verify oci://ghcr.io/john-broadway/proximo --owner john-broadway）。也镜像到了 Docker Hub（docker.io/jebroadway/proximo，摘要相同）；GHCR 仍是签名主仓库。

默认安全： 开箱即用仅支持 API。两个接近 root 权限的边缘功能均为可选启用，并有醒目提示：LXC exec（PROXIMO_ENABLE_EXEC=1，在主机上接近 root 权限）和 qemu-guest-agent 边缘功能（PROXIMO_ENABLE_AGENT=1，在来宾系统中接近 root 权限）。每项功能都由各自的故障关闭型允许列表限定范围。

从设计上实现最小占用： 入口只公布六种架构，不提供其他内容。在此版本中测得，通过 stdio 传输的 tools/list 在线路上为 5,544 字节（按每个 token 四字节的经验值约为 1,400 个 token；按标准 1.5B 的聊天模板渲染时为 1,568 个 token，由其服务端计数），这就是连接的全部成本；后方的基础架构是按需搜索，而非加载。无需限定范围：未配置的平面根本无法访问，已配置的平面则可完整访问，而且门槛不会随入口缩小。无论模型多小，PLAN 和 PROVE 都适用于每个地址。

网络接口（实验性，需选择启用）： proximo-a2a 使用 Agent2Agent 协议。proximo-http 提供纯 HTTP + 自动生成的 /openapi.json，供无代码客户端使用。proximo-mcp-http 通过可流式传输的 HTTP 提供 MCP 本身（SDK 的原生传输），供联网的 MCP 客户端使用：无需第三方 stdio→HTTP 桥接，因此外围防护仍由 Proximo 提供。在 Proxmox 主机上运行 LXC，只需一行命令： 在 PVE 节点上以 root 身份执行 bash -c "$(curl -fsSL https://raw.githubusercontent.com/john-broadway/proximo/main/packaging/lxc/ct/proximo.sh)"，即可构建 Debian 13 容器，其中运行来自 PyPI 的 Proximo 和 proximo-mcp-http，使用独立的服务用户，并在端口 41243 上生成 bearer。使用 Community-scripts 引擎（MIT），但指向 Proximo 自己的代码树，并关闭其遥测；在容器内执行同一行命令即可更新。详情：docs/SETUP.md，文件：packaging/lxc/。 三种方式都通过与 MCP 相同的主干提供完整功能面。没有第二条代码路径；信任主干和令牌范围均沿用。默认拒绝的边界防护：仅限环回地址；非本地主机访问必须提供 bearer 令牌；防御 DNS 重绑定和 CSRF。详情请见：SECURITY.md。

面向规模

一个容器只是演示。集群才是重点。

• 一次调用读取整个集群。 proximo_read pve /cluster/resources：每个 VM、节点、存储池和 SDN 对象，以精简行形式返回，并附带总数。
• 跨所有节点的一份防篡改记录。 “给我看看这个月所有更改状态的操作，并证明日志没有被动过”，变成一个真正可以回答的查询。人在命令行界面操作，做不到这一点。
• 时间从哪里省出来。 在单个节点上，资深人员用命令行界面操作更快，这没问题。跨越十几个节点和数百个 Guest 时，一个范围受限、经过审计的 Agent 才能体现价值。

**多台机器，一个 Proximo：**在 TOML 文件中注册远程服务（通过引用提供密钥，绝不内联），将 PROXIMO_TARGETS 指向该文件，再用 target="edge-pve" 指定调用目标（shell 入口：--target edge-pve）。目标会随调用传递。PLAN 和 EXECUTE 会访问同一台机器，账本会记录目标是哪一台；跨平面调用会报错。配置格式：packaging/targets.example.toml。

状态：实战记录

• 🩸 0.49.1：**跨集群的 Shell 调用，以及操作员的等待时间。**命名的 PVE 目标会将节点名称映射到 ssh 目标地址，因此 shell 行可以访问每个节点（来自 PR #107）；PROXIMO_SHELL_TIMEOUT 设置单次 shell 调用的等待时间，范围为 1 到 600 秒（issue #106）。4,186 项测试。 此前的每个版本（每个支柱、每次红队测试、每项修复）都记录在 CHANGELOG.md 中。

**如实呈现的数据：**6 个工具覆盖 1,804 个已发布地址，并依据每个地址的属性进行治理（方法决定读或写，设计上总数固定；爆炸半径等级是唯一由人工填写的列；未分级的变更操作会被拒绝，无论是否已启用）。4,186 项进程内测试（ruff + pyright 均通过）覆盖引擎、6 个支柱、入口和记录；门禁轮次会逐一禁用每个支柱的门禁，并要求测试套件检测出来。此工作区每天通过 Proximo 管理自己的 Proxmox 资产（dogfood）。

已在真实环境中验证（非模拟）：通过此入口，在真实 PVE 9 节点上端到端验证治理流程，包括读取真实目标的计划、写入密钥链上的回执、捕获变更前状态并恢复。0.44 封装器的真实环境记录（3 节点集群、PBS、PMG、PDM，以及真实的跨数据中心迁移）保留在 CHANGELOG.md，因为那是当时实际完成的；这里不把它归功于核心功能。 **尚未验证——如实说明：**小型本地模型能否通过此入口完成整个任务。已在 0.45 上进行测量和测试：在 llama.cpp 后运行未经修改的 1.5B 模型，服务器强制执行 4,096-token 上下文，并在真实 PVE 节点上以只读方式运行。模型的调用均已送达，入口每次拒绝时都指出了需要修正的内容（虚构字段，并列出真实字段）；提示词峰值为 3,074 个 token；模型没有完成任务，而是编造了一个数字。上下文窗口撑得住；1.5B 模型不行。基于硬件看门狗的隔离（需要实体 iTCO/IPMI），以及生产规模下的行为。保留的 20 个地址从不执行：按设计逐句拒绝，并非功能缺口。

文档

许可证

Apache-2.0，因其专利授权条款适合基础设施工具而选用。完整文本见 LICENSE。

致谢

由 John Broadway 与 Claude 和 Maude 共同打造：这是一次人机合作，也是我们在这台机器上制作并赠予世界的第一件作品。Claude Opus 4.8 构建了信任支柱和最初的工具界面，并持续参与此项目；Claude Fable 5 执行了 101 个 Agent 的发布审计，并完成首次发布。每次提交都附带共同作者标记。

“你们还没看够吗？” 欢迎点星、提 issue，也欢迎切磋。力量与荣耀。 ⚔️