Myrmex Hive

Myrmex Hive：安全的 Agent 编排与网关

Myrmex Hive 是基于 Model Context Protocol（MCP） 构建的去中心化、安全且极客风格的 Agent 编排框架。它旨在安全地监控、查询和管理分布式边缘服务器、Docker 主机和 Kubernetes 节点，而无需在目标系统上暴露任何入站端口。

---

1. 架构与安全模型

Myrmex Hive 专为零信任环境设计，在这类环境中，目标边缘系统（Agent）必须与直接入站网络流量完全隔离。

flowchart TD
    %% Node Definitions
    subgraph Edge ["Target Edge Node (Myrmex Agent)"]
        Agent["Myrmex Agent<br/>(CPU/Mem/Disk, strict allowlist)"]
    end

    subgraph Gateway ["Central Hive Gateway"]
        SSHD["Secure SSHD Receiver<br/>(Port 2222)"]
        Orch["Myrmex Hive Orchestrator"]
        LLM["Ollama LLM<br/>(Gemma 4/2)"]
    end

    Client["Client / CLI / Portal<br/>(Stdio / SSE MCP Interface)"]

    %% Connections
    Agent -- "SSH Outbound Tunnel" --> SSHD
    SSHD -- "JSON-RPC over SSH channel" --> Orch
    Orch <--> LLM
    Client <--> Orch

    %% Styling / Colors
    classDef edgeNode fill:#282828,stroke:#fabd2f,stroke-width:2px,color:#ebdbb2;
    classDef gatewayNode fill:#282828,stroke:#fe8019,stroke-width:2px,color:#ebdbb2;
    classDef clientNode fill:#282828,stroke:#b8bb26,stroke-width:2px,color:#ebdbb2;

    class Agent edgeNode;
    class SSHD,Orch,LLM gatewayNode;
    class Client clientNode;

安全原则（为何做出这些选择）

• 零入站端口：目标服务器不运行 SSH 守护进程，也不暴露管理端口（如 HTTP/gRPC），而是由 Myrmex Agent 主动向 Myrmex Gateway 发起安全的出站连接。这样可以消除公开扫描器发现和自动暴力破解攻击这一主要攻击途径。
• 操作系统级加密：出站隧道使用通过 Go 原生 crypto/ssh 包管理的标准 SSH 协议通道，并强制执行安全的 Ed25519 签名验证和高强度加密算法（ChaCha20-Poly1305、AES-GCM）。
• 纵深防御白名单：Agent 通过操作系统进程派生（os/exec）直接执行二进制文件，而不是调用 Shell（如 /bin/sh 或 bash）。这完全绕过了 Shell 扩展，从而消除 Shell 注入漏洞。参数会根据 config.json 中由开发者定义的正则表达式进行严格验证。
• 集中式令牌授权：Gateway 控制 API 的访问受安全的 Bearer 令牌身份验证保护。

---

2. 快速入门与安装

Myrmex Hive 支持 Go、Nix、Linux、macOS 和 Windows 环境。

Nix / NixOS（声明式 Flake）

将 Myrmex Hive 添加到 flake.nix 输入中：

inputs.myrmex-hive.url = "github:olafkfreund/myrmex-hive";

然后即可直接运行 CLI 工具：

nix run github:olafkfreund/myrmex-hive#myrmex -- --help

要在 NixOS 上将 Myrmex Agent 或 Gateway 部署为声明式 systemd 服务，请在 configuration.nix 中启用该模块：

{ inputs, config, pkgs, ... }: {
  imports = [ inputs.myrmex-hive.nixosModules.default ];

  services.myrmex-hive = {
    enable = true;
    role = "agent"; # Or "gateway"
    configPath = "/etc/myrmex/agent_config.json";
  };
}

macOS（Homebrew）

brew tap olafkfreund/myrmex
brew install --cask myrmex-hive

安装全部三个二进制文件：myrmex（运维人员 CLI）、myrmex-gateway 和 myrmex-agent。

仅限 macOS — Linuxbrew 不支持 Homebrew cask。在 Linux 上，请使用 releases page 中的 deb/rpm 软件包、Nix flake、install.sh 或容器映像。

Linux 与 macOS（直接安装）

下载、编译并将 Agent 配置为后台守护进程（Linux 上使用 systemd，macOS 上使用 LaunchDaemon）：

sudo ./install.sh

安装程序会自动编译 Agent 二进制文件、生成安全的 Ed25519 密钥、写入 config.json 并启动服务。

Windows（PowerShell 脚本）

要在 Windows Server 或 Windows 10/11 上安装 Agent，请以管理员身份启动 PowerShell 并运行：

Set-ExecutionPolicy Bypass -Scope Process -Force
.\install.ps1

PowerShell 脚本会编译二进制文件、将 Agent 配置注册到 C:\ProgramData\mcp-agent\、生成 OpenSSH 密钥，并安排一个后台任务在系统启动时启动 Agent。

Kubernetes（Helm）

每次发布时，都会将带版本号的容器映像和 Helm chart 发布到 GHCR：

helm install hive oci://ghcr.io/olafkfreund/charts/myrmex-hive \
  --version 1.2.0 \
  --namespace myrmex --create-namespace

--version 会将 chart 和映像固定为相同版本（v1.0.1+；v1.0.0 发布早于 映像/chart 发布功能）。有关映像列表、包含 Agent 密钥的可用安装示例，以及 TLS/Service/agent_id 注意事项，请参阅 docs/DEPLOYMENT.md。

---

3. 配置

Agent 配置（agent_config.json）

允许你定义单个网关地址或多个网关地址列表，以便进行高可用（HA）故障转移轮询：

{
  "agent_id": "agent-nginx",
  "gateway_addr": "gateway-1.internal:2222",
  "gateway_addrs": [
    "gateway-1.internal:2222",
    "gateway-2.internal:2222"
  ],
  "private_key_path": "/etc/mcp-agent/id_ed25519",
  "allowed_commands": [
    {
      "name": "uptime",
      "args_regex": "^$"
    },
    {
      "name": "systemctl",
      "args_regex": "^(status|restart) (nginx|postgresql)$"
    }
  ]
}

Gateway 配置（gateway_config.json）

配置接收端、TLS 证书、OIDC/令牌 RBAC 角色映射（admin、operator、read-only）以及签名审计日志路径：

{
  "listen_addr": ":2222",
  "http_addr": ":8080",
  "host_key_path": "host_key",
  "authorized_keys_path": "authorized_keys",
  "ollama_url": "http://localhost:11434",
  "ollama_model": "gemma4:e4b",
  "auth_token": "fallback_admin_token",
  "tokens": {
    "admin-token-123": "admin",
    "operator-token-456": "operator",
    "read-token-789": "read-only"
  },
  "audit_log_path": "audit.log",
  "metrics_enabled": true
}

注意：如果设置了 audit_log_path，Myrmex Gateway 会记录所有 /api/call 和 /api/chat 执行，并使用 Gateway 的 SSH 私钥生成加密签名。

注意：oidc_issuer 可启用原生 OIDC/JWKS 验证，以验证真实的 SSO 令牌（可选启用；静态令牌仍可同时使用）。参见 docs/SECRETS.md。

注意：metrics_enabled 会在 /metrics 暴露 Prometheus 端点（可选启用；使用与 API 其他部分相同的 bearer-token 身份验证）。Myrmex Gateway 还可以将阈值告警路由至 webhook/Alertmanager，并通过 OTLP 导出 OpenTelemetry 跟踪数据——均为可选启用。有关指标参考、scrape_config、Grafana 仪表板、告警路由和跟踪数据，请参见 docs/OBSERVABILITY.md。

治理与调度（均为可选启用，向后兼容——留空/未设置表示关闭）：

{
  "risk_tiers": { "run_command": "admin", "service_control": "write" },
  "require_approval_tiers": ["write", "admin"],
  "rate_limit_per_minute": 30,
  "scheduled_tasks": [
    { "name": "nightly-disk-check", "agent_id": "agent-nginx",
      "prompt": "Report disk usage and flag anything over 85%", "interval_seconds": 3600 }
  ]
}

• risk_tiers 对每个工具分类（read/write/admin）。内置的变更型工具（service_control、run_command）现在即使未列出，也默认归入非 read 层级，因此无法在未分类的情况下绕过门控；你显式设置的条目仍具有优先权。
• require_approval_tiers 会让这些层级中的调用等待第二位操作员审批（myrmex approvals）；新建的待审批请求还会通知你配置的告警目标，以免其在无人察觉时过期。有效期为 15 分钟。
• rate_limit_per_minute 限制滑动 60 秒窗口内的工具调用次数。
• scheduled_tasks 会定期针对 Agent 执行大模型编排提示词，并通过告警子系统路由摘要——用于无人值守的设备群运行状况检查。仅支持 interval_seconds（不支持 cron）。

请参见 Golden Path，了解这六道门控如何协同工作以及分阶段推出的方式。

默认采用失败关闭策略

Myrmex Gateway 采用失败关闭策略：如果处于不安全状态，它会拒绝启动（或拒绝连接），而不是继续运行。准备配置和密钥时，会强制执行以下三条规则：

