solfleet

solfleet

面向独立 Solana 验证器和 RPC 节点的 Agent 安全舰队管理工具。一个配置文件即可描述你在 devnet、testnet 和 mainnet 上的舰队。MCP 服务（以及 CLI）向 Claude 或任何 MCP 客户端提供 Solana 感知型状态、安全的原地升级，以及由健康状况驱动的 DNS 故障转移。默认情况下，所有会更改节点的操作都采用试运行模式，并受策略门控且会记录审计日志。solfleet 绝不会读取或移动你的密钥对。

路线图和设计说明见 PLAN.md。

架构

solfleet 在操作者的机器（或小型 VM）上运行。它通过 JSON-RPC（读取）和 SSH/scp（执行操作）连接舰队，在独立的构建主机上构建制品，根据各集群的参考 RPC 计算 slot 延迟，并在 DNS 提供商处管理故障转移记录。所有变更都经过同一个门控，并写入 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 个 slot，仍可能返回 200。solfleet 会检查相对于集群的 slot 延迟、掉队情况和版本偏差。
• 构建并分发。 Agave v3.0 不再提供预构建的验证器二进制文件，因此现在每位操作者都必须从源码构建。solfleet 会在专用构建节点上构建一次（包含 ABI 匹配的 Yellowstone geyser .so），缓存构建结果，并将整套制品分发到舰队。
• 感知领导者的重启。 在投票验证器自己的领导者 slot 期间重启它会跳过区块。solfleet 会通过感知领导者的安全退出机制重启验证器；RPC 节点则通过 systemctl 轮换。
• 安全故障转移。 监控循环会将延迟或不健康的节点从 DNS 中移除，并在节点恢复后将其还原，同时拒绝清空任何地址池。

状态

v1。已完成构建并通过单元测试（91 项测试，CI 覆盖 Python 3.11-3.13）。大多数路径也已在一次性 devnet 节点和真实 Cloudflare 区域上进行了实测验证。

已通过实测验证：

• 读取路径：status、validate、vote-status、inspect
• restart（RPC 通过 systemctl；验证器通过感知领导者的安全退出机制）
• 端到端原地 upgrade（在构建主机上从源码构建 agave、分发、在目标节点上通过 sha256 校验、原子切换、追赶），适用于 RPC 和投票验证器节点
• bootstrap-builder（在全新构建主机上安装工具链和依赖项）
• 从空白磁盘开始 provision 投票验证器（格式化 NVMe、安装、生成投票服务单元、启动、追赶、投票）
• DNS 驱动程序，以及针对实时 Cloudflare 区域的 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 舰队。不带任何标志时，命令只读或以试运行模式运行。

舰队健康状况感知 Solana 状态，而不只是检查 HTTP 200：

$ 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 才能执行，因此 Agent 不会意外更改节点。

工具

只读：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 不会读取、移动或生成身份密钥对或投票密钥对。按设计，投票验证节点的身份故障转移不在范围内（存在双重签名风险）。
• 审计日志。 每次试运行和执行都会记录在 SQLite 中。

开发

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

MCP 注册表

已发布到 MCP Registry。

mcp-name: io.github.sanjeevkkansal/solfleet