Bug Description

Summary

The Chrome launch-flag injection in tools/browser_tool.py::_run_browser_command writes the subprocess env var AGENT_BROWSER_CHROME_FLAGS, but agent-browser does not read that variable. The documented env var for browser launch args is AGENT_BROWSER_ARGS. As a result the --no-sandbox workaround for root execution and Ubuntu/AppArmor unprivileged-userns restrictions (issue #15765, PR #15771, commit 74c1b946e) is a silent no-op

Result: Chromium still fails to launch with "No usable sandbox" on affected systems.

Steps to Reproduce

1. Ubuntu 23.10+ host with /proc/sys/kernel/apparmor_restrict_unprivileged_userns = 1 (default on 24.04 LTS).
2. Non-root user runs hermes browser_navigate https://example.com (or any other browser_* tool).
3. The auto-detect block in _run_browser_command correctly identifies that sandbox bypass is needed and sets AGENT_BROWSER_CHROME_FLAGS=--no-sandbox --disable-dev-shm-usage in browser_env before the subprocess Popen.
4. agent-browser does not consult AGENT_BROWSER_CHROME_FLAGS. Chromium launches with the default sandbox enabled and exits with "No usable sandbox". The user-facing error is the agent-browser failure; the upstream auto-detect succeeds in its own log line, masking the cause.

Expected Behavior

When running on Ubuntu 23.10+ (or any system with AppArmor unprivileged-userns restrictions), the browser tool should successfully launch Chrome in sandbox-bypass mode (--no-sandbox --disable-dev-shm-usage) and render pages without error. A user asking Hermes to take a screenshot of a website should get a successful response with the captured image.

Actual Behavior

The browser tool fails to launch Chrome entirely. The user-facing error is:

Chrome exited early (exit code: unknown) without writing DevToolsActivePort No usable sandbox!

The upstream auto-detect block in _run_browser_command correctly identifies that sandbox bypass is needed, but the env var it writes (AGENT_BROWSER_CHROME_FLAGS) is never read by agent-browser, which expects AGENT_BROWSER_ARGS. The bypass injection is therefore a silent no-op — Chrome launches with its default sandbox and crashes on AppArmor-restricted systems.

Affected Component

Tools (terminal, file ops, web, code execution, etc.)

Messaging Platform (if gateway-related)

No response

Debug Report

Report       https://paste.rs/eHL5S
agent.log    https://dpaste.com/HXJU6TZBX
gateway.log  https://dpaste.com/EUDBVMBFH

Operating System

Ubuntu 24.04

Python Version

3.11.15

Hermes Version

v0.13.0 (2026.5.7)

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

No response

Proposed Fix (optional)

Replace the env-var-writing block inside _run_browser_command with a layout that (a) writes to the correct env var, (b) computes the flag once before the subprocess plumbing rather than mid-try:, and (c) gives users a config-driven override via [browser] launch_args. Skip entirely for CDP/cloud sessions where Chromium runs remotely.

Between the cmd_prefix block and the cmd_parts = ... assignment, add:

# Inject browser launch args via AGENT_BROWSER_ARGS env var (issue #15765).
# Reads from config["browser"]["launch_args"] first; falls back to
# "--no-sandbox --disable-dev-shm-usage" when running as root or on Ubuntu
# 23.10+/AppArmor systems where unprivileged user namespaces are restricted.
# Skipped for CDP/cloud sessions where Chrome runs remotely.
_chrome_launch_args: str = ""
if not session_info.get("cdp_url"):
    try:
        from hermes_cli.config import read_raw_config as _read_cfg
        cfg = _read_cfg()
        user_args = cfg_get(cfg, "browser", "launch_args") or ""
        if user_args.strip():
            _chrome_launch_args = user_args.strip()
        else:
            _needs_sandbox_bypass = False
            if hasattr(os, "geteuid") and os.geteuid() == 0:
                _needs_sandbox_bypass = True
                logger.debug("browser: running as root — defaulting --no-sandbox")
            else:
                _userns_restrict = "/proc/sys/kernel/apparmor_restrict_unprivileged_userns"
                try:
                    with open(_userns_restrict, encoding="utf-8") as _f:
                        if _f.read().strip() == "1":
                            _needs_sandbox_bypass = True
                            logger.debug(
                                "browser: AppArmor userns restrictions detected — "
                                "defaulting --no-sandbox"
                            )
                except OSError:
                    pass
            if _needs_sandbox_bypass:
                _chrome_launch_args = "--no-sandbox --disable-dev-shm-usage"
    except Exception as e:
        logger.debug("Could not read browser launch args from config: %s", e)

Then, inside the existing try: block where browser_env = {**os.environ} is built, replace the current if "AGENT_BROWSER_CHROME_FLAGS" not in browser_env: ... block with:

# Set AGENT_BROWSER_ARGS so agent-browser passes flags to Chrome on launch.
if _chrome_launch_args and "AGENT_BROWSER_ARGS" not in os.environ:
    browser_env["AGENT_BROWSER_ARGS"] = _chrome_launch_args

Notes for reviewers:

• The detection logic (root via os.geteuid(), AppArmor via /proc/sys/kernel/apparmor_restrict_unprivileged_userns) is unchanged from the current block — only its position in the function moves.
• The guard "AGENT_BROWSER_ARGS" not in os.environ lets operators override via shell or systemd Environment= without code edits.
• Adding [browser] launch_args to the config gives users a documented escape hatch for setting arbitrary Chrome flags (e.g. --disable-gpu, custom flags for testing) without needing to touch source.
• A simpler in-place rename of AGENT_BROWSER_CHROME_FLAGS to AGENT_BROWSER_ARGS within the current block was not sufficient to restore launches in our testing; we'd encourage maintainers to reproduce on an Ubuntu 24.04 AppArmor host before considering a minimal rename as the fix.

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR