{"record":{"id":"58f116912549ebf9","repo":"NousResearch/hermes-agent","slug":"iron-proxy-binary-not-available-run-hermes-egre","errorCode":null,"errorMessage":"iron-proxy binary not available — run `hermes egress install`.","messagePattern":"iron-proxy binary not available — run `hermes egress install`\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"agent/proxy_sources/iron_proxy.py","lineNumber":1789,"sourceCode":"    just returns the live status.\n\n    ``refresh_secrets_from_bitwarden=True`` re-fetches upstream secrets\n    via ``bws secret list`` at startup and injects them into the child\n    env.  This delivers the rotation promise that distinguishes\n    ``credential_source: bitwarden`` from ``credential_source: env``.\n    Without this flag (or with ``bitwarden_config=None``) the proxy still\n    starts but uses whatever the host process env happens to contain.\n    \"\"\"\n\n    global _proxy_nonce\n\n    existing = _read_pid()\n    if existing and _pid_alive(existing):\n        return get_status()\n\n    bin_path = binary or find_iron_proxy(install_if_missing=install_if_missing)\n    if bin_path is None:\n        raise RuntimeError(\n            \"iron-proxy binary not available — run `hermes egress install`.\"\n        )\n\n    cfg = config_path or (_proxy_state_dir() / \"proxy.yaml\")\n    if not cfg.exists():\n        raise RuntimeError(\n            f\"iron-proxy config not found at {cfg}. \"\n            \"Run `hermes egress setup` first.\"\n        )\n\n    # Build a minimal subprocess env.  os.environ.copy() would ship every\n    # secret in the operator's shell to the proxy — /proc/<pid>/environ\n    # would then expose OPENAI_API_KEY, AWS keys, etc. to any same-uid\n    # local process.  Defeats the threat model the proxy exists to\n    # mitigate.\n    env = _build_proxy_subprocess_env(\n        extra_env=extra_env,\n        refresh_from_bitwarden=refresh_secrets_from_bitwarden,","sourceCodeStart":1771,"sourceCodeEnd":1807,"githubUrl":"https://github.com/NousResearch/hermes-agent/blob/c896c09c42910c584c4c7d2325b58c14713ea42c/agent/proxy_sources/iron_proxy.py#L1771-L1807","documentation":"start_proxy() resolves the binary via find_iron_proxy(install_if_missing=...); if that returns None — no binary on disk and auto-install not requested (or not possible) — it refuses to start with the command that performs the install. This is a missing-prerequisite error raised before any config/process work happens.","triggerScenarios":"start_proxy() (or `hermes egress start`) with install_if_missing=False on a machine where the iron-proxy binary was never installed, was deleted from the proxy state dir, or auto-install failed silently earlier. Note: if a live pid exists, start_proxy returns early, so this only fires when the daemon isn't running.","commonSituations":"Fresh machine where setup ran on a different host; the state dir was cleaned; the binary was quarantined by antivirus/removed by a cleanup job.","solutions":["Run `hermes egress install` (equivalently start with auto-install enabled) to fetch and verify the pinned release binary.","Verify afterwards that find_iron_proxy() now returns a path before calling start_proxy().","If install keeps failing, work through its download/checksum errors first — this error is just the downstream symptom."],"exampleFix":"// before\nstart_proxy()  # RuntimeError: iron-proxy binary not available\n\n// after\nfrom agent.proxy_sources.iron_proxy import find_iron_proxy, start_proxy\nbin_path = find_iron_proxy(install_if_missing=True)\nif bin_path is None:\n    raise SystemExit(\"iron-proxy install failed; see logs\")\nstart_proxy(binary=bin_path)","handlingStrategy":"validation","validationCode":"from agent.proxy_sources.iron_proxy import find_iron_proxy\n\ndef binary_ready() -> bool:\n    return find_iron_proxy() is not None","typeGuard":null,"tryCatchPattern":"try:\n    start_proxy()\nexcept RuntimeError as e:\n    if \"binary not available\" in str(e):\n        find_iron_proxy(install_if_missing=True)\n        start_proxy()","preventionTips":["Run `hermes egress install` during machine provisioning, not at first start.","Gate start scripts on find_iron_proxy() returning a path."],"tags":["install","lifecycle","iron-proxy"],"backgroundTag":null,"analyzedSha":"c896c09c42910c584c4c7d2325b58c14713ea42c","analyzedAt":"2026-08-14T17:18:01.089Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}