Proximo

ルドゥスに入る ↗ · クイックスタート · セットアップ · 信頼レイヤー · デモ · ツール · インストール · セキュリティ · ドキュメント

『Gladiator』のラニスタ、Proximoにちなんだ名前です。物語そのものが設計であり、一つひとつが緊密に結びついています。

彼は剣闘士に必要なものだけを、過不足なく与えました。闘技場でのあらゆる行動に責任を負いました。牢番ではなく、ラニスタです。スペイン人は行いによって名を上げ、その記録は残り、兜を脱ぎます。代償を払っても、真実をありのままに語るのです。最後の行いで、彼は自らの自由を象徴する木剣を手に、檻を開きました。ツールも、いつかそのような結末を迎えられるとよいでしょう。

「群衆の心をつかめば、自由を手にできる」

ほかの製品は、どちらかを選ばせます。読み取り専用のおもちゃか、すべての鍵を渡して祈るかです。Proximoはそうしません。危険な操作はすべて、実行前に計画されます。判定、実際の対象、変更内容が示されます。操作はすべて証明されます。改ざんを検知できる記録が残ります。そして、プラットフォームが基本機能を提供する限り、元に戻せます。変更操作では、変更対象の記録を事前に取得し、ベンダー独自の書き込み機能を使って元に戻します。コンテナー内での危険なコマンドは、事前にスナップショットを取得できます。取得できない場合、実行を拒否します。

後付けではなく、基盤に組み込まれた信頼。AI エージェントに鍵を渡し、記録は手元に残しましょう。

主権を保ち、エージェントを選びません。 あなたのマシン、あなたのトークン、あなたが所有する台帳。クラウドも、外部への通信も、明示的に選択しない限り常時稼働するサーバーもありません。

できること

平易な英語で「ct 105 がなぜスラッシングしているの？」と尋ねます。AI エージェントがノードとゲストの状態を取得してログを末尾まで確認し、そのレーンを開いていれば、コンテナー内で診断を実行して原因を調べます。

修正方法が見つかった場合は、何かに手を加える前に計画を表示します。判定、現在の対象の状態、具体的な変更内容を確認できます。求められれば最初にスナップショットを取得し、取得できない場合は実行しません。修正を適用すると、変更内容を正確に記録したキー付きの受領証を発行します。元に戻せるよう、変更前の状態も記録されます。

これらすべてを6 つのツールで実行し、4 つの Proxmox 製品が公開するすべてのアドレスに対応します。ラッパーも、ページをめくって探すカタログも、エンドポイントごとのツールもありません。アドレスを見つけて、計画を立て、読み取りまたは呼び出しを行い、記録を検証します。機能全体が小規模なローカルモデルのコンテキストに収まります。

それがこの製品です。AI が操作できても、壊すことはできないハイパーバイザーです。

デフォルトは読み取り専用です。最初の呼び出しで変更は実行されません。まず影響範囲を計画として返し、確認できるようにします。変更ごとに改ざん検知可能な受領証を発行します。

比較対象は Proximo と GUI ではありません。Proximo と、LLM に root トークンを渡して何も起きないことを祈る方法です。

説明を鵜呑みにしないでください。ご自身で検証してください。

# 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 の場合は 1 行です。

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 ベースのサーバーなら実行できますが、スコープをほとんど絞れない広範なシェルアクセスを利用します。

Proximo は、この両面を筋道立てて統合します。両方の機能を、監査済みの単一インターフェースで、最小権限の原則に従って提供します。設計による信頼性：

(各類型の列は前述の分断状況を示すもので、特定のプロジェクトを指すものではありません。公式の Proxmox MCP はありません。Proximo は独立したコミュニティプロジェクトです。)

信頼レイヤー：Proximo を際立たせるもの

中核には6つの柱があります。デフォルトで有効なのは4つです。

残る2つは、設計上、設定されるまでオフのままです。これらの状態パスがエージェントの手の届かない場所にある場合にのみ意味があるため、有効にするかどうかはお客様が決めます。Proximo がお客様に代わって有効にした柱は、エージェント自身が無効にできてしまいます。

proximo doctor は中核の状態を報告します。有効な柱、未設定の項目、それらを設定する正確な方法を確認できます。ほかにも4つの制御があり、設定されるまではオフです。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 エージェントに実際のインフラストラクチャを任せる前に尋ねるべき10の質問です。Proximo 自身の採点表も、一部の評価を含めて公開しています。

デモ

記録は自らを守ります。

_{3つのエージェント操作が鍵付き台帳に記録され、1つのエントリがインプレースで編集されます。audit_verify() は正確な行で停止し、ok=False となります。前方走査では見逃す切り詰めも、ピン留めされたヘッドとの照合で検出されます。実際のコード、実際の暗号技術、演出なし、0.30.0 で記録。 自分でバイトを改ざんし、チェーンが拒む様子を確認してください。VERIFY.md のセクション2をご覧ください。}

サーフェスとツール：1つのコントロールプレーン

