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<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;

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:

   bash

   Copy

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

2. 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:

   bash

   Copy

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

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