# NousResearch/hermes-agent · docker_extra_args config not bridged to terminal env

## Open now

- 1 issue, 2 PRs open on GitHub.
- #28892: FR: single-source terminal config→env bridge (eliminate 3-dict drift)
- PR #28995: feat: Config-Runtime Contract Registry (Phase 1) + fix #28046 + fix #28863
- PR #129844: fix(config): one terminal env map for every bridge

A bug where terminal.docker_extra_args set in config.yaml is silently dropped because it is missing from the config-to-environment-variable bridge maps, particularly in gateway mode. Members include bug reports, multiple fix attempts, and a feature request to unify the bridging logic.

## TL;DR

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

- #28892: FR: single-source terminal config→env bridge (eliminate 3-dict drift)

## Closed / duplicate issues

- #28863: terminal.docker_extra_args from config.yaml silently dropped — missing in _terminal_env_map bridge
- #30415: \[Bug\]: terminal.docker_extra_args silently ignored in gateway mode (missing env-var bridge)
- #35751: terminal.docker_extra_args in config.yaml not being applied to Docker sandbox
- #39615: \[Bug\]: The docker-extra_args configuration is invalid in config. yml and cannot be read.
- #45129: Title:\`docker_extra_args\` ignored by gateway — missing from \`_terminal_env_map\` in \`gateway/run.py\`

## Prior & competing PRs

- **#28888: fix(terminal): add docker_extra_args to all three config-to-env bridge maps (#28863)**. closed without merge · fix tier `suggested`
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `#28891`, `#28891`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#28891: fix(gateway): bridge terminal.docker_extra_args and docker_forward_env to env**. closed without merge · fix tier `suggested`
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `#35937`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#29236: fix(terminal): pass docker_extra_args through _terminal_env_map (#28863)**. closed without merge · fix tier `suggested`
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `#28891`, `#28888`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#30629: fix(gateway): bridge terminal.docker_extra_args to env for gateway sessions (#30415)**. closed without merge · fix tier `suggested`
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `#28891`, `#28888`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#30887: fix(gateway): bridge terminal.docker_extra_args to env for gateway sessions (#30415)**. closed without merge · fix tier `suggested`
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `#30629`, `#28891`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#39683: fix(terminal): bridge docker_extra_args from config.yaml (#39615)**. closed without merge · fix tier `suggested`
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `#35937`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#50631: fix(terminal): bridge docker_extra_args to TERMINAL_DOCKER_EXTRA_ARGS in CLI + gateway**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `cli.py`, `gateway/run.py`, `tests/tools/test_terminal_config_env_sync.py`
  - fix hunks:
  - `cli.py`

    ```diff
    @@ -621,6 +621,7 @@ def load_cli_config() -> Dict[str, Any]:
             "container_persistent": "TERMINAL_CONTAINER_PERSISTENT",
             "docker_volumes": "TERMINAL_DOCKER_VOLUMES",
             "docker_env": "TERMINAL_DOCKER_ENV",
    +        "docker_extra_args": "TERMINAL_DOCKER_EXTRA_ARGS",
             "docker_mount_cwd_to_workspace": "TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE",
             "docker_run_as_host_user": "TERMINAL_DOCKER_RUN_AS_HOST_USER",
             "docker_persist_across_processes": "TERMINAL_DOCKER_PERSIST_ACROSS_PROCESSES",
    ```
  - `gateway/run.py`

    ```diff
    @@ -1464,6 +1464,7 @@ def _profile_runtime_scope(profile_home: "Path"):
                     "container_persistent": "TERMINAL_CONTAINER_PERSISTENT",
                     "docker_volumes": "TERMINAL_DOCKER_VOLUMES",
                     "docker_env": "TERMINAL_DOCKER_ENV",
    +                "docker_extra_args": "TERMINAL_DOCKER_EXTRA_ARGS",
                     "docker_mount_cwd_to_workspace": "TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE",
                     "docker_run_as_host_user": "TERMINAL_DOCKER_RUN_AS_HOST_USER",
                     "docker_persist_across_processes": "TERMINAL_DOCKER_PERSIST_ACROSS_PROCESSES",
    ```
  - `tests/tools/test_terminal_config_env_sync.py`

    ```diff
    @@ -233,6 +233,27 @@ def test_docker_env_is_bridged_everywhere():
         assert "TERMINAL_DOCKER_ENV" in _terminal_tool_env_var_names()
     
     
    +def test_docker_extra_args_is_bridged_everywhere():
    +    """Regression pin for docker_extra_args config key being silently ignored.
    +
    +    ``terminal.docker_extra_args`` in config.yaml passes extra flags verbatim
    +    to ``docker run`` (e.g. ``--gpus=all``, ``--shm-size=16g``).  The key was
    +    present in DEFAULT_CONFIG, TERMINAL_CONFIG_ENV_MAP (so ``hermes config
    +    set`` bridged it), terminal_tool._get_env_config (reads
    +    TERMINAL_DOCKER_EXTRA_ARGS), and DockerEnvironment (applies extra_args) --
    +    but it was MISSING from cli.py's env_mappings and gateway/run.py's
    +    _terminal_env_map.  So a user who hand-edited config.yaml had their GPU /
    +    shm-size flags silently dropped on the CLI and gateway/desktop paths,
    +    while ``image``/``volumes`` (which were in those maps) bridged fine --
    +    producing the "Hermes partially reads the Docker config" symptom.  Guard
    +    all four bridging points so this cannot regress.
    +    """
    +    assert "docker_extra_args" in _cli_env_map_keys()
    +    assert "docker_extra_args" in _gateway_env_map_keys()
    +    assert "docker_extra_args" in _save_config_env_sync_keys()
    +    assert "TERMINAL_DOCKER_EXTRA_ARGS" in _terminal_tool_env_var_names()
    +
    +
     def test_docker_persist_across_processes_is_bridged_everywhere():
         """Regression pin for the cross-process container reuse toggle.
     
    ```
- **#28995: feat: Config-Runtime Contract Registry (Phase 1) + fix #28046 + fix #28863**. open
  - maintainer direction: category `superseded_by_pr`; implication `superseded`
  - files: `.dev-workflow/code-graph.db`, `agent/agent_init.py`, `gateway/run.py`, `hermes_cli/config.py`, `hermes_cli/config_contracts.py`, `tests/hermes_cli/test_config_contracts.py`, `tests/hermes_cli/test_custom_provider_max_tokens.py`
- **#45288: fix(gateway): bridge docker_extra_args config to TERMINAL_DOCKER_EXTRA_ARGS env var**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `de6b3ae3774fb0bb48f288159e7bb326d8f48bc2`, `#50631`
- **#63945: fix(config): bridge terminal.docker_extra_args into runtime env**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `#50631`
- **#129844: fix(config): one terminal env map for every bridge**. open
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `f930a00ff1`
  - files: `gateway/run.py`, `hermes_cli/cli_config_load.py`, `hermes_cli/config.py`, `hermes_cli/main.py`, `tests/tools/test_terminal_config_env_sync.py`

## Fix status

- Merged to main in PR #50631 (cited above). No release data is tracked. Verify downstream.
- Fix last verified (merged) `2026-06-22`.
- Subsystem: `environments`