これらのバックエンドは意図的に地味なものです。誰でも呼び出せます。製品の価値は、その上にある信頼レイヤーです。

6つのツールで、すべてのアドレスに対応します。ベンダーが API を公開し、Proximo はそれをすべて提供し、各アドレスの性質に応じてガバナンスを適用します。4つの製品にわたる公開アドレスは1,804件で、読み取りが884件、オペレーターが有効化すれば実行可能な変更操作が785件（それぞれに作成者が設定した影響範囲の段階があります）、オペレーターのスイッチで有効になるものが32件（ゲストエージェント、コンテナおよびノードのシェル）、ダウンロード用レーンが5件、理由を明記して意図的に保留しているものが20件、JSON 呼び出しではないものとして除外したものが78件です。この記録はベンダー独自のスキーマから生成され、古いコピーではテストスイートに失敗します：docs/arena.md。

オペレーターが実際に使い始める、6つのツールによる文法です。

型付き入力を備えた6つのツール：docs/TOOLS.md · 手順ガイド：docs/SETUP.md。

インストールと実行

**コアのみ、モデルは介在しません：**同じインストールには proximo-core pve GET /nodes/pve1/status も含まれます（任意のアドレスで --plan を指定すれば、判定と公開スキーマを確認できます。何にも触れません）。インポート依存関係は httpx だけです（テストで測定済み）。4つすべての製品で、公開されているすべてのアドレスに対応し、MCP の入口と同じアームゲート、ティア、監査台帳を備えています。コアには独自のネットワーク入口があり、それぞれ 0.44 の入口と同じ境界の内側にコアを配置しています。proximo-mcp-http（ストリーミング可能な HTTP 経由の MCP）、proximo-http（REST、OpenAPI ドキュメントを備えた POST /tools/{name}）、proximo-a2a（6つのツールをスキルとする Agent2Agent カード）です。

📦 0.49.1：PyPI、GitHub、GHCR（署名済みマルチアーキテクチャイメージ）で公開中です。

**0.49.1 の新機能（クラスター全体でのシェル呼び出しと、オペレーターの待機時間）。**名前付き PVE ターゲットでは、各ノード名を SSH 接続先にマッピングできるため（[targets.<name>.nodes]）、シェルの対象行がクラスター内のすべてのノードに到達します。マッピングがない場合は、読み取りやコスト消費が発生する前に拒否され、接続先も引き続きパス上のノードとして応答する必要があります。PROXIMO_SHELL_TIMEOUT で、1回のシェル呼び出しを待機する時間を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 に近い2つの境界はオプトイン方式で、明確に警告されます。LXC exec（PROXIMO_ENABLE_EXEC=1、ホスト上で root に近い権限）と qemu-guest-agent の境界（PROXIMO_ENABLE_AGENT=1、ゲスト内で root に近い権限）です。それぞれ専用のフェイルクローズ型許可リストで範囲を制限します。

**構成上、フットプリントは最小限：**入口が公開するのは6つのスキーマだけです。このリリースでの測定では、stdio 経由の tools/list はワイヤー上で5,544バイトです（4バイトを1トークンとする目安で約1,400トークン、標準の1.5Bのチャットテンプレートでは1,568トークン。サーバーで計測）。これが接続にかかるコストのすべてであり、その背後にある環境は読み込みではなく検索されます。範囲を制限する必要はありません。設定していないプレーンには到達できず、設定したプレーンには全体に到達できます。また、ゲートは入口が小さくなっても縮小しません。モデルの規模がどれほど小さくても、すべてのアドレスに PLAN と PROVE が適用されます。

ネットワーク向けインターフェイス（実験的、オプトイン）：proximo-a2a は Agent2Agent を使用します。proximo-http は、ノーコードクライアント向けにプレーンな HTTP と生成済みの /openapi.json を提供します。proximo-mcp-http は、ネットワーク接続型 MCP クライアント向けに Streamable HTTP 経由で MCP 自体を提供します（SDK 標準のトランスポート）。サードパーティ製の stdio→HTTP ブリッジが不要なため、境界は Proximo が維持します。Proxmox ホスト上の LXC、1行でインストール：PVE ノード上で root として、bash -c "$(curl -fsSL https://raw.githubusercontent.com/john-broadway/proximo/main/packaging/lxc/ct/proximo.sh)" を実行すると、PyPI の Proximo を使って proximo-mcp-http を実行する Debian 13 コンテナを構築します。専用のサービスユーザーを作成し、ポート41243で使用するベアラーも生成します。Community-scripts エンジン（MIT）を Proximo 独自のツリーに向けて使用し、テレメトリーは無効にしています。コンテナ内で同じコマンドを実行すると更新できます。詳細：docs/SETUP.md、ファイル：packaging/lxc/。 3 つすべてが、MCP と同じスパインを通じて全機能を提供します。コードパスは増えず、信頼スパインとトークンのスコープを継承します。フェイルクローズの境界防御：ループバック、localhost 以外ではベアラートークン必須、DNS リバインディングと CSRF への防御。詳細：SECURITY.md。

