Myrmex Hive

Myrmex Hive: Secure Agent Orchestrator & Gateway

Myrmex Hive is a decentralized, secure, and geeky agent orchestration framework built on top of the Model Context Protocol (MCP). It is designed to securely monitor, query, and manage distributed edge servers, Docker hosts, and Kubernetes nodes without exposing any ingress ports on your target systems.

---

1. Architecture & Security Model

Myrmex Hive is designed for zero-trust environments where target edge systems (agents) must remain completely isolated from direct inbound network traffic.

flowchart TD

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

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

Client["Client / CLI / Portal (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;

Security Principles (Why We Made These Choices)

• Zero Inbound Ports: Instead of running an SSH daemon or exposing management ports (like HTTP/gRPC) on your target servers, the Myrmex Agent initiates a secure, outbound connection to the Myrmex Gateway. This eliminates the primary attack vector of public scanner discovery and automated brute-force attacks.
• OS-Grade Encryption: Outbound tunnels utilize standard SSH protocol channels managed via Go's native crypto/ssh package, enforcing secure Ed25519 signature validation and high-grade ciphers (ChaCha20-Poly1305, AES-GCM).
• Defense-in-Depth Allowlist: The Agent executes binaries directly via OS process forks (os/exec) rather than invoking a shell (like /bin/sh or bash). This completely bypasses shell expansion, neutralizing shell injection vulnerabilities. Arguments are strictly validated against developer-defined regular expressions in config.json.
• Central Token Authorization: Access to the Gateway's control API is guarded via secure bearer token authentication.

---

2. Quickstart & Installation

Myrmex Hive supports Go, Nix, Linux, macOS, and Windows environments.

Nix / NixOS (Declarative Flake)

Add Myrmex Hive to your flake.nix inputs:

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

You can then run the CLI tool directly:

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

To deploy a Myrmex Agent or Gateway as a declarative systemd service on NixOS, enable the module in your 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

Installs all three binaries: myrmex (operator CLI), myrmex-gateway, and myrmex-agent.

*macOS only — Homebrew casks are not supported on Linuxbrew. On Linux use the deb/rpm packages from the releases page, the Nix flake, install.sh, or the container images.*

Linux & macOS (Direct Install)

To download, compile, and configure the Agent as a background daemon (systemd on Linux, LaunchDaemon on macOS):

sudo ./install.sh

*The installer automatically compiles the agent binary, generates secure Ed25519 keys, writes the config.json, and boots the service.*

Windows (PowerShell Script)

To install the Agent on Windows Server or Windows 10/11, launch PowerShell as Administrator and run:

Set-ExecutionPolicy Bypass -Scope Process -Force

.\install.ps1

*The PowerShell script compiles the binary, registers the agent configuration under `C:\ProgramData\mcp-agent\`, generates OpenSSH keys, and schedules a background task to launch the agent at system startup.*

Kubernetes (Helm)

Versioned container images and a Helm chart are published to GHCR on every release:

helm install hive oci://ghcr.io/olafkfreund/charts/myrmex-hive \

--version 1.2.0 \ --namespace myrmex --create-namespace

--version pins the chart and the images together (v1.0.1+; v1.0.0 predates image/chart publishing). See docs/DEPLOYMENT.md for the image list, a working install with agent keys, and the TLS/Service/agent_id caveats.

---

3. Configuration

Agent Configuration (agent_config.json)

Allows you to define a single gateway or a list of multiple gateway addresses for High Availability (HA) failover cycling:

{

"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)

Configures the receiver, TLS certs, OIDC/Tokens RBAC role mapping (admin, operator, read-only), and signed audit log path:

{

"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 }

*Note: If `audit_log_path` is set, Myrmex Gateway records all `/api/call` and `/api/chat` executions alongside a cryptographic signature generated using the Gateway's private SSH host key.*

*Note: oidc_issuer enables native OIDC/JWKS validation of real SSO tokens (opt-in; static tokens keep working alongside). See docs/SECRETS.md.*

*Note: metrics_enabled exposes a Prometheus endpoint at /metrics (opt-in; behind the same bearer-token auth as the rest of the API). Myrmex Gateway can also route threshold alerts to a webhook/Alertmanager and export OpenTelemetry traces over OTLP — all opt-in. See docs/OBSERVABILITY.md for the metric reference, a scrape_config, the Grafana dashboard, alert routing and tracing.*

Governance & scheduling (all opt-in, backward-compatible — empty/unset means off):

{

"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` classifies each tool (`read`/`write`/`admin`). Built-in mutating tools (`service_control`, `run_command`) now default to a non-`read` tier even when unlisted, so they can't slip past gating unclassified; your explicit entries still override.

• require_approval_tiers makes calls in those tiers wait for a second operator (myrmex approvals), and a new pending approval also pages your configured alert targets so it can't expire unnoticed. 15-minute TTL.
• rate_limit_per_minute caps tool calls in a sliding 60-second window.
• scheduled_tasks periodically run an LLM orchestration prompt against an agent and route the summary through the alerting subsystem — unattended fleet health checks. interval_seconds only (no cron).

See Golden Path for how these six gates fit together and a staged rollout.

Fail-closed defaults

Myrmex Gateway fails closed: it refuses to start (or rejects a connection) rather than run in an insecure state. When preparing configs and keys, three rules are enforced:

1. `authorized_keys` comment = agent-id (identity binding). The Gateway takes each connected agent's identity from the comment on its authorized_keys entry, and rejects any key whose comment is empty or does not match the agent_id the agent presents. Generate every agent key with its agent-id as the comment:

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

Then the public line in authorized_keys must keep that comment (ssh-ed25519 AAAA... agent-nginx).

1. Persistent `host_key_path` required when `audit_log_path` is set. Audit entries are signed with the Gateway's SSH host key, so a transient (regenerated-on-restart) key would make past signatures unverifiable. The Gateway refuses to start if audit_log_path is set but host_key_path is empty. Generate a stable host key once and point host_key_path at it:

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

The Gateway also refuses to start without authorized_keys_path (no agent allowlist).

1. Agents verify the Gateway host key. By default agents use trust-on-first-use (TOFU): on first connect they learn and persist the Gateway host key to .gateway_hostkey (override with known_host_key_path) and require a matching key thereafter — no config change needed. To pin explicitly instead, set gateway_host_key in agent_config.json to the Gateway host public-key line:

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

The local test fixtures (generate_keys.sh, setup_test_env.sh) already satisfy all three: agent keys are commented with their agent-ids, a persistent test_env/gateway/host_key is generated and mounted, and agents rely on TOFU.

---

4. Local LLM Setup (Ollama & Gemma 4)

Myrmex Hive orchestrates actions and interprets output using local LLMs.

Option A: Running as Docker Side-Services (Recommended)

An optional Docker setup is available via profiles in docker-compose.test.yml preloaded with the gemma4:e4b model (offline-ready):

• CPU-only mode:

  docker compose --profile ollama-cpu up -d

• GPU-accelerated mode (requires NVIDIA Container Toolkit):

  docker compose --profile ollama-gpu up -d

Option B: Manual Host Setup

1. Install Ollama on your Gateway server.
2. Pull the desired model (Gemma 4):

   ollama pull gemma4:e4b

1. Ensure Ollama is running and accessible (default http://localhost:11434). Link it in gateway_config.json.

---

5. Using the Myrmex CLI (myrmex)

The Go-based Myrmex CLI allows operators to interact with the gateway, view agents, invoke tools, and launch the assistant directly from the terminal.

Global Options

• --url: Gateway API base URL (default: https://localhost:8080)
• --token: Gateway token (or MYRMEX_TOKEN environment variable)
• -o, --output: Output format (text or json)

CLI Command Reference

• Status: View connected edge agents and configured upstream servers:

  myrmex status

• Agents: List detailed specifications of all connected agents:

  myrmex agents

• Tools: List all available tools across the swarm:

  myrmex tools

• Call: Execute a tool on a specific agent. Automatically unmasks and un-escapes payloads:

  myrmex call agent-nginx__get_metrics

• Call with JSON output: Outputs a clean, raw JSON payloa