solfleet

solfleet

独立した Solana バリデーターと RPC ノードのための、エージェントに安全なフリート管理ツールです。1 つの設定ファイルで、devnet、testnet、mainnet にまたがるフリートを記述できます。MCP サーバー（および CLI）を通じて、Solana に対応したステータス、安全なインプレースアップグレード、ヘルス状態に基づく DNS フェイルオーバーを Claude または任意の MCP クライアントに提供します。ノードを変更するすべての操作は、デフォルトでドライランとなり、ポリシーによるゲート制御と監査が行われます。solfleet がキーペアを読み取ったり移動したりすることはありません。

ロードマップと設計メモについては、PLAN.md をご覧ください。

アーキテクチャ

solfleet はオペレーターのマシン（または小規模な VM）で動作します。JSON-RPC（読み取り）と SSH/scp（操作）を使ってフリートと通信し、別のビルドホストでアーティファクトをビルドし、各クラスターの参照 RPC に対するスロット遅延を算出して、DNS プロバイダーのフェイルオーバーレコードを管理します。すべての変更は 1 つのゲートを通り、SQLite の監査ログに記録されます。

flowchart TB
  claude["Claude / any MCP client"]

  subgraph operator["operator machine"]
    mcp["solfleet-mcp (stdio)"]
    cli["solfleet CLI"]
    core["core: probe · safety gate · executor · dns"]
    audit[("audit log (SQLite)")]
    claude -->|MCP| mcp
    mcp --> core
    cli --> core
    core --> audit
  end

  builder["build host (agave + geyser from source)"]
  ref["cluster reference RPC"]
  dns["DNS provider (Cloudflare / Route53)"]

  subgraph fleet["fleet: devnet / testnet / mainnet"]
    rpc["RPC nodes"]
    val["voting validators"]
  end

  core -->|JSON-RPC :8899| rpc
  core -->|JSON-RPC :8899| val
  core -->|SSH / scp| rpc
  core -->|SSH / scp| val
  core -->|SSH build, fetch artifacts| builder
  builder -. "artifact set + sha256" .-> core
  core -->|slot lag / delinquency| ref
  core -->|eject / restore A records| dns

インプレースアップグレードの実行方法

sequenceDiagram
  actor Op as Claude / operator
  participant SF as solfleet
  participant B as build host
  participant N as node
  participant R as reference RPC
  Op->>SF: upgrade node to version (confirm)
  SF->>SF: gate, policy + preflight (else stop)
  SF->>B: build agave + geyser (or reuse cache)
  B-->>SF: artifact set + sha256
  SF->>N: scp artifacts as dest.solfleet-new
  SF->>N: sha256 on node matches builder (else abort)
  alt RPC node
    SF->>N: systemctl stop
    SF->>N: atomic swap (binary + geyser + marker)
    SF->>N: systemctl start
  else voting validator
    SF->>N: atomic swap (binary + geyser + marker)
    SF->>N: agave-validator exit (leader-aware), systemd relaunches
  end
  loop until healthy and caught up
    SF->>R: getSlot
    SF->>N: getHealth / getSlot
  end
  SF->>SF: verify reported version, write audit entry

フェイルオーバーの実行方法

sequenceDiagram
  participant SF as solfleet watch
  participant N as pool members
  participant R as reference RPC
  participant D as DNS provider
  loop every interval
    SF->>N: getHealth / getSlot
    SF->>R: getSlot (cluster head)
    SF->>SF: per member: unhealthy, lag over limit, or delinquent
    alt every member failing
      SF->>SF: keep current records (never empty the pool)
    else at least one healthy
      SF->>D: ensure TXT ownership marker
      SF->>D: remove A record of each failing member
      SF->>D: add A record of each recovered member
      SF->>SF: write audit entry
    end
  end

特長

• Solana に対応したヘルスチェック。 汎用的なヘルスチェックでは HTTP 200 が返ることを確認しますが、Solana ノードは 500 スロット遅れていても 200 を返すことがあります。solfleet はクラスターに対するスロット遅延、非稼働状態、バージョンの差異を確認します。
• ビルドと配布。 Agave v3.0 ではビルド済みバリデーターバイナリが廃止されたため、すべてのオペレーターがソースからビルドする必要があります。solfleet は専用のビルダー・ノードで一度だけビルドし（ABI に適合する Yellowstone geyser .so とともに）、キャッシュしてから、アーティファクト一式をフリートに配布します。
• リーダーを考慮した再起動。 投票中のバリデーターを自身のリーダースロット中に再起動すると、ブロックがスキップされます。solfleet はリーダーを考慮したセーフエグジットを使ってバリデーターを再起動し、RPC ノードは systemctl で順に切り替えます。
• 安全なフェイルオーバー。 監視ループは、遅延または異常のあるノードを DNS から除外し、復旧後に戻します。また、プールが空になることを防ぎます。

ステータス

v1 を実装済みで、単体テストも完了しています（91 件のテスト、Python 3.11～3.13 で CI を実施）。また、ほとんどの処理は、使い捨ての devnet ノードと実際の Cloudflare ゾーンを使ってライブ環境でも実証済みです。

ライブ環境で実証済み：