大規模環境で

コンテナ 1 つはデモです。クラスターこそが本領です。

• クラスター全体を 1 回の呼び出しで。 proximo_read pve /cluster/resources：すべての VM、ノード、ストレージプール、SDN オブジェクトを、合計付きの簡潔な行として取得します。
• すべてのノードにまたがる、改ざん検知可能な 1 つの記録。 *「今月、状態を変更した操作をすべて表示し、ログが改ざんされていないことを証明して」*という依頼に、実際に答えられるクエリになります。CLI の前から人が離れれば、それはできません。
• 時間を取り戻せる場面。 1 つのノードなら、CLI を使う熟練者のほうが速く、それで問題ありません。十数台のノードと数百のゲストにまたがれば、範囲が限定され、監査可能なエージェントが力を発揮します。

多数のマシンを、1 つの Proximo で： リモートを TOML ファイルに登録し（シークレットは参照で指定し、直接書き込みません）、PROXIMO_TARGETS でそのファイルを指定し、target="edge-pve" を付けて呼び出します（シェル経由の場合：--target edge-pve）。ターゲットは呼び出しとともに渡されます。PLAN と EXECUTE は同じマシンを対象とし、台帳には対象が記録され、プレーンをまたぐ呼び出しはエラーになります。設定形式：packaging/targets.example.toml。

ステータス：実績記録

• 🩸 0.49.1：クラスターをまたぐシェル呼び出しと、オペレーターの待ち時間。 名前付き PVE ターゲットがノード名を ssh 接続先に対応付けるため、シェルの行がすべてのノードに届きます（PR #107 から）。PROXIMO_SHELL_TIMEOUT でシェル呼び出し 1 回の待ち時間を 1～600 秒に設定できます（issue #106）。テスト数 4,186。 それ以前のすべてのリリース（すべてのピラー、すべてのレッドチーム、すべての修正）は CHANGELOG.md に記載されています。

数値を正直に： 公開アドレス 1,804 個に対してツールは 6 つです。それぞれのアドレスの性質に基づいて制御します（メソッドによって読み取りか書き込みかが決まり、合計は構造上決まります。影響範囲のティアは人が記入する唯一の列であり、ティア未設定の変更操作は、武装済みかどうかにかかわらず拒否されます）。プロセス内テスト 4,186 件（ruff + pyright はクリーン）が、エンジン、6 つのピラー、各接続口と記録を固定し、ゲートラウンドでは各ピラーのゲートを一度に 1 つずつ無効化して、テストスイートがそれを検知するかを確認します。このワークスペースは Proximo を通じて自らの Proxmox 環境を日々管理しています（ドッグフーディング）。

実環境で実証済み（モックではありません）：この接続口を通じ、実際の PVE 9 ノードに対して制御された経路をエンドツーエンドで検証しています。ライブターゲットを読み取る計画、キー付きチェーン上の実行記録、変更前状態の取得と復元も含みます。0.44 ラッパーの実環境での記録（3 ノードのクラスター、PBS、PMG、PDM、実際のデータセンター間移動）は、実証した場所である CHANGELOG.md に記載されています。コアの実績として再掲してはいません。 未実証のこと — はっきり記します： 小型ローカルモデルが、この接続口を通じてタスク全体を完了すること。0.45 で実測・実行しました。llama.cpp 上で動作する標準の 1.5B モデルを、サーバーが強制する 4,096 トークンのコンテキストで、実際の PVE ノードに対して読み取り専用で試しました。呼び出しは到達し、接続口による拒否では、毎回修正すべき点が示されました（存在しないフィールドに対し、実際に使えるフィールドが列挙されました）。プロンプトは最大 3,074 トークンでした。モデルはタスクを完了できず、数値を捏造しました。コンテキストウィンドウは十分ですが、1.5B モデルの能力は不十分です。ハードウェアウォッチドッグによるフェンシング（物理的な iTCO/IPMI が必要）と、本番規模での動作も未実証です。保留中の 20 個のアドレスは決して実行されません。設計どおり、文章単位で拒否されるものであり、未対応による穴ではありません。

ドキュメント

ライセンス

インフラストラクチャツールに適した特許ライセンス条項を理由に、Apache-2.0 を選択しています。全文は LICENSE をご覧ください。

クレジット

John Broadway が Claude と Maude とともに開発しました。人間と AI のパートナーシップであり、このマシンで初めて作り、世界に公開したものです。Claude Opus 4.8 は信頼性の柱と当初のツール群を構築し、それ以来この取り組みを支えてきました。Claude Fable 5 は 101 エージェントによるリリース監査と初回公開を実施しました。すべてのコミットには共同執筆者のトレーラーが付いています。

「楽しんでいただけましたか？」 スター、イシュー、そして切磋琢磨できる仲間を歓迎します。力と名誉を。 ⚔️