# NousResearch/hermes-agent · Honcho local/self-hosted baseUrl and API key config fixes

## Open now

- Nothing open on GitHub.

These issues and fixes all concern Honcho failing to correctly read, honor, or route through a configured baseUrl for local or self-hosted instances, often falling back to the production cloud or requiring an API key unnecessarily. The work spans configuration resolution, setup wizards, CLI display, and per-profile client isolation.

## TL;DR

- 15 member(s): 0 open issue(s), 4 closed issue(s), 0 open PR(s), 2 merged PR(s), 9 PR(s) closed without merging.
- A fix was merged to main in PR #3644. Verify it addresses your case.
- **Recommended:** read PR #3644 (and any competing PRs below) before filing. Confirm the merged change covers your symptom.

## Maintainer resolution verdict

- Internal-tracker verdict over this cluster's issue members: `partially_resolved` · deciding PR(s): `pr-85452`. This is distinct from the fix status above. Weigh it yourself.

## How this cluster was grouped

- Link evidence (`STRUCTURAL_PARTIAL`): some members are connected by structural evidence (shared changed files, or a closing/superseded reference); the rest are joined by an automated relevance judgement over their text.
- Members outside that structural core may belong to a different underlying problem.
- Pairwise link density `0.12`: the share of member pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. `1.00` means every pair is linked.

## Closed / duplicate issues

- #2613: \[Bug\]: Local Honcho "base_url" instead of api key does not work
- #3555: \[Bug\]: Invalid Honcho API key from  local host???
- #4269: \[Bug\]: Honcho session link for locally hosted honcho incorrectly links to public honcho server
- #43800: \[Bug\]: Honcho plugin ignores endpoint.baseUrl in ~/.honcho/config.json, silently routes to production cloud

## Prior & competing PRs

- **#2645: fix(honcho): support local baseUrl-only configuration**. closed without merge · fix tier `suggested`
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `#9884`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#3644: fix(honcho): allow self-hosted local instances without API key**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `cli.py`, `gateway/run.py`, `hermes_cli/doctor.py`, `honcho_integration/cli.py`, `honcho_integration/client.py`, `run_agent.py`
  - fix hunks:
  - `cli.py`

    ```diff
    @@ -6089,7 +6089,7 @@ def run(self):
                 from honcho_integration.client import HonchoClientConfig
                 from agent.display import honcho_session_line, write_tty
                 hcfg = HonchoClientConfig.from_global_config()
    -            if hcfg.enabled and hcfg.api_key and hcfg.explicitly_configured:
    +            if hcfg.enabled and (hcfg.api_key or hcfg.base_url) and hcfg.explicitly_configured:
                     sname = hcfg.resolve_session_name(session_id=self.session_id)
                     if sname:
                         write_tty(honcho_session_line(hcfg.workspace_id, sname) + "\n")
    ```
  - `gateway/run.py`

    ```diff
    @@ -432,7 +432,7 @@ def _get_or_create_gateway_honcho(self, session_key: str):
                 from honcho_integration.session import HonchoSessionManager
     
                 hcfg = HonchoClientConfig.from_global_config()
    -            if not hcfg.enabled or not hcfg.api_key:
    +            if not hcfg.enabled or not (hcfg.api_key or hcfg.base_url):
                     return None, hcfg
     
                 client = get_honcho_client(hcfg)
    ```
  - `hermes_cli/doctor.py`

    ```diff
    @@ -56,7 +56,7 @@ def _honcho_is_configured_for_doctor() -> bool:
             from honcho_integration.client import HonchoClientConfig
     
             cfg = HonchoClientConfig.from_global_config()
    -        return bool(cfg.enabled and cfg.api_key)
    +        return bool(cfg.enabled and (cfg.api_key or cfg.base_url))
         except Exception:
             return False
     
    ```

    ```diff
    @@ -708,8 +708,8 @@ def run_doctor(args):
                 check_warn("Honcho config not found", "run: hermes honcho setup")
             elif not hcfg.enabled:
                 check_info(f"Honcho disabled (set enabled: true in {_honcho_cfg_path} to activate)")
    -        elif not hcfg.api_key:
    -            check_fail("Honcho API key not set", "run: hermes honcho setup")
    +        elif not (hcfg.api_key or hcfg.base_url):
    +            check_fail("Honcho API key or base URL not set", "run: hermes honcho setup")
                 issues.append("No Honcho API key — run 'hermes honcho setup'")
             else:
                 from honcho_integration.client import get_honcho_client, reset_honcho_client
    ```
  - `honcho_integration/cli.py`

    ```diff
    @@ -270,7 +270,7 @@ def cmd_status(args) -> None:
                 print(f"    {peer}: {mode}")
         print(f"  Write freq:     {hcfg.write_frequency}")
     
    -    if hcfg.enabled and hcfg.api_key:
    +    if hcfg.enabled and (hcfg.api_key or hcfg.base_url):
             print("\n  Connection... ", end="", flush=True)
             try:
                 get_honcho_client(hcfg)
    ```

    ```diff
    @@ -278,7 +278,7 @@ def cmd_status(args) -> None:
             except Exception as e:
                 print(f"FAILED ({e})\n")
         else:
    -        reason = "disabled" if not hcfg.enabled else "no API key"
    +        reason = "disabled" if not hcfg.enabled else "no API key or base URL"
             print(f"\n  Not connected ({reason})\n")
     
     
    ```
  - `honcho_integration/client.py`

    ```diff
    @@ -417,9 +417,18 @@ def get_honcho_client(config: HonchoClientConfig | None = None) -> Honcho:
         else:
             logger.info("Initializing Honcho client (host: %s, workspace: %s)", config.host, config.workspace_id)
     
    +    # Local Honcho instances don't require an API key, but the SDK
    +    # expects a non-empty string.  Use a placeholder for local URLs.
    +    _is_local = resolved_base_url and (
    +        "localhost" in resolved_base_url
    +        or "127.0.0.1" in resolved_base_url
    +        or "::1" in resolved_base_url
    +    )
    +    effective_api_key = [redacted:secret-assignment] or ("local" if _is_local else None)
    +
         kwargs: dict = {
             "workspace_id": config.workspace_id,
    -        "api_key": config.api_key,
    +        "api_key": effective_api_key,
             "environment": config.environment,
         }
         if resolved_base_url:
    ```
  - `run_agent.py`

    ```diff
    @@ -1084,8 +1084,8 @@ def __init__(
                         else:
                             if not hcfg.enabled:
                                 logger.debug("Honcho disabled in global config")
    -                        elif not hcfg.api_key:
    -                            logger.debug("Honcho enabled but no API key configured")
    +                        elif not (hcfg.api_key or hcfg.base_url):
    +                            logger.debug("Honcho enabled but no API key or base URL configured")
                             else:
                                 logger.debug("Honcho enabled but missing API key or disabled in config")
                 except Exception as e:
    ```

    ```diff
    @@ -2292,8 +2292,14 @@ def is_interrupted(self) -> bool:
         # ── Honcho integration helpers ──
     
         def _honcho_should_activate(self, hcfg) -> bool:
    -        """Return True when remote Honcho should be active."""
    -        if not hcfg or not hcfg.enabled or not hcfg.api_key:
    +        """Return True when Honcho should be active.
    +
    +        Self-hosted Honcho may be configured with a base_url and no API key,
    +        so activation should accept either credential style.
    +        """
    +        if not hcfg or not hcfg.enabled:
    +            return False
    +        if not (hcfg.api_key or hcfg.base_url):
                 return False
             return True
     
    ```