• 読み取り処理：status、validate、vote-status、inspect
• restart（RPC は systemctl、バリデーターはリーダーを考慮したセーフエグジットを使用）
• RPC ノードと投票中のバリデーター・ノードの両方について、インプレースの upgrade をエンドツーエンドで実施（ビルダー上で Agave をソースからビルドし、配布し、ターゲットで sha256 を検証し、アトミックスワップを行って追いつくまで確認）
• bootstrap-builder（何もないビルダーにツールチェーンと依存関係をセットアップ）
• ディスクだけの状態から投票中のバリデーターを provision（NVMe をフォーマットし、インストールし、投票ユニットを生成して、起動、同期、投票を実施）
• ライブの Cloudflare ゾーンに対する DNS ドライバーと dns status / eject / restore、および最後のメンバーを除外しない保護

単体テスト済みですが、ライブ環境では未実行：

• 自律的な watch ループ（調査 -> 判断 -> 操作）。判断ロジックは単体テスト済みで、実証済みの Cloudflare ドライバーを再利用します。
• Route53 ドライバー（接続先となる AWS ゾーンがまだありません）

未実装：HTTP トランスポート（現在、MCP は stdio のみ）。PLAN.md（M6）をご覧ください。

インストール

pipx install solfleet            # not yet published; for now:
pipx install git+https://github.com/sanjeevkkansal/solfleet
pipx install 'solfleet[route53]' # if you use Route53 for DNS

クイックスタート

cp fleet.example.yaml fleet.yaml     # edit with your nodes
cp policy.example.yaml policy.yaml   # optional; sane defaults if absent
solfleet status                      # probe the fleet
solfleet status --watch              # refreshing live table
solfleet validate                    # structural + live readiness check
solfleet vote-status mn-val-1        # voting health: credits, balance, delinquency, leader
solfleet inspect mn-val-1            # read-only SSH detail for one node
solfleet bootstrap-builder b1        # install build toolchain on a builder; --confirm
solfleet provision rpc-1 4.1.0       # dry-run bring-up plan; --confirm to run
solfleet plan-upgrade mn-val-1 4.1.0 # dry-run upgrade plan
solfleet upgrade mn-val-1 4.1.0      # dry-run; add --confirm to execute
solfleet watch --dry-run             # DNS failover loop, decide-only

MCP（Claude Code）：

claude mcp add solfleet -- solfleet-mcp

セッション例

小規模な devnet フリートを対象にしています。フラグを指定しない場合、コマンドは読み取り専用またはドライランで実行されます。

フリートのヘルス状態は、単なる HTTP 200 ではなく、Solana に対応して確認されます：

$ solfleet status
CLUSTER  NODE   ROLE  HEALTH  VERSION     SLOT LAG  VOTE
devnet   rpc-1  rpc   ok      4.1.0-rc.1  0         -
devnet   rpc-2  rpc   ok      4.1.0-rc.1  0         -

アップグレードはデフォルトでドライランです。順序付きの実行計画とゲートの判定が返されます。--confirm を渡すまでは何も変更されません：

$ solfleet plan-upgrade rpc-1 4.1.0
{
  "decision": {
    "operation": "upgrade",
    "cluster": "devnet",
    "node": "rpc-1",
    "mode": "dry-run",
    "allowed": true,
    "plan": [
      "on builder 'build-1': build agave 4.1.0 from source",
      "distribute artifact set to rpc-1; checksum-verify each (abort on mismatch)",
      "stop solana-validator, swap, start",
      "swap /usr/local/bin/agave-validator + geyser .so + version marker atomically",
      "wait until healthy + caught up to https://api.devnet.solana.com",
      "verify reported version == 4.1.0; record before/after"
    ],
    "reasons": [
      "dry-run: preflight checks pass; pass confirm=true to execute"
    ]
  },
  "target_version": "4.1.0"
}

MCP では、同じ操作をツール（fleet_status、plan_node_upgrade、upgrade、...）として利用できます。Claude には同じ実行計画が返され、実行には confirm=true の指定が必要なため、エージェントが誤ってノードを変更することはありません。

ツール

読み取り専用：fleet_status、node_detail、version_drift、vote_status、 leader_schedule、validate、plan_node_upgrade、dns_pool_status、 audit_log。

実行に確認が必要（デフォルトではドライラン。実行するには confirm=true を指定）： bootstrap_builder_host、provision、restart、upgrade、 dns_pool_eject、dns_pool_restore。

すべての変更操作はデフォルトでドライランとなり、policy.yaml （許可されるバージョン、ディスク容量の下限、リーダー期間の最小値）に照らしてチェックされ、 SQLite の監査ログに記録されます。監視ループは唯一の自律的な変更操作ですが、同じ監査ログと プールを空にしないルールによって制限されています。

安全モデル

• デフォルトでドライラン。 confirm=true を指定して呼び出さない限り、変更操作は実行順のプランと 事前チェックの結果を返します。
• ポリシーゲート。 クラスターごとの policy.yaml で、許可されるバージョンの glob、ディスク容量の 下限、バリデーターに対する require_leader_window_minutes を設定します。
• チェックサム検証済みの配布。 アップグレード用アーティファクトは、切り替え前にターゲット上で ビルダーと照合して sha256 チェックを行います。
• キーは一切扱いません。 solfleet は ID／投票キーペアを読み取ることも、移動することも、 生成することもありません。投票バリデーターの ID フェイルオーバーは、ダブルサイニングのリスクがあるため、 設計上対象外です。
• 監査ログ。 すべてのドライランと実行内容が SQLite に記録されます。

開発

uv venv && uv pip install -e '.[dev]'
uv run pytest

MCP レジストリ

MCP Registry に公開されています。

mcp-name: io.github.sanjeevkkansal/solfleet