Myrmex Hive

Myrmex Hive：セキュアなエージェントオーケストレーター＆ゲートウェイ

Myrmex Hive は、**Model Context Protocol（MCP）**上に構築された、分散型でセキュア、かつ技術者向けのエージェントオーケストレーションフレームワークです。対象システムでインバウンドポートを一切公開せずに、分散したエッジサーバー、Docker ホスト、Kubernetes ノードを安全に監視、クエリ、管理できるように設計されています。

---

1. アーキテクチャとセキュリティモデル

Myrmex Hive は、対象のエッジシステム（エージェント）をインバウンドのネットワークトラフィックから完全に隔離する必要がある、ゼロトラスト環境向けに設計されています。

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 へのセキュアなアウトバウンド接続を開始します。これにより、公開スキャナーによる検出や自動化されたブルートフォース攻撃という主要な攻撃経路を排除できます。
• OS グレードの暗号化：アウトバウンドトンネルでは、Go のネイティブな crypto/ssh パッケージで管理される標準の SSH プロトコルチャネルを使用し、セキュアな Ed25519 署名の検証と高強度暗号（ChaCha20-Poly1305、AES-GCM）を適用します。
• 多層防御の許可リスト：エージェントはシェル（/bin/sh や bash など）を呼び出すのではなく、OS のプロセスフォーク（os/exec）を通じてバイナリを直接実行します。これによりシェル展開を完全に回避し、シェルインジェクションの脆弱性を無効化します。引数は config.json 内の開発者定義の正規表現に照らして厳密に検証されます。
• 一元化されたトークン認証：ゲートウェイの制御 API へのアクセスは、セキュアなベアラートークン認証によって保護されます。

---

2. クイックスタートとインストール

Myrmex Hive は Go、Nix、Linux、macOS、Windows の環境に対応しています。

Nix / NixOS（宣言的 Flake）

flake.nix の入力に Myrmex Hive を追加します：

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

次の3つのバイナリがインストールされます：myrmex（オペレーター CLI）、myrmex-gateway、myrmex-agent。

macOS のみ対応 — Homebrew cask は Linuxbrew ではサポートされていません。Linux では リリースページ の 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 スクリプトはバイナリをコンパイルし、エージェント設定を C:\ProgramData\mcp-agent\ に登録して OpenSSH キーを生成し、システム起動時にエージェントを起動するバックグラウンドタスクをスケジュールします。

Kubernetes（Helm）

バージョン付きコンテナーイメージと Helm チャートは、リリースのたびに GHCR に公開されます：

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

