NousResearch/hermes-agent · error · RuntimeError

Unsupported platform for iron-proxy auto-install: {system} {

Error message

Unsupported platform for iron-proxy auto-install: {system} {machine}

What it means

The auto-installer for the iron-proxy egress proxy builds a release asset name from platform.system()/platform.machine() and only knows Linux, Darwin, and Windows. Any other OS falls through to this RuntimeError instead of guessing an asset. Windows is deliberately excluded upstream (no native binaries), so this message is the catch-all for everything else (FreeBSD, Solaris, Cygwin-python reporting 'CYGWIN_NT...', etc.).

Source

Thrown at agent/proxy_sources/iron_proxy.py:426

    """

    system = platform.system()
    machine = platform.machine().lower()

    if system == "Linux":
        arch = "arm64" if machine in ("arm64", "aarch64") else "amd64"
        return f"iron-proxy_{_IRON_PROXY_VERSION}_linux_{arch}.tar.gz"
    if system == "Darwin":
        arch = "arm64" if machine in ("arm64", "aarch64") else "amd64"
        return f"iron-proxy_{_IRON_PROXY_VERSION}_darwin_{arch}.tar.gz"
    if system == "Windows":
        raise RuntimeError(
            "iron-proxy does not ship native Windows binaries as of "
            f"v{_IRON_PROXY_VERSION}. Run the proxy on a Linux/macOS host, "
            "or inside WSL."
        )

    raise RuntimeError(
        f"Unsupported platform for iron-proxy auto-install: {system} {machine}"
    )


# ---------------------------------------------------------------------------
# Binary discovery + lazy install
# ---------------------------------------------------------------------------


def find_iron_proxy(*, install_if_missing: bool = False) -> Optional[Path]:
    """Return a path to a usable ``iron-proxy`` binary, or None.

    Resolution order:
      1. ``<hermes_home>/bin/iron-proxy``  (our managed copy — preferred)
      2. ``shutil.which("iron-proxy")``    (system PATH)

    When ``install_if_missing`` is True and neither resolves, calls
    :func:`install_iron_proxy` to download and verify the pinned version.

View on GitHub (pinned to c896c09c42)

Solutions

Run the proxy on a supported Linux or macOS host (or inside WSL on Windows) and point Hermes at it.
Manually download the iron-proxy release for linux/darwin matching your architecture and place the binary where find_iron_proxy() looks, so auto-install is never attempted.
If this is a real platform you control, extend the asset-name branch in _platform_asset_name to cover it and verify a matching release asset exists.

Defensive patterns

Strategy: validation

Validate before calling

import platform
from agent.proxy_sources.iron_proxy import find_iron_proxy

def can_auto_install() -> bool:
    return platform.system() in ("Linux", "Darwin") or find_iron_proxy() is not None

Try / catch

try:
    find_iron_proxy(install_if_missing=True)
except RuntimeError as e:
    if "Unsupported platform" in str(e):
        # fall back to a pre-installed binary or skip egress proxying
        pass
    raise

Prevention

Pre-install the iron-proxy binary on supported hosts and ship it with the image so auto-install never runs on exotic platforms.
Assert platform.system() is Linux/Darwin in deployment checks before enabling the egress feature.

When it happens

Trigger: Calling find_iron_proxy(install_if_missing=True) (directly or via start_proxy(install_if_missing=True) / `hermes egress install`) on a host where platform.system() returns something other than 'Linux', 'Darwin', or 'Windows' — e.g. FreeBSD, OpenBSD, a SunOS zone, or a Python build that reports a nonstandard system string.

Common situations: Running Hermes in a BSD jail or Alpine-adjacent container with a custom platform string; trying to auto-install from a NAS or a minimal VM; scripting against the egress module on an exotic CI runner.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/7c9f2452112885e8. Report an issue: GitHub.