proximo-proxmox 0.1.1__tar.gz

proximo_proxmox-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -q -ra

proximo_proxmox-0.1.1/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtualenvs / caches
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Debian build artifacts
+debian/proximo/
+debian/.debhelper/
+debian/files
+debian/*.substvars
+debian/*.log
+*.deb
+*.buildinfo
+*.changes
+
+# Proximo runtime — never commit audit logs or real config
+*.log
+audit.log
+*.env
+!*.env.example
+
+# Lockfile (library — consumers resolve their own deps)
+uv.lock

proximo_proxmox-0.1.1/CHANGELOG.md

@@ -0,0 +1,180 @@
+# Changelog
+
+All notable changes to Proximo. Format loosely follows Keep a Changelog; versions are SemVer.
+
+## [Unreleased]
+
+_Nothing yet._
+
+---
+
+## [0.1.1] — 2026-06-10 — "Spaniard"
+
+Hardening + release-readiness pass driven by an independent multi-team audit (3 cold reviewers,
+40 doc claims source-verified, full-history leak audit, adversarial verification of every finding).
+
+### Added
+- **Realm options dict** (`8d2dac0`): `pve_realm_create` and `pve_realm_update` now accept a
+  type-specific `options` dict — LDAP (`server1`/`base_dn`/`user_attr`), AD (`domain`/`server1`),
+  OpenID (`issuer-url`/`client-id`). Previously, creating any LDAP/AD/OpenID realm was impossible
+  through the tool. Live-proven against a real PVE 9.2 API.
+- **Governance/dangerous plane — live-proven to execute** (milestone): the governance and dangerous
+  plane (identity role/group/user/ACL; storage; SDN apply; network apply; realm create) that was
+  previously built+redteamed but MOCKED-only is now **proven to execute create→read→delete against
+  a real PVE 9.2 API on a nested test cluster**. Also proven on a nested 3-node test cluster:
+  offline guest migration (including local-disk) and HA-config operations (resource add/list/remove)
+  execute. PROVE ledger verified throughout. **Honest scope:** "nested test cluster" — not
+  production scale; HA **fencing** (hardware watchdog) and **online** live-migration (shared storage)
+  remain unproven.
+- **CI**: GitHub Actions workflow — ruff + the full pytest suite on Python 3.12 and 3.13.
+
+### Security
+- **A2A perimeter hardening** (`a8ce10b`, `0d952a6`): fail-closed by design — non-localhost bind
+  is **refused** unless `PROXIMO_A2A_TOKEN_FILE` is set; bearer auth (constant-time comparison) on
+  the JSON-RPC control endpoint when a token is set; Host-header allowlist + DNS-rebind defense
+  (`PROXIMO_A2A_ALLOWED_HOSTS`); `'*'` in the allowlist warns rather than silently disabling. The
+  agent card declares the bearer scheme. localhost-default dev behavior unchanged; A2A stays opt-in.
+- **Audit ledger file permissions:** the ledger is now created `0600` (owner-only) instead of the
+  umask default — entries can carry command/SQL detail and were world-readable on typical umasks.
+  Applies at creation; an existing file keeps the mode its operator set.
+
+### Fixed
+- Realm create/update no longer silently ignores type-specific options (LDAP/AD/OpenID realms
+  were uncreatable before this fix).
+- **Audit-integrity:** `ct_logs` now enforces the CTID allowlist at the server layer like its
+  siblings — a forbidden CTID ledgers as `blocked:allowlist` instead of surfacing as a backend error,
+  so allowlist denials are uniformly traceable in the PROVE ledger. Blocked entries for read-only
+  tools (`ct_logs`, `ct_diagnose`) now ledger `mutation: false`, matching the tool's true class.
+- **Packaging:** `proximo-a2a` without the `[a2a]` extra now prints a one-line
+  `pip install "proximo[a2a]"` hint (exit 2) instead of a raw `ModuleNotFoundError` traceback —
+  including when only `uvicorn` is missing; a missing *submodule* of an installed dependency still
+  tracebacks (that is a real environment bug, not a missing extra).
+
+### Notes
+- **117 MCP tools; 1964 tests passing (0 skipped); ruff clean.** Public on GitHub 2026-06-10; PyPI/GHCR pending.
+- Docs: public-readiness scrub of ROADMAP/CHANGELOG/POSITIONING; README install command made
+  copy-pasteable; claim wording tightened to carry its own scope. Lint: 3 leftover warnings in the
+  live-smoke scripts cleaned.
+
+## [0.1.0] — 2026-06-09 — "Spaniard"
+
+First blood — the foundation of the ethical Proxmox MCP. _Tagged `v0.1.0`; not yet published to
+PyPI/GHCR (local/private). Honest scope: 117 MCP tools, most exercised against mocks only; the trust
+spine + core lifecycle are live-proven, the governance plane is built/redteamed but not yet live-fired._
+
+### Added
+- **MCP stdio transport, proven end-to-end:** `python -m proximo` entry point; the `initialize` handshake
+  advertises Proximo's own version (not the MCP SDK's); covered by a real-client integration test
+  (`test_mcp_stdio_e2e.py`: client → stdio → FastMCP dispatch → tool → back).
+- Two backends: **REST API management** (scoped token) + **`ssh`→`pct` in-container exec** (local or remote).
+- **MCP tool surface** (FastMCP): `pve_node_status`, `pve_list_guests`, `pve_guest_status`,
+  `pve_guest_power`, `ct_exec`, `ct_psql`, `ct_logs`.
+- **Ethical spine:** append-only audit log (records real outcomes), confirm-gates on every mutating tool,
+  fail-closed CTID allowlist, input validation on API path components (vmid/kind/node).
+- Tests (13) + ruff lint config. Clean run.
+
+### Security
+- Security redteam (2026-06-07): **5 findings, all fixed** —
+  `ct_exec`/`ct_psql` now confirm-gated; allowlist now fails **closed**; audit records real outcomes
+  (errors included); `vmid`/`kind`/`node` validated against injection; TLS-disabled now warns.
+- Verified solid: command injection (shlex-correct on local + ssh + psql paths); the API token is never
+  logged, never enters the audit log, subprocess argv, or error messages.
+
+### PROVE pillar — tamper-evident ledger (2026-06-07)
+- The audit log is now a **hash-chained, tamper-evident ledger**: `entry_hash = sha256(prev_hash + body)`,
+  flock-guarded, fsync'd. `verify()` and the `audit_verify` MCP tool detect any altered / deleted /
+  inserted / reordered entry and pinpoint the break; `head()` is anchorable off-box. Tamper-**evident**,
+  not tamper-proof (honestly scoped). +6 tamper-detection tests. Redteam: 2 findings fixed.
+- This is one of the four trust-layer pillars (PLAN · UNDO · **PROVE** · DIAGNOSE) — see POSITIONING.md.
+
+### PLAN pillar — dry-run by default (2026-06-07)
+- New `proximo.planning` module: **every mutating tool now previews before it acts.** Called without
+  `confirm=True`, `pve_guest_power` / `ct_exec` / `ct_psql` return a **plan** — the exact change, the
+  guest's live state (power), blast radius, and an **advisory, heuristic risk rating** — instead of
+  executing. `confirm=True` then executes. You structurally cannot mutate without a plan first existing.
+- **PLAN ⊗ PROVE:** the previewed plan (including the live state it was based on) is written to the
+  tamper-evident ledger with `outcome="planned"`; a confirmed execution records `confirmed=true`. The
+  approval trail — *what preview was shown before the action* — is now verifiable, not just *that* it ran.
+- **Honest by design (guard every path to LOW):** `LOW` means "does not change state," not "safe";
+  the absence of a `HIGH` flag is not a safety signal; destructive signatures are curated, not exhaustive.
+- Adversarial review: confirmed bypasses fixed — whitelist audit (`find -delete`, `ip route add`,
+  `mount <dev>` no longer rate "read-only"); SQL `SELECT pg_terminate_backend()/lo_import()`,
+  `COPY ... PROGRAM` (RCE) now escalate; failed dry-runs are audited; `current` state recorded; latent
+  `_max_risk`/`_fmt_uptime` edge crashes fixed. Every confirmed bypass became a regression test.
+- Tests: **81 total** (was 21), ruff clean.
+- **Guarantee enforced:** the plan is recorded on BOTH paths — even a one-shot `confirm=True` records
+  its `planned` entry before mutating (no plan, no mutation). The PLAN→PROVE triplet
+  (`planned → ok/confirmed`) is uniform; a one-shot confirm can't bypass the recorded preview.
+
+### UNDO pillar — auto-snapshot before mutating + one-call revert (2026-06-07)
+- **Snapshot backend + tools:** `pve_snapshot_list` (read), `pve_snapshot_create`, `pve_rollback`
+  (DESTRUCTIVE — discards changes since the snapshot), `pve_snapshot_delete` (all PLAN-gated), and
+  `pve_task_status` to poll the async task UPIDs these return. Endpoints verified against PVE docs.
+- **The headline — auto-undo before exec:** `ct_exec`/`ct_psql` gain `snapshot=True`. With `confirm=True`
+  it takes a `proximo_undo_<ts>` snapshot **and waits for the task to finish** before running the
+  mutation, records the undo point, and returns it. **Fail-closed:** if the snapshot can't be created
+  or doesn't finish OK (e.g. storage doesn't support snapshots), the command is **NOT run**.
+- **Honest:** snapshots are storage-dependent (ZFS/BTRFS/LVM-thin; not directory/raw) — surfaced in the
+  plan, never assumed. Rollback's PLAN spells out the blast radius. Async ops record `outcome="submitted"`
+  (not "ok") so the ledger never claims an in-flight task is done.
+- Adversarial review: confirmed fixes, each a regression test — regex anchors `$`→`\Z` (newline bypass),
+  UPID length cap + reserved-name (`current`) guard, microsecond-unique undo names, strict task-exit
+  (fail-closed on missing `exitstatus`), server-layer allowlist gate (no orphaned snapshot for a
+  forbidden CTID), non-contradictory rollback preview when the snapshot is missing.
+- Tests: **116 total**, ruff clean.
+
+### DIAGNOSE pillar — read-first "what's broken" (2026-06-07)
+- New `proximo.diagnose` module + tools: `ct_diagnose` (API guest status + a FIXED read-only
+  in-container battery — failed units, disk, recent errors, memory, listening ports) and
+  `pve_diagnose` (node status + storage usage + recent failed tasks). Both strictly READ-ONLY
+  (no confirm, no mutation), audited. Backend reads: `node_storage`, `node_tasks`.
+- **Honest by design:** advisory flags, never causation ("signal present", not "the cause is X").
+  Flags also surface **incompleteness** — partial mode (exec off → API-only + a skipped-probes flag),
+  a failed read, or a failed probe all flag, so an empty `flags` list can never read as a false clean
+  bill of health. Inactive/offline storage is reported as offline, not as "full" (no stale-data alarm).
+- Adversarial review — read-only guarantee held (no injection, gates correct); the task-list `status`
+  field was **verified against the live PVE API**. Fixes, each a regression test: incompleteness flags,
+  inactive-storage handling, removed dead `--no-legend` guard, `_frac` inf/overflow guard, transient/
+  WARNINGS tasks no longer counted as failed, `node_tasks` limit clamp, `ExecBackend` vmid validation.
+- Tests: **141 total**, ruff clean. **All four trust-layer pillars (PLAN · UNDO · PROVE · DIAGNOSE) now built.**
+
+### Coverage expansion — phases 1–7 (2026-05 → 2026-06)
+- Grew the MCP surface from the 7 foundation tools to **117** `@mcp.tool()` tools, every mutating one
+  wearing PLAN+UNDO+PROVE by construction: provisioning/backup/restore, config/disk/cloud-init mutation, the
+  four "dangerous plane" domains (**firewall · network/SDN · cluster HA/migration · ACL/users/roles/realms**),
+  observability, task/pool control, storage admin, and **PBS-native** deep tools (GC/verify/prune/snapshots/
+  namespaces; separate `:8007` backend, TLS fail-closed).
+- **Live-proven** against a real PVE: the core provisioning/config mutate cycle (create→config→revert→
+  clone→backup→restore→delete, ledger verified) + read shapes across node/storage/observability + a
+  PBS datastore. **Honest scope:** the bulk of the 117-tool surface — *including the dangerous plane* —
+  is **MOCKED-only** (unit-tested against fakes, not fired against real Proxmox). A broad live smoke needs a
+  wider scoped token. See the `ROADMAP.md` reality-check and `LANDSCAPE.md`.
+
+### A2A (Agent2Agent) face — experimental (2026-06-09)
+- Optional second protocol head (`pip install 'proximo[a2a]'` → `proximo-a2a`): a curated **16-skill slice**
+  exposed over A2A, routing to the same server tools so PLAN/PROVE/UNDO/fail-closed are inherited. Serves an
+  agent card at `/.well-known/agent-card.json`; localhost by default (no built-in auth — warns on
+  non-localhost). Built + redteamed (PLAN-bypass + slice-boundary: **0 findings**); +47 tests. **Proven
+  end-to-end against a real a2a-sdk client** — agent-card resolve over HTTP + a real `message/send` invoking a
+  skill → completed task with a `result` artifact (real-socket proof + an in-process integration test,
+  `test_a2a_e2e.py`).
+
+### PROVE — opt-in HMAC-keyed audit chain (2026-06-09)
+- The audit ledger now supports an **opt-in keyed mode**: set `PROXIMO_AUDIT_KEY_PATH` to chain entries
+  with **HMAC-SHA256** instead of bare SHA-256 (key auto-generated at 0600 via an atomic temp+link, hex
+  stored, fail-closed on empty/non-hex/<32-byte). The **ledger's key is authoritative** — a downgrade
+  (strip the HMAC, recompute as SHA-256 without the key) is rejected; a keyed log must be all-keyed. Default
+  stays **unkeyed and byte-identical** (existing logs + tests unaffected); `audit_verify` reports `keyed`.
+  Adversarial review (forge / key-handling / verify lenses): no exploitable forgery; +12 tests incl. the downgrade
+  attack. **Honest scope:** keying resists forward-rewrite by an attacker *without* the key, but a same-user
+  attacker who can write the 0600 log can often read the 0600 key — the **off-box `head()` anchor remains
+  the strong guarantee.** Not a "cryptographic depth" moat.
+
+### Honesty note (2026-06-09)
+- The PBS cert fingerprint is stored but **not yet wire-enforced**.
+
+### Notes
+- Not yet released; **pre-alpha.** Apache-2.0 LICENSE: ✅ added. Pending: broad live smoke of the
+  mocked surface (needs a properly-scoped token), publish (PyPI/GHCR + CI) so the install commands work.
+
+_Strength and honor._

proximo_proxmox-0.1.1/Dockerfile

@@ -0,0 +1,16 @@
+# Proximo — self-contained, sovereign, on-demand.
+# The MCP client launches it per session: `docker run -i --rm ... proximo` (stdio).
+FROM python:3.13-slim
+
+# openssh-client powers the in-container exec edge (ssh -> pct). Everything else is bundled by pip,
+# so the image is self-contained and the host stays untouched.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends openssh-client \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY . /app
+RUN pip install --no-cache-dir .
+
+# MCP stdio server — no daemon, no open port. Launched on demand by the client.
+ENTRYPOINT ["proximo"]

proximo_proxmox-0.1.1/LANDSCAPE.md

@@ -0,0 +1,173 @@
+# Proximo — The Proxmox Automation Landscape
+
+> **Created** 2026-06-08 · **Refreshed** 2026-06-09 (method-corrected sweep; see Method).
+> **Refreshed 2026-06-10** (competitor numbers re-verified; Proximo governance plane now live-proven to
+> execute; A2A perimeter parity closed; official-Proxmox-MCP threat added).
+> An honest, source-verified survey of the Proxmox automation field across four modalities
+> (MCP / A2A / AI / API-IaC), with Proximo's own position stated plainly — including where it is late,
+> unproven, or simply not first. No manufactured foils.
+
+> **Method.** Competitors are ranked by real popularity (GitHub stars, registry presence). Tool counts
+> and safety features were re-read from the repositories on 2026-06-09 — not inferred from READMEs or
+> star counts, which miss feature drift. A keyword-only search (`proxmox` + `mcp`/`ai`) misses tools
+> whose primary identity is something else — e.g. a multi-backend homelab cockpit that exposes Proxmox
+> as one backend among many — so this survey adds an **off-keyword pass** for that class. A survey's
+> silence means "not found," never "does not exist"; treat each finding as as-of its date.
+
+---
+
+## TL;DR — the Proxmox field, four lanes
+
+1. **MCP (AI-native) — contested; Proximo is not first.** Two ~250★ leaders (**canvrno** ~261★, read-only
+   "safe inspector" with ~6 tools; **RekklesNA/ProxmoxMCP-Plus** ~241★, the active governance leader), a
+   long <50★ tail, and one real *trust* peer (**proxxx**). **Raw tool-count is not a moat:**
+   `chajus1/proxmox-mcp-enhanced` already claims **115 tools** — within a couple of Proximo's 117, and a
+   raw count says nothing about whether the tools are proven (a significant portion of Proximo's lifecycle
+   surface still runs against mocks — see *Where Proximo stands*).
+2. **A2A (agent-to-agent) — greenfield for Proxmox.** No dedicated open A2A agent-card/server for Proxmox
+   found (off-keyword sweep included). Homelabbers run multi-agent systems *on* Proxmox; nobody exposes
+   Proxmox *as* an A2A participant. Demand is unverified — flagged, not claimed.
+3. **AI (non-MCP automation) — hobby-tier, unconsolidated.** n8n templates, Prox-AI, OpenClaw, Clawdbot,
+   Paperclip — real activity, near-zero stars, no serious product. The serious builders are choosing MCP,
+   so this lane mostly feeds Lane 1.
+4. **API / IaC — the mature base layer (different modality, not a rival).** Terraform (Telmate ~2.9k★, bpg
+   ~2k★), Ansible `community.general.proxmox`, proxmoxer ~787★. Proximo doesn't compete here — but its
+   PLAN/UNDO maps onto the **plan/apply/destroy** idiom those users already trust.
+
+**The honest summary:** Proximo is a late, unstarred entrant in the contested MCP lane. Its defensible
+thesis is **not** "first," "most tools," or "the only one with trust." It is **trust *by construction***
+(every mutation carries PLAN + UNDO + PROVE in-band, fail-closed) **× coverage of the dangerous/governance
+plane** (firewall/SDN/ACL/roles/realms/PBS) that even the leaders keep off the MCP surface **× auto-UNDO**
+(fail-closed snapshot-before-mutate). You can bolt a `--dry-run` flag onto one tool; you cannot retrofit
+auto-snapshot + hash-chain + blast-radius across 100+ existing flat tools after the fact.
+
+---
+
+## Lane 1 — MCP servers for Proxmox VE (ranked, stars re-pulled 2026-06-10)
+
+| # | Repo | ★ | Tools | Lang | What it is / safety posture (source-verified 06-10) |
+|---|---|---|---|---|---|
+| 1 | **canvrno/ProxmoxMCP** | ~261 | ~6 | Py | Most-starred. Read-mostly "safe inspector," built for Cline. Popular *because* it doesn't hold the knives. |
+| 2 | **RekklesNA/ProxmoxMCP-Plus** | ~241 | ~42 | Py | **Active governance leader** (v0.5.8, Jun 7 2026). VMs/CT/snap/backup/ISO/storage/cluster + SSH-exec + job-control (list/get/poll/cancel/retry). Gov = `command_policy` + `approval_token` + TLS + DNS-rebind. **NO dry-run / NO auto-rollback / NO blast-radius / NO firewall·SDN·ACL·HA.** Permissive by default. |
+| 3 | **chajus1/proxmox-mcp-enhanced** | ~10 | **115** | Py | ⚠️ **The breadth rival.** Claims 115 tools "covering every aspect." Trust layer **unverified/absent** — but it rules out any "most complete by count" claim. Its dangerous-op coverage should be verified before anyone claims the completeness lane. |
+| 4 | **fabriziosalmi/proxxx** | ~15 | **25 (MCP)** | Rust | **The real TRUST peer** (v0.8.4, May 30 2026, 43 releases). MCP = VM ops + cluster diag + PBS *browse/restore* + GitOps state export/diff/**`--dry-run`** + audit-verify. Has a pre-flight **risk gate (PLAN-ish)** + **HMAC-keyed offline-verifiable audit chain** (PROVE — arguably stronger than Proximo's default-unkeyed ledger) + Telegram **HITL**. **No auto-UNDO** (read-only rollback *preview* only). **Firewall/SDN/ACL/PBS-writes are NOT on the MCP surface** — they live in the human TUI. |
+| 5 | gilby125/mcp-proxmox | ~41 | ~55 | JS | Configurable permissions. |
+| 6 | Markermav/ProxmoxMCP-advance | ~24 | — | Py | Multi-client (Claude/Goose/Cline). |
+| 7 | bsahane/mcp-proxmox | ~18 | — | Py | FastMCP, token auth, monitoring. |
+| 8 | mdlmarkham/TailOpsMCP | ~13 | — | Py | Homelab ops over Tailscale (multi-host; see Cross-cut A). |
+| 9 | tyxak/remotepower | ~12 | — | Py | Dashboard + CVE/patch + Proxmox MCP. |
+| 10 | antonio-mello-ai/mcp-proxmox | ~11 | — | Py | Cluster mgmt via AI. |
+| — | mjrestivo16 (35 tools), Samik081 (TS), jmerelnyc, GethosTheWalrus, agentify-sh, husniadil (PyPI), heybearc, ry-ops, plgonzalezrx8 (read-only+confirm), Zaptimist (ssh-exec), rodaddy (forks) | <10 | — | mix | The long tail. Registry-listed (PulseMCP/mcpmarket/Glama). |
+
+**PBS-specific MCPs (PBS is not whitespace):** `szoran53/pbs-mcp-server` (TS), `ahmetem/pbs-mcp` (Py) —
+datastore/snapshot/GC/verify/prune. proxxx covers PBS *browse/restore* inside its cockpit.
+
+**Where Proximo differs (Lane 1):** the governance leader (RekklesNA) is permissive-by-default with no
+PLAN/UNDO; the trust peer (proxxx) has PLAN+PROVE+HITL but keeps the dangerous plane out of MCP and has no
+auto-UNDO; the breadth rival (chajus1) has count but no verified trust. The intersection none of them
+holds — *the full firewall/SDN/ACL/roles/realms/PBS plane, exposed to the agent over MCP, every tool
+PLAN+UNDO+PROVE by construction, fail-closed by default* — is where Proximo aims. That intersection is
+currently empty.
+
+## Lane 2 — A2A (agent-to-agent) for Proxmox — greenfield
+
+- **No open A2A agent-card / server for Proxmox found** (incl. off-keyword sweep). A2A itself is large
+  (Google → Linux Foundation, 50+ partners; JSON-RPC/gRPC/REST + SSE + Agent Cards) — but nobody has
+  shipped "Proxmox as a first-class A2A participant."
+- Closest: commercial **Mindflow** "Proxmox VE agent"; homelabbers running *multi-agent systems on*
+  Proxmox (Paperclip, Clawdbot) — agents-hosted-on-Proxmox, not Proxmox-as-agent.
+- **Proximo's position:** an A2A Agent Card for Proxmox ("the Proxmox operator agent; here are its skills")
+  would be first in this lane. Demand is unverified — no signal yet that anyone is asking.
+
+## Lane 3 — AI (non-MCP automation) for Proxmox — hobby-tier
+
+| Project | Signal | What it is |
+|---|---|---|
+| **n8n "Proxmox AI agent" template** | popular no-code path | NL→Proxmox API via n8n + genAI; the most-reached-for non-coder route. |
+| **folkvarlabs/Prox-AI** | ~5★, HCL | Terraform-config *generator* via Google Forms + cost-approval. Not an agent. |
+| **OpenClaw** | — | Read-only LLM-backed Proxmox interface. |
+| **Clawdbot / Paperclip** | — | LLM-with-tools runtimes deployed *in* Proxmox LXCs. |
+
+No serious consolidated product here; the real builders pick MCP (Lane 1). This lane is a feeder, not a
+separate front — though a one-command no-code on-ramp (e.g. an n8n node) would reach the non-coder crowd.
+
+## Lane 4 — API / IaC clients — the mature base layer (different modality)
+
+Terraform **bpg** ~2k★ (modern leader, plan/apply/destroy) & **Telmate** ~2.9k★ (legacy) · Ansible
+`community.general.proxmox` (huge usage) · **proxmoxer** ~787★ (dominant Py wrapper) · Go (Telmate ~487,
+luthermonson ~267) · **Corsinvest cv4pve** suite (admin/autosnap/diag/metrics/botgram) · **CAPMOX** ~447★
+(K8s Cluster-API). Proximo doesn't rival these — but their users already trust **plan/apply** semantics, so
+Proximo's PLAN/UNDO speaks a dialect they know. Leverage, not competition.
+
+---
+
+## Cross-cut A — the multi-backend / homelab-fleet shape
+
+These never surface under "proxmox mcp"; Proxmox is one backend among several. This is the class a
+keyword search misses, and the one to keep watching:
+- **bshandley/homelab-mcp** — MCP over Docker + OPNsense (firewall) + TrueNAS + **Proxmox** + Home Assistant;
+  read-only→write capability tiers. A unified-homelab play on the "AI runs my whole homelab" pitch.
+- **AI-Engineering-at/homelab-mcp-bundle** (~4★) — 8-server homelab bundle incl. Proxmox.
+- **mdlmarkham/TailOpsMCP** (~13★) — multi-host homelab ops over Tailscale.
+- **shareed2k/Honey** — searches service instances across platforms incl. Proxmox.
+
+**Implication:** Proximo's bet is *depth on one platform with trust*; this class's bet is *breadth across
+the homelab*. Different bets — but if "AI runs my homelab" becomes the dominant framing, the breadth
+players, not the Proxmox-MCP leaders, are the more direct competition.
+
+## Cross-cut B — generic trust layers: can someone add PLAN/UNDO *for* Proxmox without building it?
+
+The 2026 hot category is **MCP gateways / guardrails** — they sit in front of *any* MCP and add governance:
+**IBM ContextForge** (3.8k★, Apache-2.0; proxies MCP **and A2A** and REST), **Docker MCP Gateway**,
+**Lasso**, **Bifrost**, **TrueFoundry**, **Portkey**, **MintMCP**, **Obot**, **Traefik Hub**, **AWS Bedrock
+AgentCore**. The adjacent AI-SRE market (Hyground, StackGen, NeuBird, Azure SRE Agent, SRE.ai) is
+well-funded.
+
+**Why this matters, source-verified:** every one of these gateways provides **auth + policy + audit +
+(some) human-approval** — but **none provide dry-run, auto-rollback, or blast-radius**, because a gateway
+is **resource-blind**: it can gate or log a tool call, but it can't snapshot a Proxmox VM or compute the
+blast radius of an ACL change, because it doesn't understand the resource. **PLAN and UNDO are
+domain-specific by necessity** — a generic layer can't do them *for* Proxmox.
+
+**The honest threat (assemble-from-parts):** ContextForge (audit/policy/approval) + RekklesNA (coverage)
+= a credible audit + policy + HITL story over Proxmox *today*, with no new code. That combo lacks
+PLAN/UNDO/blast-radius — but if a buyer's bar is "audit + approval," it clears now. The defensible ground
+is the part that can't be assembled: PLAN (live-state + blast-radius), UNDO (auto-snapshot/revert), and
+coverage of the governance plane — not "has an audit log."
+
+---
+
+## Where Proximo honestly stands (no spin, no shrink)
+
+- **Popularity:** zero (local, unpublished — v0.1.1, not on PyPI/GHCR, zero public stars). MCP leaders
+  ~250★; IaC leaders ~2–3k★.
+- **"First":** no. **"Most tools":** no (chajus1 ≈115). **"Only one with trust":** no (proxxx: risk-gate +
+  keyed audit chain + HITL; RekklesNA: command_policy + approval-token).
+- **Genuinely differentiated, execution now confirmed on the key plane:**
+  1. **Trust by construction** — every mutation PLAN+UNDO+PROVE *in-band & fail-closed-by-default*, vs
+     proxxx's human-gates-each-act and RekklesNA's opt-in/audit-only.
+  2. **The dangerous/governance plane on the MCP surface** — firewall/SDN/ACL/roles/realms/PBS exposed *to
+     the agent*. RekklesNA doesn't cover it; proxxx keeps it in the TUI. This is the empty intersection.
+     The identity/storage/SDN/network/realm surface and offline migration + HA-config have been
+     **live-proven to execute** against a real PVE 9.2 API, including a nested 3-node test cluster, with
+     PROVE verified throughout. Still unproven: real HA fencing (hardware watchdog), online live-migration
+     (shared storage), and production scale.
+  3. **Auto-UNDO** — none of the above takes the snapshot for you; proxxx previews a rollback, it doesn't
+     perform one.
+- **A2A face perimeter-parity closed:** fail-closed public bind, bearer auth on the control endpoint,
+  `PROXIMO_A2A_ALLOWED_HOSTS` Host/DNS-rebind allowlist — previously warn-only. Matches the leader's
+  perimeter posture.
+- **Maturity, stated straight:** v0.1.1, unpublished; a significant portion of the broader ~117-tool
+  lifecycle surface still runs against mocks; MCP face is local stdio (no network bind); perimeter
+  hardening for MCP becomes required the day a remote transport is added. The differentiation above is now
+  execution-confirmed on the governance plane; lifecycle breadth and production scale remain to prove.
+- **Emerging threat:** field chatter that Proxmox may ship an **official MCP server**. An official basic
+  server would commoditize the VM/LXC/snapshot/backup lifecycle layer. Proximo's durable answer is the
+  dangerous/governance plane and trust-by-construction — capabilities an official day-one server is
+  unlikely to ship. This risk is real; watch the Proxmox project for announcements.
+
+## Sources
+GitHub (stars + repo READMEs re-read 2026-06-10: canvrno, RekklesNA v0.5.8, proxxx v0.8.4, chajus1,
+gilby125, bshandley/homelab-mcp); PulseMCP / mcpmarket / Glama registries; IBM/mcp-context-forge (3.8k★,
+v1.0.2); Integrate.io & TrueFoundry MCP-gateway roundups; agamm/awesome-ai-sre; a2a-protocol.org;
+Mindflow; n8n Proxmox-AI template.

proximo_proxmox-0.1.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 John Broadway
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.