# NousResearch/hermes-agent · Browser detection and executable path resolution fixes

## Open now

- 2 issues, 1 PR open on GitHub.
- #48172: browser: macOS app-bundle Chrome is ignored by local tool availability check
- #66111: \[Bug\]: browser.executable_path config not passed to agent-browser subprocess — ARM64 browser timeout
- PR #66131: fix(browser): propagate browser.executable_path config to agent-browser subprocess (#66111)

Multiple bugs and fixes around how Chromium/Chrome is detected across macOS app-bundles, Docker images, and custom executable paths. Covers the availability check logic, AGENT_BROWSER_EXECUTABLE_PATH propagation, and bundled vs. system browser discovery.

## TL;DR

- 15 member(s): 2 open issue(s), 2 closed issue(s), 1 open PR(s), 2 merged PR(s), 8 PR(s) closed without merging.
- A fix was merged to main in PR #19595. Verify it addresses your case.
- **Recommended:** read PR #19595 (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-33184`. 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.

## Open related issues

- #48172: browser: macOS app-bundle Chrome is ignored by local tool availability check
- #66111: \[Bug\]: browser.executable_path config not passed to agent-browser subprocess — ARM64 browser timeout

## Closed / duplicate issues

- #15697: \[Bug\]: Auto-launch failed: Chrome not found error when running hermes-cli with official Docker image
- #19294: \[Bug\]: _chromium_installed() ignores AGENT_BROWSER_EXECUTABLE_PATH and system Chrome — browser tools unnecessarily gated

## Prior & competing PRs

- **#19457: fix(browser): detect configured system chrome**. closed without merge · fix tier `suggested`
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `45fd45103d6cb3d8a1910aad6ec9de7e3d55e4fb`, `#30161`, `#33408`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#19595: fix: _chromium_installed() honors AGENT_BROWSER_EXECUTABLE_PATH and system Chrome**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `tools/browser_tool.py`
  - fix hunks:
  - `tools/browser_tool.py`

    ```diff
    @@ -2757,17 +2757,40 @@ def _chromium_search_roots() -> List[str]:
     def _chromium_installed() -> bool:
         """Return True when a usable Chromium (or headless-shell) build is on disk.
     
    +    Checks, in order:
    +
    +    1. ``AGENT_BROWSER_EXECUTABLE_PATH`` env var — the official way to point
    +       agent-browser at a pre-installed Chrome/Chromium.
    +    2. System Chrome/Chromium in PATH (``google-chrome``, ``chromium-browser``,
    +       ``chrome``).
    +    3. Playwright's browser cache (current logic) — directories containing
    +       ``chromium-*`` or ``chromium_headless_shell-*``.
    +
         agent-browser (0.26+) downloads Playwright's chromium / headless-shell
    -    builds into ``PLAYWRIGHT_BROWSERS_PATH`` and won't start without them.
    -    When the CLI is present but no browser build is, the first browser tool
    -    call hangs for the full command timeout (often ~30s each) before
    -    surfacing a useless error. Guarding the tool behind this check prevents
    -    advertising a capability that will fail at runtime.
    +    builds into ``PLAYWRIGHT_BROWSERS_PATH`` and won't start without at least
    +    one of the three above being present.  Without a browser binary the CLI
    +    hangs on first use until the command timeout fires (often ~30s).  Guarding
    +    the tool behind this check prevents advertising a capability that will
    +    fail at runtime.
         """
         global _cached_chromium_installed
         if _cached_chromium_installed is not None:
             return _cached_chromium_installed
     
    +    # 1. AGENT_BROWSER_EXECUTABLE_PATH — explicit user-configured browser
    +    ab_path = os.environ.get("AGENT_BROWSER_EXECUTABLE_PATH", "").strip()
    +    if ab_path:
    +        if os.path.isfile(ab_path) or shutil.which(ab_path):
    +            _cached_chromium_installed = True
    +            return True
    +
    +    # 2. System Chrome/Chromium in PATH (common names)
    +    system_chrome = shutil.which("google-chrome") or shutil.which("chromium-browser") or shutil.which("chrome")
    +    if system_chrome:
    +        _cached_chromium_installed = True
    +        return True
    +
    +    # 3. Playwright browser cache (legacy — chromium-* / chromium_headless_shell-* dirs)
         for root in _chromium_search_roots():
             if not root or not os.path.isdir(root):
                 continue
    ```
- **#33184: fix(docker): discover agent-browser Chromium binary at boot**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `docker/stage2-hook.sh`
- **#48185: fix(tools): detect macOS app-bundle Chrome in browser availability gate**. closed without merge · fix tier `suggested`
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `97888fed483c1e867666b6beb4eb03e409cc9481`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#48252: fix(browser): detect macOS app-bundle Chrome in availability check (#48172)**. closed without merge · fix tier `suggested`
  - maintainer direction: category `uncategorized`; implication `needs_llm`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#15908: fix(docker): set AGENT_BROWSER_EXECUTABLE_PATH to Playwright's Chromium**. closed without merge
  - maintainer direction: category `stale_abandoned`; implication `active`
- **#18635: fix(install): implement dynamic browser bin discovery for agent-browser**. closed without merge
  - maintainer direction: category `silent_close`; implication `active`
- **#19298: fix: _chromium_installed() ignores AGENT_BROWSER_EXECUTABLE_PATH and system Chrome**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `#19595`
- **#48225: fix: harden macOS desktop and browser resolution**. closed without merge
  - maintainer direction: category `superseded_by_pr`; implication `superseded`
- **#48232: fix: detect macOS app-bundle browsers for tool checks**. closed without merge
  - maintainer direction: category `superseded_by_pr`; implication `superseded`
- **#66131: fix(browser): propagate browser.executable_path config to agent-browser subprocess (#66111)**. open
  - maintainer direction: category `partial_fix`; implication `needs_llm`; refs `de96a829fa5d`, `#66111`, `#66131`, `#66131`, `#66131`, `#66131`, `#374151`, `#66111`, `#66131`
  - files: `hermes_cli/config.py`, `tests/tools/test_browser_executable_path.py`, `tools/browser_tool.py`, `website/docs/user-guide/configuration.md`, `website/docs/user-guide/features/browser.md`

## Fix status

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