- **#85452: fix(honcho): isolate clients per profile, resolve baseUrl/apiKey, enforce saveMessages containment**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `agent/memory_manager.py`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `plugins/memory/honcho/README.md`, `plugins/memory/honcho/__init__.py`, `plugins/memory/honcho/cli.py`, `plugins/memory/honcho/client.py`, `plugins/memory/honcho/session.py`, `tests/honcho_plugin/test_async_memory.py`, `tests/honcho_plugin/test_client.py`, `tests/honcho_plugin/test_client_identity_isolation.py`, `tests/honcho_plugin/test_save_messages.py`, `tests/plugins/memory/test_honcho_cli_peers.py`, `tests/run_agent/test_primary_runtime_restore.py`, `tests/test_honcho_client_config.py` (+2 more)
- **#2619: fix(honcho): support base_url for local instances in setup and identity commands**. closed without merge
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#13439`
- **#3560: fix(honcho): bypass API key validation for local servers**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `#3644`, `#3482`, `#3570`
- **#3570: fix(honcho): use placeholder API key for local instances that don't require auth**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `#3644`, `#3482`, `#3560`
- **#5002: fix: Honcho base_url host-block resolution + OpenViking is_available + doctor check**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `#5078`
- **#13439: fix(honcho): support base_url-only config in cmd_identity for local instances**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `36d6b643f6dd6ece5b6a1eada243ae4cb7d26551`
- **#14489: fix(honcho): honor host-specific baseUrl**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `2f80ae0a6a`, `#131301`
- **#43803: fix(memory): read endpoint.baseUrl from Honcho config; accept HONCHO_URL**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `ad588542e`
- **#83508: fix(honcho): resolve baseUrl/apiKey correctly for self-hosted and multi-profile setups**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `#85452`

## Fix status

- Merged to main in PR #3644 (cited above). No release data is tracked. Verify downstream.
- Fix last verified (merged) `2026-08-13`.
- Subsystem: `agent`