1. authorized_keys 注释 = agent-id（身份绑定）。 Gateway 从每个已连接 Agent 的 authorized_keys 条目注释中获取其身份，并拒绝注释为空或与 Agent 提供的 agent_id 不匹配的密钥。生成每个 Agent 密钥时，都要将其 agent-id 设为注释：

   ssh-keygen -t ed25519 -f id_ed25519 -N "" -C "agent-nginx"
   

   随后，authorized_keys 中的公钥行必须保留该注释（ssh-ed25519 AAAA... agent-nginx）。

2. 设置 audit_log_path 时必须指定持久的 host_key_path。 审计条目使用 Gateway 的 SSH 主机密钥签名，因此临时密钥（重启时会重新生成）会导致过去的签名无法验证。如果设置了 audit_log_path，但 host_key_path 为空，Gateway 会拒绝启动。生成一次稳定的主机密钥，并将 host_key_path 指向它：

   ssh-keygen -t ed25519 -f host_key -N "" -C "myrmex-gateway"
   

   如果未设置 authorized_keys_path（没有 Agent 允许列表），Gateway 同样会拒绝启动。

3. Agent 会验证 Gateway 主机密钥。 默认情况下，Agent 使用首次使用时信任（TOFU）：首次连接时，Agent 会获取并持久保存 Gateway 主机密钥至 <private_key_path>.gateway_hostkey（可通过 known_host_key_path 覆盖），此后要求密钥匹配——无需更改配置。若要显式固定密钥，可在 agent_config.json 中设置 gateway_host_key，并填入 Gateway 主机公钥行：

   { "gateway_host_key": "ssh-ed25519 AAAA... myrmex-gateway" }
   

本地测试夹具（generate_keys.sh、setup_test_env.sh）已满足以上三项要求：Agent 密钥的注释中包含对应的 agent-id，会生成并挂载持久的 test_env/gateway/host_key，且 Agent 使用 TOFU。

---

4. 本地大模型设置（Ollama 和 Gemma 4）

Myrmex Hive 使用本地大模型编排操作并解读输出。

选项 A：作为 Docker 辅助服务运行（推荐）

docker-compose.test.yml 中提供了通过配置文件预加载 gemma4:e4b 模型的可选 Docker 设置（可离线使用）：

• 仅 CPU 模式：

  docker compose --profile ollama-cpu up -d
  

• GPU 加速模式（需要 NVIDIA Container Toolkit）：

  docker compose --profile ollama-gpu up -d
  

选项 B：手动在主机上设置

1. 在你的 Gateway 服务器上安装 Ollama。
2. 拉取所需模型（Gemma 4）：

   ollama pull gemma4:e4b
   

3. 确保 Ollama 正在运行且可访问（默认地址为 http://localhost:11434）。在 gateway_config.json 中关联它。

---

5. 使用 Myrmex CLI（myrmex）

基于 Go 的 Myrmex CLI 允许运维人员与网关交互、查看 Agent、调用工具，并直接从终端启动助手。

全局选项

• --url：Gateway API 基础 URL（默认值：https://localhost:8080）
• --token：Gateway 令牌（或 MYRMEX_TOKEN 环境变量）
• -o、--output：输出格式（text 或 json）

CLI 命令参考

• 状态：查看已连接的边缘 Agent 和已配置的上游服务：

  myrmex status
  

• Agent：列出所有已连接 Agent 的详细规格：

  myrmex agents
  

• 工具：列出整个集群中的所有可用工具：

  myrmex tools
  

• 调用：在指定 Agent 上执行工具。自动取消载荷掩码并反转转义：

  myrmex call agent-nginx__get_metrics
  

• 以 JSON 格式调用：直接将整洁的原始 JSON 载荷输出到标准输出（非常适合通过管道传递给 jq）：

  myrmex call agent-nginx__get_metrics -o json | jq '.cpu_usage_percent'
  

• 询问：提示 Myrmex AI 助手进行分析并执行操作。终端输出采用美观的等宽字体 Markdown 样式：

  myrmex ask "Is nginx running on agent-nginx? If not, restart it."
  

• 以 JSON 格式询问：将最终 AI 响应直接转发给其他自动化工具或 Agent：

  myrmex ask "Check system metrics" -o json
  

• 计划（试运行）模式下询问：模型仍会在每一步进行调用，但不会执行任何工具——响应会列出原本会执行的调用。可在信任整个循环前用它预览操作：

  myrmex ask --plan "Restart nginx on agent-nginx if it looks wedged"
  