--version を指定するとチャートとイメージをまとめて固定できます（v1.0.1 以降。v1.0.0 はイメージ／チャートの公開前のバージョンです）。イメージ一覧、エージェントキーを使った動作するインストール例、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 Configuration (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 を設定すると、実際の SSO トークンに対するネイティブ OIDC／JWKS 検証が有効になります（オプトイン。静的トークンも引き続き使用できます）。docs/SECRETS.md を参照してください。

注：metrics_enabled を設定すると、/metrics に Prometheus エンドポイントが公開されます（オプトイン。API の他の部分と同じベアラートークン認証で保護されます）。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 を設定すると、該当するティアの呼び出しは 2 人目のオペレーターによる承認（myrmex approvals）待ちになります。また、新しい承認リクエストが保留になると、設定済みのアラート送信先にも通知されるため、気づかれないまま期限切れになることはありません。有効期間は 15 分です。
• rate_limit_per_minute は、スライディング方式の 60 秒間に実行できるツール呼び出し数を制限します。
• scheduled_tasks は、エージェントに対して LLM オーケストレーションプロンプトを定期的に実行し、その要約をアラートサブシステム経由でルーティングします。これにより、フリートのヘルスチェックを無人で実施できます。interval_seconds のみを使用し、cron は使用しません。

この 6 つのゲートの連携と段階的なロールアウトについては、Golden Path を参照してください。

フェイルクローズのデフォルト

Myrmex Gateway はフェイルクローズで動作します。安全でない状態で実行するのではなく、起動を拒否するか、接続を拒否します。設定と鍵を準備する際は、次の 3 つのルールが適用されます。

1. authorized_keys のコメント = agent-id（ID の紐付け）。 Gateway は、接続された各エージェントの ID を authorized_keys エントリのコメントから取得し、コメントが空の場合、またはエージェントが提示する agent_id と一致しない場合、その鍵を拒否します。各エージェントの鍵は、コメントに 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 がない場合（エージェントの許可リストがない場合）も、Gateway は起動を拒否します。

3. エージェントは Gateway のホスト鍵を検証します。 デフォルトでは、エージェントは**初回接続時信頼（TOFU）**を使用します。初回接続時に 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）は、すでに 3 つのルールすべてに準拠しています。エージェント鍵のコメントにはそれぞれの agent-id が記載され、永続的な test_env/gateway/host_key が生成されてマウントされ、エージェントは TOFU を使用します。

---

4. ローカル LLM のセットアップ（Ollama と Gemma 4）

Myrmex Hive は、ローカル LLM を使用してアクションをオーケストレーションし、出力を解釈します。

オプション A：Docker サイドサービスとして実行する（推奨）

gemma4:e4b モデルがプリロードされたオプションの Docker セットアップを、docker-compose.test.yml のプロファイルから利用できます（オフラインですぐに使用可能です）。

• 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 を使うと、オペレーターはゲートウェイを操作し、エージェントを表示し、ツールを呼び出し、ターミナルからアシスタントを直接起動できます。

グローバルオプション

• --url：ゲートウェイ API のベース URL（デフォルト：https://localhost:8080）
• --token：ゲートウェイトークン（または環境変数 MYRMEX_TOKEN）
• -o、--output：出力形式（text または json）

CLI コマンドリファレンス

• ステータス：接続されているエッジエージェントと設定済みのアップストリームサーバーを表示します：

  myrmex status
  

• エージェント：接続されているすべてのエージェントの詳細な仕様を一覧表示します：

  myrmex agents
  

• ツール：スウォーム全体で利用可能なすべてのツールを一覧表示します：

  myrmex tools
  

• 呼び出し：特定のエージェント上でツールを実行します。ペイロードのマスク解除とエスケープ解除は自動的に行われます：

  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 の応答を、他の自動化ツールやエージェントに直接渡します：

  myrmex ask "Check system metrics" -o json
  

• プラン（ドライラン）モードで質問する：各ステップでモデルへの問い合わせは行われますが、ツールは実行されません。応答には、実行されるはずだった呼び出しが一覧表示されます。ループに任せる前にアクションをプレビューするために使用します：

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

• フリート全体のオーケストレーション：複数のエージェントに同じオーケストレーションを実行し、エージェントごとの要約を集約します。接続されているすべてのエージェントには --all を、対象を絞るには --agents を使用します（フリート全体のプレビューには --plan を組み合わせます）：

  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 モデルが、引数 {"cmd":"top"}（または許可された診断スクリプト）を指定した agent-db__run_command が許可リストで利用可能であることを特定します。
4. オーケストレーターがツールを実行してログを解析し、整形されたレポートをターミナルに直接表示します。

シナリオ B：Antigravity SDK との統合

Antigravity SDK エージェントなど、他の自動化 AI システムから Myrmex Hive をプログラムで簡単に操作できます。 ゲートウェイは、安全なベアラートークンで保護された標準エンドポイント（/api/chat および /api/call）を公開します。Antigravity エージェントはエンドポイントにクエリを送信し、構造化されたツールリストのペイロードを受け取り、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. 監査イベントを記録して検証する：このリクエストには書き込みに似た評価手順が含まれるため、ゲートウェイはタイムスタンプ、トークンのロール（operator）、API ルート（/api/chat）、および base64 署名を記録した、暗号署名付きのエントリを audit.log に書き込みます。セキュリティ監査担当者は、ゲートウェイの公開 SSH ホストキーを使ってログの真正性を検証します。

シナリオ D：独自サービスのテストとカオステスト

開発者は、SSH 接続せずに、実際のホスト上でサービスを実行し、停止させ、監視して、再起動したいと考えています。

1. ハーネスを許可リストに登録する。機能を作り込まないでください。examples/service-test-harness/ のエントリをコピーします。固定の動詞セット（cpu、mem、latency、loss、kill）を持つ chaos.sh、指定したホストに固定されたプローブ、設定バリエーション用の適用スクリプトを使用します。
2. 何かを停止させる前に、復旧を確認する。まずゲートウェイ経由でサービスを再起動します。再起動経路が機能しないなら、障害を注入するべきではありません。
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. VM の分離：Myrmex Gateway を、プライベート VPC 内のセキュアな Compute Engine VM にデプロイします。IAM ロールを適用するため、ゲートウェイの制御インターフェース（:8080）へのアクセスは Identity-Aware Proxy（IAP） 経由のみにします。
2. Kubernetes エージェント：Myrmex Agents を Google Kubernetes Engine（GKE）上に DaemonSet としてデプロイし、GKE ノードのリソースを自動的に監視、管理します。
3. シークレットのセキュリティ：ゲートウェイの認証トークンを設定ファイルに保存しないでください。起動時に Google Secret Manager からトークンを動的に取得します。

---

8. エアギャップ環境のデータセンター

高度にセキュアなエアギャップシステムでは：

• Myrmex Hive は、パブリック DNS や外部インターネットへのアクセスを必要としません。
• ゲートウェイサーバーに Ollama をローカルでデプロイします。Ollama と Myrmex Gateway は同じローカルネットワークで実行されるため、LLM の推論はすべてエアギャップの境界内で行われます。
• エージェントはローカルサブネット経由で内部的に SSH トンネルを確立し、完全にエアギャップで監査可能な管理プレーンを維持します。