• 全体 Agent 编排：在多个 Agent 上运行相同的编排，并汇总每个 Agent 的摘要。使用 --all 指定所有已连接的 Agent，或使用 --agents 指定部分 Agent（结合 --plan 可预览全体 Agent 的操作）：

  myrmex ask --all "Report disk usage and flag anything over 85%"
  myrmex ask --agents agent-1,agent-2 "How busy are these two?"
  

---

6. 实际编排场景

场景 A：自动化集群恢复

运维人员发出查询： myrmex ask "Check load average on agent-db. If it's over 4.0, run diagnostic logs and let me know what process is consuming CPU."

1. 编排器调用 agent-db__get_metrics。
2. 编排器解析返回的指标 JSON。
3. 如果负载超过 4.0，本地 Gemma 模型会确认允许列表中提供了 agent-db__run_command（参数为 {"cmd":"top"}）或获准的诊断脚本。
4. 编排器执行工具、解析日志，并直接在终端中展示整洁、格式化的报告。

场景 B：与 Antigravity SDK 集成

你可以轻松地通过其他自动化 AI 系统（例如 Antigravity SDK Agent）以编程方式驱动 Myrmex Hive。 网关提供由安全 bearer 令牌保护的标准端点（/api/chat 和 /api/call）。你的 Antigravity Agent 可以查询端点、接收结构化工具列表载荷，并通过 SSH 隧道触发操作。

场景 C：隔离网中的 Gemma 4 部署与加密审计

企业管理员使用可离线运行的 Ollama 侧服务，配置安全且完全经过合规审计的本地助手：

1. 启动 Ollama：管理员在 Docker 中启动预加载的、仅使用 CPU 的 Gemma 4 侧服务：

   docker compose --profile ollama-cpu up -d
   

2. 配置网关：在 gateway_config.json 中，将网关连接到 Ollama 端点：

   "ollama_url": "http://myrmex-ollama-cpu:11434",
   "ollama_model": "gemma4:e4b"
   

3. 执行操作员请求：操作员执行经过合规审计的 CLI 查询：

   myrmex ask "Verify the nginx server is running on agent-nginx" --token "operator-token-456"
   

4. 记录并验证审计事件：由于请求包含类似写入的评估步骤，网关会在 audit.log 中记录一条经过加密签名的条目，其中显示时间戳、令牌角色（operator）、API 路由（/api/chat）和 base64 签名。安全审计员使用网关的 SSH 公钥验证日志的真实性。

场景 D：测试和混沌测试自己的服务

开发者希望在真实主机上运行、破坏、观察并重启服务，而无需通过 SSH 登录。

1. 将测试工具加入允许列表，不要构建新功能。复制 examples/service-test-harness/ 中的条目：包含固定动词集（cpu、mem、latency、loss、kill）的 chaos.sh、固定指向你指定主机的探测工具，以及用于配置变体的应用脚本。
2. 在造成任何故障之前，先验证恢复能力。 先通过 Gateway 重启服务——如果重启流程不起作用，就不该注入故障。
3. 注入并观察。 故障有时间限制且会自动恢复，并会立即返回，让你可以在故障发生时观察其影响：

   myrmex call web-1__run_command --arguments '{"name":"/opt/myrmex/chaos.sh","args":["latency","60","250","eth0"]}'
   # → latency: applied 250 on eth0, auto-reverts in 60s
   

4. 获取记录。 每次注入都会写入经过签名的审计日志，因此混沌测试会留下防篡改证据，记录哪些故障在何时影响了哪些主机。

完整指南：docs/SERVICE_TESTING.md。

---

7. GCP 最佳实践

对于部署在 Google Cloud Platform 上的云端：

1. 虚拟机隔离：在私有 VPC 内的安全 Compute Engine 虚拟机上部署 Myrmex Gateway。仅通过 Identity-Aware Proxy (IAP) 暴露 Gateway 的控制接口（:8080），以强制执行 IAM 角色。
2. Kubernetes Agent：在 Google Kubernetes Engine (GKE) 上以 DaemonSet 形式部署 Myrmex Agent，以自动监控和管理 GKE 节点资源。
3. 密钥安全：避免将 Gateway 身份验证令牌存储在配置文件中。启动时从 Google Secret Manager 动态获取令牌。

---

8. 隔离网数据中心

在高度安全的隔离网系统中：

• Myrmex Hive 无需公共 DNS 或外部互联网访问。
• 在 Gateway 服务器上本地部署 Ollama。由于 Ollama 和 Myrmex Gateway 在同一本地网络中运行，大模型推理完全在隔离网边界内进行。
• Agent 通过本地子网在内部建立 SSH 隧道，从而维持完全隔离且可审计的管理平面。