From bc6bb6e8f17231c019f483a7685bf4842a88cf97 Mon Sep 17 00:00:00 2001
From: Sandy Chapman <schapman@nvidia.com>
Date: Mon, 17 Aug 2026 10:34:38 -0300
Subject: [PATCH] refactor(evaluator)!: rename env_overrides to hydra_params,
 add env_vars
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`env_overrides` read as "environment variables" to everyone who met it. It is
not: the "env" is Gym's *environment* (the resources-server), and the values
become Hydra config overrides — `{'a': {'b': 1}}` flattens to `++a.b=1`. The
name is now `hydra_params`, which says what it does.

That frees `env` to mean what people assumed, and the gap it leaves is real.
Some Gym environments are configurable only through the OS environment:
`wmt_translation` reads `WMT_TRANSLATION_COMET_PY_CACHE` for its model-cache
root and otherwise defaults to `/opt/Gym/.cache/comet-python`, a path that
exists only inside NVIDIA's container image, so on any other machine it fails
with `PermissionError: /opt/Gym` before the GPU requirement is even reached.

Until now the only way to set that was to export it before invoking the
runner, which makes a property of the *environment* into a property of
whoever happened to launch the run — and a job spec executed elsewhere has no
ambient environment to inherit from at all. The new `env_vars` field carries
it in the config instead.

Precedence is this process's environment, then the Ray uv-hook default, then
`env_vars`. Explicit config wins over both, including over the Ray setting:
that default exists to make Gym work rather than as an invariant, and someone
debugging that hook needs a way to put it back. `_gym_invocation_env` exists
so this is assertable without starting Ray.

`env_vars` is redacted in `RunnerInfo.config` on the same rules as
`hydra_params`, and needs it more: an environment variable is the conventional
way to hand a process an API key, so a caller doing the obvious thing would
otherwise write one into the run bundle. Verified the existing markers catch
`OPENAI_API_KEY`, `HF_TOKEN`, `AWS_SECRET_ACCESS_KEY` and `DB_PASSWORD` while
leaving `WMT_TRANSLATION_COMET_PY_CACHE` and `HTTPS_PROXY` verbatim.

BREAKING CHANGE: `env_overrides` is renamed to `hydra_params` on both
`GymRuntimeConfig` and the Gym runner-target job spec, so it changes the REST
contract in plugins/nemo-evaluator/openapi/openapi.yaml. The field landed in
main one day ago (#1257) and has no known callers.

Signed-off-by: Sandy Chapman <schapman@nvidia.com>

Rebased onto main after #1295 split `gym_runtime.py` into the `gym/` package.
Re-applied on the new layout rather than resolving a delete/modify conflict
against a file that no longer exists. One placement changed as a result:
`_gym_invocation_env` now lives in `gym/process.py` rather than beside the
runner. The environment a CLI is invoked with is part of how it is run, which
is what that module is for, and it keeps the runtime module orchestration-only.
It is `process.py`'s first dependency on `config.py`, which stays acyclic.

Signed-off-by: Sandy Chapman <schapman@nvidia.com>
---
 .../nemo_evaluator_sdk/examples/gym/README.md |  2 +-
 .../agent_eval/runtimes/gym/config.py         | 30 ++++++++-----
 .../agent_eval/runtimes/gym/process.py        | 23 ++++++++++
 .../agent_eval/runtimes/gym/runtime.py        | 15 ++++---
 .../test_gym_environment_coverage.py          | 16 +++----
 .../tests/agent_eval/test_gym_runtime.py      | 31 ++++++++++++-
 .../tests/agent_eval/test_run_metadata.py     | 44 ++++++++++++++++---
 plugins/nemo-evaluator/openapi/openapi.yaml   | 21 +++++++--
 .../src/nemo_evaluator/jobs/agent_evaluate.py |  3 +-
 .../src/nemo_evaluator/jobs/agent_spec.py     | 14 ++++--
 .../tests/integration/conftest.py             | 14 +++---
 .../tests/test_agent_evaluate.py              |  4 +-
 .../agent_eval/runtimes/gym/config.py         | 30 ++++++++-----
 .../agent_eval/runtimes/gym/process.py        | 23 ++++++++++
 .../agent_eval/runtimes/gym/runtime.py        | 15 ++++---
 15 files changed, 221 insertions(+), 64 deletions(-)

diff --git a/packages/nemo_evaluator_sdk/examples/gym/README.md b/packages/nemo_evaluator_sdk/examples/gym/README.md
index 0189e03eb3..b2b4c0c74d 100644
--- a/packages/nemo_evaluator_sdk/examples/gym/README.md
+++ b/packages/nemo_evaluator_sdk/examples/gym/README.md
@@ -42,7 +42,7 @@ Working from a Gym checkout also makes its components take precedence over the p
 
 Useful flags: `--resources-server`, `--agent`, `--model-type` (`inference_provider` for OpenAI-compatible **chat** endpoints; `openai_model` uses the OpenAI **Responses API** and 500s against chat-only endpoints), `--num-repeats`, `--dataset`, `--output-dir`.
 
-For the full set of knobs the underlying `gym env start` / `gym eval run` commands accept, see the [NeMo Gym documentation](https://github.com/NVIDIA-NeMo/Gym). Anything `GymRuntimeConfig` does not expose as a field can be passed through with its `env_overrides` escape hatch — nested data such as `{"model": {"temperature": 0.7}}`, flattened to Hydra's override grammar and applied to `gym env start`.
+For the full set of knobs the underlying `gym env start` / `gym eval run` commands accept, see the [NeMo Gym documentation](https://github.com/NVIDIA-NeMo/Gym). Anything `GymRuntimeConfig` does not expose as a field can be passed through with its `hydra_params` escape hatch — nested data such as `{"model": {"temperature": 0.7}}`, flattened to Hydra's override grammar and applied to `gym env start`.
 
 Each run writes its bundle to a fresh temporary directory by default. Pass `--output-dir` to choose one, but give every run its own: the runner refuses to reuse a directory that already holds Gym rollout output (Gym appends to its failures sidecar, so reusing one would mix runs) and raises rather than clearing a prior run's results.
 
diff --git a/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/config.py b/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/config.py
index 21a3dabecd..200cd41884 100644
--- a/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/config.py
+++ b/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/config.py
@@ -128,10 +128,10 @@ def _flatten_overrides(overrides: Mapping[str, Any], _prefix: str = "") -> list[
     return arguments
 
 
-def _redact_env_overrides(overrides: Mapping[str, Any], _prefix: str = "") -> dict[str, Any]:
+def _redact_hydra_params(overrides: Mapping[str, Any], _prefix: str = "") -> dict[str, Any]:
     """Redact credential-looking values from overrides before they are recorded as provenance.
 
-    ``env_overrides`` is a free-form escape hatch forwarded to Gym, so nothing stops a caller passing
+    ``hydra_params`` is a free-form escape hatch forwarded to Gym, so nothing stops a caller passing
     ``{"model": {"api_key": "sk-..."}}``. ``RunnerInfo.config`` is persisted into the run bundle, so a
     value that looks like a credential must not be written there.
 
@@ -147,7 +147,7 @@ def _redact_env_overrides(overrides: Mapping[str, Any], _prefix: str = "") -> di
     for key, value in overrides.items():
         path = f"{_prefix}{key}"
         if isinstance(value, Mapping):
-            redacted[key] = _redact_env_overrides(value, f"{path}.")
+            redacted[key] = _redact_hydra_params(value, f"{path}.")
         elif any(marker in path.casefold() for marker in _SECRET_KEY_MARKERS):
             redacted[key] = _REDACTED
         elif isinstance(value, (list, tuple)):
@@ -158,9 +158,9 @@ def _redact_env_overrides(overrides: Mapping[str, Any], _prefix: str = "") -> di
 
 
 def _redact_list_item(item: Any, path: str) -> Any:
-    """Redact inside one element of a list-valued override. See :func:`_redact_env_overrides`."""
+    """Redact inside one element of a list-valued override. See :func:`_redact_hydra_params`."""
     if isinstance(item, Mapping):
-        return _redact_env_overrides(item, f"{path}.")
+        return _redact_hydra_params(item, f"{path}.")
     if isinstance(item, (list, tuple)):
         return [_redact_list_item(nested, path) for nested in item]
     return item
@@ -186,11 +186,11 @@ def _selection_args(config: GymRuntimeConfig, work_dir: Path) -> list[str]:
         # env we're running. Assumes the agent config's top-level key equals the agent name (the
         # simple_agent convention) *and* that the resources-server is registered under the
         # environment's own name — not universally true, so self-contained or differently-named
-        # servers set bind_resources_server=False and bind themselves via env_overrides.
+        # servers set bind_resources_server=False and bind themselves via hydra_params.
         selection.append(
             f"+{config.agent}.responses_api_agents.{config.agent}.resources_server.name={config.resources_server}"
         )
-    selection.extend(_flatten_overrides(config.env_overrides))
+    selection.extend(_flatten_overrides(config.hydra_params))
     # Gym is a Hydra app, so each invocation writes a timestamped run directory — by default
     # `outputs/<date>/<time>/` under the *current* directory. Since the subprocesses inherit this
     # process's cwd (so Gym can find env.yaml), the default would litter whatever directory the
@@ -229,13 +229,23 @@ class GymRuntimeConfig(BaseModel):
         "(the composable/Pattern-A agent case, e.g. simple_agent whose config leaves it '???'). Set False for "
         "self-contained agents that already bind their own resources-server.",
     )
-    env_overrides: dict[str, Any] = Field(
+    hydra_params: dict[str, Any] = Field(
         default_factory=dict,
-        description="Nested config overrides merged into Gym's config, applied after the auto-derived "
+        description="Parameters merged into Gym's Hydra config, applied after the auto-derived "
         "resources-server binding. Structured rather than pre-serialized Hydra strings so the config "
         "travels as JSON — `{'a': {'b': 1}}` becomes `++a.b=1` at invocation. This is the escape "
         "hatch for what Gym does not standardize: an environment whose resources-server is registered "
-        "under a different name, or which references a model server no shipped config defines.",
+        "under a different name, or which references a model server no shipped config defines. "
+        "Distinct from `env_vars`: these configure the Gym *environment*, not the OS environment.",
+    )
+    env_vars: dict[str, str] = Field(
+        default_factory=dict,
+        description="Environment variables set on the `gym` invocation, merged over the ones this "
+        "process already has. Some Gym environments are configurable only this way — `wmt_translation` "
+        "reads `WMT_TRANSLATION_COMET_PY_CACHE` for its model-cache root, defaulting to a path that "
+        "exists only inside NVIDIA's container image — and requiring the caller to export those turns "
+        "a property of the environment into a property of whoever launched the run. Redacted from "
+        "recorded provenance on the same rules as `hydra_params`.",
     )
     num_repeats: int = Field(default=1, ge=1, description="Attempts per row; each attempt becomes one trial.")
     concurrency: int = Field(
diff --git a/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/process.py b/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/process.py
index b4871a9891..05262049c1 100644
--- a/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/process.py
+++ b/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/process.py
@@ -20,6 +20,8 @@
 from collections.abc import Sequence
 from pathlib import Path
 
+from nemo_evaluator_sdk.agent_eval.runtimes.gym.config import GymRuntimeConfig
+
 logger = logging.getLogger(__name__)
 
 
@@ -186,3 +188,24 @@ async def _terminate(proc: asyncio.subprocess.Process, *, grace_s: float = 30.0)
     except asyncio.TimeoutError:
         _signal_group(pgid, signal.SIGKILL)
         await proc.wait()
+
+
+def _gym_invocation_env(config: GymRuntimeConfig) -> dict[str, str]:
+    """The environment the ``gym`` CLI is invoked with.
+
+    Three layers, lowest precedence first:
+
+    1. **This process's environment.** Gym reads credentials from its own gitignored ``env.yaml``,
+       but honours plenty of ordinary variables (``HF_TOKEN``, proxies) a caller expects to carry
+       over.
+    2. **``RAY_ENABLE_UV_RUN_RUNTIME_ENV=0``.** Gym launches each server from its own subdir with its
+       own ``.venv``; Ray (>=2.56) otherwise detects a ``uv run`` ancestor and tries to replicate that
+       uv project onto its workers, asserting the project's ``pyproject.toml`` lives in the driver's
+       cwd — which aborts startup. That hook is wrong for Gym, whose servers manage their own deps.
+    3. **``config.env_vars``.** Named explicitly in the run config, so it wins over both. That
+       includes the Ray setting: it is a default that makes Gym work, not an invariant, and someone
+       debugging that hook needs a way to put it back.
+
+    Lives here rather than in the runtime so the precedence is assertable without starting Ray.
+    """
+    return {**os.environ, "RAY_ENABLE_UV_RUN_RUNTIME_ENV": "0", **config.env_vars}
diff --git a/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/runtime.py b/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/runtime.py
index 69a09339b8..2b7cb4a7b4 100644
--- a/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/runtime.py
+++ b/packages/nemo_evaluator_sdk/src/nemo_evaluator_sdk/agent_eval/runtimes/gym/runtime.py
@@ -12,7 +12,6 @@
 
 import asyncio
 import logging
-import os
 import re
 import tempfile
 from collections import deque
@@ -24,7 +23,7 @@
     _HYDRA_SUBDIR,
     GymRuntimeConfig,
     _hydra_scalar,
-    _redact_env_overrides,
+    _redact_hydra_params,
     _selection_args,
 )
 from nemo_evaluator_sdk.agent_eval.runtimes.gym.dataset import _materialize_dataset, _source_datasets
@@ -33,6 +32,7 @@
     _VALIDATE_TIMEOUT_S,
     _drain_pumps,
     _gym_executable,
+    _gym_invocation_env,
     _pending_servers,
     _pump_stream,
     _terminate,
@@ -80,8 +80,10 @@ def runner_info(self) -> RunnerInfo:
         """Identify this runner and the Gym settings that shape its results.
 
         Credentials normally live in the Gym checkout's gitignored ``env.yaml`` and never reach this
-        object — but ``env_overrides`` is a free-form escape hatch, so its values are redacted by key
-        (see :func:`_redact_env_overrides`) rather than trusted.
+        object — but ``hydra_params`` and ``env_vars`` are free-form escape hatches, so their values
+        are redacted by key (see :func:`_redact_hydra_params`) rather than trusted. ``env_vars``
+        needs it at least as much: environment variables are the conventional way to pass an API
+        key, so a caller doing the obvious thing would otherwise write one into the run bundle.
         """
         cfg = self._config
         return RunnerInfo(
@@ -95,7 +97,8 @@ def runner_info(self) -> RunnerInfo:
                 "num_repeats": cfg.num_repeats,
                 "concurrency": cfg.concurrency,
                 "bind_resources_server": cfg.bind_resources_server,
-                "env_overrides": _redact_env_overrides(cfg.env_overrides),
+                "hydra_params": _redact_hydra_params(cfg.hydra_params),
+                "env_vars": _redact_hydra_params(cfg.env_vars),
                 "reward_key": cfg.reward_key,
             },
         )
@@ -201,7 +204,7 @@ async def _run_two_step(self, input_path: Path, output_path: Path, work_dir: Pat
         # detects a `uv run` ancestor and tries to replicate that uv project onto its workers,
         # asserting the project pyproject.toml lives in the driver's cwd — which aborts startup. That
         # hook is wrong for Gym (servers manage their own deps), so disable it for the subprocesses.
-        subprocess_env = {**os.environ, "RAY_ENABLE_UV_RUN_RUNTIME_ENV": "0"}
+        subprocess_env = _gym_invocation_env(cfg)
 
         selection = _selection_args(cfg, work_dir)
 
diff --git a/packages/nemo_evaluator_sdk/tests/agent_eval/test_gym_environment_coverage.py b/packages/nemo_evaluator_sdk/tests/agent_eval/test_gym_environment_coverage.py
index 054587b24d..8332b58f8a 100644
--- a/packages/nemo_evaluator_sdk/tests/agent_eval/test_gym_environment_coverage.py
+++ b/packages/nemo_evaluator_sdk/tests/agent_eval/test_gym_environment_coverage.py
@@ -82,7 +82,7 @@
 #: answer keeps "the plumbing works" separable from "the agent produced nothing".
 _CANNED_ANSWER = "This is a stub response from the NeMo Platform test suite."
 
-#: Stands in for a per-run absolute directory inside a case's `env_overrides`. A committed
+#: Stands in for a per-run absolute directory inside a case's `hydra_params`. A committed
 #: absolute path would be wrong on every machine, so the run substitutes a real one.
 _ABS_ASSETS_PLACEHOLDER = "_ABS_ASSETS"
 
@@ -213,7 +213,7 @@ class GymEnvironmentCase:
     #: Nested config overrides this environment needs beyond the runner's automatic binding. Empty
     #: where the standard `policy_model` wiring is enough; populated as the sweep discovers what an
     #: environment actually requires.
-    env_overrides: Mapping[str, Any] = field(default_factory=dict)
+    hydra_params: Mapping[str, Any] = field(default_factory=dict)
     #: Row field holding this environment's ground truth, and how it wants an answer spelled. When
     #: set, the stub answers each prompt with that row's own correct answer and the rollout test can
     #: assert a perfect score — which is what makes per-task attribution testable (see
@@ -277,7 +277,7 @@ def id(self) -> str:
         # hiding them behind guesswork would make the runner wrong for environments that follow the
         # convention. Recorded here so the cost to a caller is visible.
         bind_resources_server=False,
-        env_overrides={
+        hydra_params={
             "simple_agent": {
                 "responses_api_agents": {"simple_agent": {"resources_server": {"name": "gdpval_resources_server"}}}
             },
@@ -322,7 +322,7 @@ def id(self) -> str:
         #
         # `_ABS_ASSETS` is a placeholder: the rollout test substitutes a real tmp_path, since a
         # committed absolute path would be wrong on every machine.
-        env_overrides={
+        hydra_params={
             "legal_agent_bench": {
                 "resources_servers": {
                     "legal_agent_bench": {
@@ -417,7 +417,7 @@ def _require_environment(gym: str, case: GymEnvironmentCase) -> Path:
     return environment_dir
 
 
-def _selection(case: GymEnvironmentCase, hydra_dir: Path, env_overrides: Mapping[str, Any] | None = None) -> list[str]:
+def _selection(case: GymEnvironmentCase, hydra_dir: Path, hydra_params: Mapping[str, Any] | None = None) -> list[str]:
     """The selection arguments the runner passes to both `gym env validate` and `gym env start`.
 
     ``hydra.run.dir`` mirrors what the runner does: Gym is a Hydra app and writes a timestamped run
@@ -436,7 +436,7 @@ def _selection(case: GymEnvironmentCase, hydra_dir: Path, env_overrides: Mapping
         argv.append(f"+{case.agent}.responses_api_agents.{case.agent}.resources_server.name={case.resources_server}")
     # Resolved overrides when the caller has them, so validate checks the *same* values the rollout
     # would run — an unresolved `_ABS_ASSETS` placeholder would validate a config nothing ever uses.
-    argv.extend(_flatten_overrides(case.env_overrides if env_overrides is None else env_overrides))
+    argv.extend(_flatten_overrides(case.hydra_params if hydra_params is None else hydra_params))
     argv.append(f"hydra.run.dir={hydra_dir}")
     return argv
 
@@ -494,7 +494,7 @@ def _case_overrides(case: GymEnvironmentCase, tmp_path: Path) -> dict[str, Any]:
     """
     assets = tmp_path / "assets"
     assets.mkdir(parents=True, exist_ok=True)
-    rendered = json.dumps(case.env_overrides).replace(_ABS_ASSETS_PLACEHOLDER, str(assets))
+    rendered = json.dumps(case.hydra_params).replace(_ABS_ASSETS_PLACEHOLDER, str(assets))
     return json.loads(rendered)
 
 
@@ -563,7 +563,7 @@ async def test_gym_environment_runs_end_to_end(case: GymEnvironmentCase, tmp_pat
                 # Omit rather than pass None, so the runner's own default stays the single source of
                 # truth for every environment that does not need more.
                 **({"startup_timeout_s": case.startup_timeout_s} if case.startup_timeout_s else {}),
-                env_overrides={
+                hydra_params={
                     "policy_base_url": policy_base_url,
                     "policy_api_key": "stub-key",
                     "policy_model_name": "stub-model",
diff --git a/packages/nemo_evaluator_sdk/tests/agent_eval/test_gym_runtime.py b/packages/nemo_evaluator_sdk/tests/agent_eval/test_gym_runtime.py
index b56ee9835a..ba3a721877 100644
--- a/packages/nemo_evaluator_sdk/tests/agent_eval/test_gym_runtime.py
+++ b/packages/nemo_evaluator_sdk/tests/agent_eval/test_gym_runtime.py
@@ -37,6 +37,7 @@
     _LOG_TAIL_LINES,
     _drain_pumps,
     _gym_executable,
+    _gym_invocation_env,
     _pending_servers,
     _pump_stream,
 )
@@ -769,7 +770,7 @@ def test_selection_omits_the_binding_when_the_caller_binds_it_themselves(tmp_pat
     selection = _selection_args(
         _config(
             bind_resources_server=False,
-            env_overrides={
+            hydra_params={
                 "simple_agent": {"responses_api_agents": {"simple_agent": {"resources_server": {"name": "other"}}}}
             },
         ),
@@ -848,6 +849,34 @@ async def test_validate_config_raises_with_gyms_own_report(tmp_path: Path) -> No
     assert "mcqa" in str(excinfo.value)
 
 
+def test_invocation_env_inherits_the_process_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Gym honours ordinary variables a caller expects to carry over — proxies, HF_TOKEN — so the
+    # parent environment is the base layer rather than being replaced.
+    monkeypatch.setenv("A485_INHERITED", "from-parent")
+    assert _gym_invocation_env(_config())["A485_INHERITED"] == "from-parent"
+
+
+def test_invocation_env_disables_rays_uv_hook_by_default() -> None:
+    # Gym launches each server from its own subdir with its own .venv; Ray's uv-project replication
+    # asserts the driver's cwd holds the pyproject and aborts startup.
+    assert _gym_invocation_env(_config())["RAY_ENABLE_UV_RUN_RUNTIME_ENV"] == "0"
+
+
+def test_env_vars_win_over_the_inherited_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    # The point of the field: naming a variable in the run config makes it a property of the
+    # environment being run, not of whoever launched the runner.
+    monkeypatch.setenv("WMT_TRANSLATION_COMET_PY_CACHE", "/whatever-the-launcher-had")
+    env = _gym_invocation_env(_config(env_vars={"WMT_TRANSLATION_COMET_PY_CACHE": "/from-the-run-config"}))
+    assert env["WMT_TRANSLATION_COMET_PY_CACHE"] == "/from-the-run-config"
+
+
+def test_env_vars_can_restore_rays_uv_hook() -> None:
+    # The Ray default exists to make Gym work, not as an invariant — someone debugging that hook
+    # needs a way to put it back, so an explicit value has to outrank it.
+    env = _gym_invocation_env(_config(env_vars={"RAY_ENABLE_UV_RUN_RUNTIME_ENV": "1"}))
+    assert env["RAY_ENABLE_UV_RUN_RUNTIME_ENV"] == "1"
+
+
 def test_gym_executable_reports_how_to_install_when_absent(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(shutil, "which", lambda _: None)
     with pytest.raises(RuntimeError, match="own environment"):
diff --git a/packages/nemo_evaluator_sdk/tests/agent_eval/test_run_metadata.py b/packages/nemo_evaluator_sdk/tests/agent_eval/test_run_metadata.py
index 52c2ab14c9..798ee054a0 100644
--- a/packages/nemo_evaluator_sdk/tests/agent_eval/test_run_metadata.py
+++ b/packages/nemo_evaluator_sdk/tests/agent_eval/test_run_metadata.py
@@ -96,7 +96,7 @@ class _Provider:
                 "model_type",
                 "num_repeats",
                 "bind_resources_server",
-                "env_overrides",
+                "hydra_params",
                 "reward_key",
             },
         ),
@@ -186,8 +186,8 @@ def _info(**kwargs):
     assert _info()["effective_agent"] == "oracle"
 
 
-def test_gym_redacts_credential_looking_env_overrides() -> None:
-    # env_overrides is a free-form Hydra escape hatch forwarded to `gym env start`, and RunnerInfo.config
+def test_gym_redacts_credential_looking_hydra_params() -> None:
+    # hydra_params is a free-form Hydra escape hatch forwarded to `gym env start`, and RunnerInfo.config
     # is persisted into the run bundle — so a value that looks like a credential must not be written there.
     from nemo_evaluator_sdk.agent_eval.runtimes.gym import GymAgentTaskRunner, GymRuntimeConfig
 
@@ -196,7 +196,7 @@ def test_gym_redacts_credential_looking_env_overrides() -> None:
             agent="a",
             agent_config="c",
             resources_server="r",
-            env_overrides={
+            hydra_params={
                 "model": {"api_key": "sk-should-not-be-recorded", "temperature": 0.7},
                 "env": {"HF_TOKEN": "hf_should-not-be-recorded"},
                 "agent": {"nested": {"secret": "deep-should-not-be-recorded"}},
@@ -208,7 +208,7 @@ def test_gym_redacts_credential_looking_env_overrides() -> None:
         )
     )
 
-    recorded = runner.runner_info().config["env_overrides"]
+    recorded = runner.runner_info().config["hydra_params"]
 
     assert recorded == {
         "model": {
@@ -227,6 +227,40 @@ def test_gym_redacts_credential_looking_env_overrides() -> None:
     assert "should-not-be-recorded" not in json.dumps(recorded)
 
 
+def test_gym_redacts_credential_looking_env_vars() -> None:
+    # env_vars needs redaction at least as much as hydra_params: an environment variable is the
+    # conventional way to hand a process an API key, so a caller doing the obvious thing would
+    # otherwise write one straight into the run bundle.
+    from nemo_evaluator_sdk.agent_eval.runtimes.gym import GymAgentTaskRunner, GymRuntimeConfig
+
+    runner = GymAgentTaskRunner(
+        config=GymRuntimeConfig(
+            agent="a",
+            agent_config="c",
+            resources_server="r",
+            env_vars={
+                "WMT_TRANSLATION_COMET_PY_CACHE": "/shared/cache",
+                "OPENAI_API_KEY": "sk-should-not-be-recorded",
+                "HF_TOKEN": "hf_should-not-be-recorded",
+                "AWS_SECRET_ACCESS_KEY": "should-not-be-recorded",
+                "DB_PASSWORD": "should-not-be-recorded",
+            },
+        )
+    )
+
+    recorded = runner.runner_info().config["env_vars"]
+
+    assert recorded == {
+        # The reason the field exists — a cache path is provenance worth keeping verbatim.
+        "WMT_TRANSLATION_COMET_PY_CACHE": "/shared/cache",
+        "OPENAI_API_KEY": "<redacted>",
+        "HF_TOKEN": "<redacted>",
+        "AWS_SECRET_ACCESS_KEY": "<redacted>",
+        "DB_PASSWORD": "<redacted>",
+    }
+    assert "should-not-be-recorded" not in json.dumps(recorded)
+
+
 def test_model_provenance_records_the_endpoint_and_invocation_params() -> None:
     # A name alone is not an identity: the same model served from two URLs, or run at two different
     # temperatures, would otherwise record identical provenance.
diff --git a/plugins/nemo-evaluator/openapi/openapi.yaml b/plugins/nemo-evaluator/openapi/openapi.yaml
index 8fb023a6f7..2a7897e6ee 100644
--- a/plugins/nemo-evaluator/openapi/openapi.yaml
+++ b/plugins/nemo-evaluator/openapi/openapi.yaml
@@ -3777,14 +3777,27 @@ components:
           description: Auto-bind the agent's `resources_server.name` via a Hydra override.
             Set False for self-contained agents that already bind their own resources-server.
           default: true
-        env_overrides:
+        hydra_params:
           additionalProperties: true
           type: object
-          title: Env Overrides
-          description: "Extra config overrides for `gym env start`, as nested data\
+          title: Hydra Params
+          description: "Parameters merged into Gym's Hydra config, as nested data\
             \ \u2014 {'model': {'temperature': 0.7}} rather than pre-serialized Hydra\
             \ strings \u2014 so a spec survives being sent as JSON. Flattened to Hydra's\
-            \ grammar at invocation, after the auto-derived resources-server binding."
+            \ grammar at invocation, after the auto-derived resources-server binding.\
+            \ Distinct from `env_vars`: these configure the Gym environment, not the\
+            \ OS environment."
+        env_vars:
+          additionalProperties:
+            type: string
+          type: object
+          title: Env Vars
+          description: "Environment variables set on the `gym` invocation. Some Gym\
+            \ environments are configurable only this way \u2014 `wmt_translation`\
+            \ reads `WMT_TRANSLATION_COMET_PY_CACHE` for its model-cache root and\
+            \ defaults to a container-only path \u2014 and a job spec has no ambient\
+            \ environment to inherit from, so whatever the environment needs has to\
+            \ travel in the spec."
         num_repeats:
           type: integer
           minimum: 1.0
diff --git a/plugins/nemo-evaluator/src/nemo_evaluator/jobs/agent_evaluate.py b/plugins/nemo-evaluator/src/nemo_evaluator/jobs/agent_evaluate.py
index 6562d52dbd..d54a01c04c 100644
--- a/plugins/nemo-evaluator/src/nemo_evaluator/jobs/agent_evaluate.py
+++ b/plugins/nemo-evaluator/src/nemo_evaluator/jobs/agent_evaluate.py
@@ -360,7 +360,8 @@ def _resolve_target(
                     resources_server=target.resources_server,
                     model_type=target.model_type,
                     bind_resources_server=target.bind_resources_server,
-                    env_overrides=target.env_overrides,
+                    hydra_params=target.hydra_params,
+                    env_vars=target.env_vars,
                     num_repeats=target.num_repeats,
                     concurrency=target.concurrency,
                     startup_timeout_s=target.startup_timeout_s,
diff --git a/plugins/nemo-evaluator/src/nemo_evaluator/jobs/agent_spec.py b/plugins/nemo-evaluator/src/nemo_evaluator/jobs/agent_spec.py
index 77afdcc88c..7c786eec1c 100644
--- a/plugins/nemo-evaluator/src/nemo_evaluator/jobs/agent_spec.py
+++ b/plugins/nemo-evaluator/src/nemo_evaluator/jobs/agent_spec.py
@@ -173,11 +173,19 @@ class GymRunnerTarget(BaseModel):
         description="Auto-bind the agent's `resources_server.name` via a Hydra override. Set False for "
         "self-contained agents that already bind their own resources-server.",
     )
-    env_overrides: dict[str, Any] = Field(
+    hydra_params: dict[str, Any] = Field(
         default_factory=dict,
-        description="Extra config overrides for `gym env start`, as nested data — {'model': {'temperature': 0.7}} "
+        description="Parameters merged into Gym's Hydra config, as nested data — {'model': {'temperature': 0.7}} "
         "rather than pre-serialized Hydra strings — so a spec survives being sent as JSON. Flattened to "
-        "Hydra's grammar at invocation, after the auto-derived resources-server binding.",
+        "Hydra's grammar at invocation, after the auto-derived resources-server binding. Distinct from "
+        "`env_vars`: these configure the Gym environment, not the OS environment.",
+    )
+    env_vars: dict[str, str] = Field(
+        default_factory=dict,
+        description="Environment variables set on the `gym` invocation. Some Gym environments are "
+        "configurable only this way — `wmt_translation` reads `WMT_TRANSLATION_COMET_PY_CACHE` for its "
+        "model-cache root and defaults to a container-only path — and a job spec has no ambient "
+        "environment to inherit from, so whatever the environment needs has to travel in the spec.",
     )
     num_repeats: int = Field(default=1, ge=1, description="Attempts per row; each attempt becomes one trial.")
     concurrency: int = Field(
diff --git a/plugins/nemo-evaluator/tests/integration/conftest.py b/plugins/nemo-evaluator/tests/integration/conftest.py
index 35741ad639..0b78acb6f5 100644
--- a/plugins/nemo-evaluator/tests/integration/conftest.py
+++ b/plugins/nemo-evaluator/tests/integration/conftest.py
@@ -31,7 +31,7 @@
 #: IGW mock-provider prefix, and the env var the in-process IGW config reads it from. Applied to
 #: *this* (test) process via the ``_igw_mock_prefix`` fixture (not at import) so it never leaks into
 #: unrelated unit suites that merely collect this conftest; passed to the platform subprocess via
-#: each fixture's ``env_overrides``.
+#: each fixture's ``hydra_params``.
 MOCK_PROVIDER_PREFIX = "igw-mock-"
 MOCK_PROVIDER_PREFIX_ENVVAR = "NMP_INFERENCE_GATEWAY_MOCK_PROVIDER_PREFIX"
 CLICKHOUSE_XDIST_GROUP = "nmp_intake_clickhouse"
@@ -94,7 +94,7 @@ def running_platform(
     *,
     run_args: list[str],
     base_url: str,
-    env_overrides: dict[str, str] | None = None,
+    hydra_params: dict[str, str] | None = None,
     ready_timeout: float = 180.0,
 ) -> Iterator[str]:
     """Run ``nemo services run`` bound to ``base_url``'s port, yield the URL, then tear it down.
@@ -112,7 +112,7 @@ def running_platform(
     process = subprocess.Popen(
         ["uv", "run", "nemo", "services", "run", *run_args, "--port", str(port)],
         cwd=REPO_ROOT,
-        env={**os.environ, "NMP_BASE_URL": base_url, **(env_overrides or {})},
+        env={**os.environ, "NMP_BASE_URL": base_url, **(hydra_params or {})},
     )
     try:
         _wait_for_ready(base_url, timeout=ready_timeout, process=process)
@@ -138,7 +138,7 @@ def _igw_mock_prefix() -> Iterator[None]:
     var: the override is honored ahead of the cached/env config, so it works regardless of when the
     IGW config was first read, whereas a whole-repo run can read and cache that config before any
     plugin-local hook fires. The platform *subprocess* gets the same prefix via each fixture's
-    ``env_overrides``.
+    ``hydra_params``.
     """
     with igw_mock_provider_mode(MOCK_PROVIDER_PREFIX):
         yield
@@ -200,7 +200,7 @@ def subprocess_platform(tmp_path_factory: pytest.TempPathFactory) -> Iterator[st
     with running_platform(
         run_args=["--service-group", "all", "--controller-group", "all"],
         base_url=AGENT_PLATFORM_BASE_URL,
-        env_overrides={
+        hydra_params={
             "NMP_CONFIG_FILE_PATH": str(config_path),
             MOCK_PROVIDER_PREFIX_ENVVAR: MOCK_PROVIDER_PREFIX,
         },
@@ -222,7 +222,7 @@ def auth_subprocess_platform(tmp_path_factory: pytest.TempPathFactory) -> Iterat
     with running_platform(
         run_args=["--service-group", "all", "--controller-group", "all"],
         base_url=AGENT_AUTH_PLATFORM_BASE_URL,
-        env_overrides={
+        hydra_params={
             "NMP_CONFIG_FILE_PATH": str(config_path),
             MOCK_PROVIDER_PREFIX_ENVVAR: MOCK_PROVIDER_PREFIX,
         },
@@ -289,6 +289,6 @@ def docker_platform(tmp_path_factory: pytest.TempPathFactory) -> Iterator[str]:
     with running_platform(
         run_args=["--service-group", "all", "--controller-group", "all"],
         base_url=AGENT_DOCKER_PLATFORM_BASE_URL,
-        env_overrides={"NMP_CONFIG_FILE_PATH": str(config_path)},
+        hydra_params={"NMP_CONFIG_FILE_PATH": str(config_path)},
     ) as base_url:
         yield base_url
diff --git a/plugins/nemo-evaluator/tests/test_agent_evaluate.py b/plugins/nemo-evaluator/tests/test_agent_evaluate.py
index 5fcb2101d7..b4a97fdb05 100644
--- a/plugins/nemo-evaluator/tests/test_agent_evaluate.py
+++ b/plugins/nemo-evaluator/tests/test_agent_evaluate.py
@@ -314,7 +314,7 @@ def test_resolve_target_builds_gym_runtime_from_runner_target(tmp_path: Path) ->
         num_repeats=2,
         concurrency=4,
         reward_key="score",
-        env_overrides={"model": {"temperature": 0.7}},
+        hydra_params={"model": {"temperature": 0.7}},
     )
     target, prompt_template, params = AgentEvalJob._resolve_target(gym_target, ctx)
     assert isinstance(target, GymAgentTaskRunner)
@@ -324,7 +324,7 @@ def test_resolve_target_builds_gym_runtime_from_runner_target(tmp_path: Path) ->
     assert target._config.reward_key == "score"
     # Overrides are nested data on both sides of the seam — the spec model and the runtime config
     # must agree on the shape, or the spec validates and the runtime rejects it.
-    assert target._config.env_overrides == {"model": {"temperature": 0.7}}
+    assert target._config.hydra_params == {"model": {"temperature": 0.7}}
     # A runner shapes its own request, so it contributes no prompt template or inference params.
     assert prompt_template is None
     assert params is None
diff --git a/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/config.py b/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/config.py
index 21a3dabecd..200cd41884 100644
--- a/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/config.py
+++ b/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/config.py
@@ -128,10 +128,10 @@ def _flatten_overrides(overrides: Mapping[str, Any], _prefix: str = "") -> list[
     return arguments
 
 
-def _redact_env_overrides(overrides: Mapping[str, Any], _prefix: str = "") -> dict[str, Any]:
+def _redact_hydra_params(overrides: Mapping[str, Any], _prefix: str = "") -> dict[str, Any]:
     """Redact credential-looking values from overrides before they are recorded as provenance.
 
-    ``env_overrides`` is a free-form escape hatch forwarded to Gym, so nothing stops a caller passing
+    ``hydra_params`` is a free-form escape hatch forwarded to Gym, so nothing stops a caller passing
     ``{"model": {"api_key": "sk-..."}}``. ``RunnerInfo.config`` is persisted into the run bundle, so a
     value that looks like a credential must not be written there.
 
@@ -147,7 +147,7 @@ def _redact_env_overrides(overrides: Mapping[str, Any], _prefix: str = "") -> di
     for key, value in overrides.items():
         path = f"{_prefix}{key}"
         if isinstance(value, Mapping):
-            redacted[key] = _redact_env_overrides(value, f"{path}.")
+            redacted[key] = _redact_hydra_params(value, f"{path}.")
         elif any(marker in path.casefold() for marker in _SECRET_KEY_MARKERS):
             redacted[key] = _REDACTED
         elif isinstance(value, (list, tuple)):
@@ -158,9 +158,9 @@ def _redact_env_overrides(overrides: Mapping[str, Any], _prefix: str = "") -> di
 
 
 def _redact_list_item(item: Any, path: str) -> Any:
-    """Redact inside one element of a list-valued override. See :func:`_redact_env_overrides`."""
+    """Redact inside one element of a list-valued override. See :func:`_redact_hydra_params`."""
     if isinstance(item, Mapping):
-        return _redact_env_overrides(item, f"{path}.")
+        return _redact_hydra_params(item, f"{path}.")
     if isinstance(item, (list, tuple)):
         return [_redact_list_item(nested, path) for nested in item]
     return item
@@ -186,11 +186,11 @@ def _selection_args(config: GymRuntimeConfig, work_dir: Path) -> list[str]:
         # env we're running. Assumes the agent config's top-level key equals the agent name (the
         # simple_agent convention) *and* that the resources-server is registered under the
         # environment's own name — not universally true, so self-contained or differently-named
-        # servers set bind_resources_server=False and bind themselves via env_overrides.
+        # servers set bind_resources_server=False and bind themselves via hydra_params.
         selection.append(
             f"+{config.agent}.responses_api_agents.{config.agent}.resources_server.name={config.resources_server}"
         )
-    selection.extend(_flatten_overrides(config.env_overrides))
+    selection.extend(_flatten_overrides(config.hydra_params))
     # Gym is a Hydra app, so each invocation writes a timestamped run directory — by default
     # `outputs/<date>/<time>/` under the *current* directory. Since the subprocesses inherit this
     # process's cwd (so Gym can find env.yaml), the default would litter whatever directory the
@@ -229,13 +229,23 @@ class GymRuntimeConfig(BaseModel):
         "(the composable/Pattern-A agent case, e.g. simple_agent whose config leaves it '???'). Set False for "
         "self-contained agents that already bind their own resources-server.",
     )
-    env_overrides: dict[str, Any] = Field(
+    hydra_params: dict[str, Any] = Field(
         default_factory=dict,
-        description="Nested config overrides merged into Gym's config, applied after the auto-derived "
+        description="Parameters merged into Gym's Hydra config, applied after the auto-derived "
         "resources-server binding. Structured rather than pre-serialized Hydra strings so the config "
         "travels as JSON — `{'a': {'b': 1}}` becomes `++a.b=1` at invocation. This is the escape "
         "hatch for what Gym does not standardize: an environment whose resources-server is registered "
-        "under a different name, or which references a model server no shipped config defines.",
+        "under a different name, or which references a model server no shipped config defines. "
+        "Distinct from `env_vars`: these configure the Gym *environment*, not the OS environment.",
+    )
+    env_vars: dict[str, str] = Field(
+        default_factory=dict,
+        description="Environment variables set on the `gym` invocation, merged over the ones this "
+        "process already has. Some Gym environments are configurable only this way — `wmt_translation` "
+        "reads `WMT_TRANSLATION_COMET_PY_CACHE` for its model-cache root, defaulting to a path that "
+        "exists only inside NVIDIA's container image — and requiring the caller to export those turns "
+        "a property of the environment into a property of whoever launched the run. Redacted from "
+        "recorded provenance on the same rules as `hydra_params`.",
     )
     num_repeats: int = Field(default=1, ge=1, description="Attempts per row; each attempt becomes one trial.")
     concurrency: int = Field(
diff --git a/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/process.py b/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/process.py
index b4871a9891..8ab2f65b09 100644
--- a/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/process.py
+++ b/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/process.py
@@ -20,6 +20,8 @@
 from collections.abc import Sequence
 from pathlib import Path
 
+from nemo_platform.beta.evaluator.agent_eval.runtimes.gym.config import GymRuntimeConfig
+
 logger = logging.getLogger(__name__)
 
 
@@ -186,3 +188,24 @@ async def _terminate(proc: asyncio.subprocess.Process, *, grace_s: float = 30.0)
     except asyncio.TimeoutError:
         _signal_group(pgid, signal.SIGKILL)
         await proc.wait()
+
+
+def _gym_invocation_env(config: GymRuntimeConfig) -> dict[str, str]:
+    """The environment the ``gym`` CLI is invoked with.
+
+    Three layers, lowest precedence first:
+
+    1. **This process's environment.** Gym reads credentials from its own gitignored ``env.yaml``,
+       but honours plenty of ordinary variables (``HF_TOKEN``, proxies) a caller expects to carry
+       over.
+    2. **``RAY_ENABLE_UV_RUN_RUNTIME_ENV=0``.** Gym launches each server from its own subdir with its
+       own ``.venv``; Ray (>=2.56) otherwise detects a ``uv run`` ancestor and tries to replicate that
+       uv project onto its workers, asserting the project's ``pyproject.toml`` lives in the driver's
+       cwd — which aborts startup. That hook is wrong for Gym, whose servers manage their own deps.
+    3. **``config.env_vars``.** Named explicitly in the run config, so it wins over both. That
+       includes the Ray setting: it is a default that makes Gym work, not an invariant, and someone
+       debugging that hook needs a way to put it back.
+
+    Lives here rather than in the runtime so the precedence is assertable without starting Ray.
+    """
+    return {**os.environ, "RAY_ENABLE_UV_RUN_RUNTIME_ENV": "0", **config.env_vars}
diff --git a/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/runtime.py b/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/runtime.py
index 252dc003d6..48b68a7534 100644
--- a/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/runtime.py
+++ b/sdk/python/nemo-platform/src/nemo_platform/beta/evaluator/agent_eval/runtimes/gym/runtime.py
@@ -12,7 +12,6 @@
 
 import asyncio
 import logging
-import os
 import re
 import tempfile
 from collections import deque
@@ -24,7 +23,7 @@
     _HYDRA_SUBDIR,
     GymRuntimeConfig,
     _hydra_scalar,
-    _redact_env_overrides,
+    _redact_hydra_params,
     _selection_args,
 )
 from nemo_platform.beta.evaluator.agent_eval.runtimes.gym.dataset import _materialize_dataset, _source_datasets
@@ -33,6 +32,7 @@
     _VALIDATE_TIMEOUT_S,
     _drain_pumps,
     _gym_executable,
+    _gym_invocation_env,
     _pending_servers,
     _pump_stream,
     _terminate,
@@ -80,8 +80,10 @@ def runner_info(self) -> RunnerInfo:
         """Identify this runner and the Gym settings that shape its results.
 
         Credentials normally live in the Gym checkout's gitignored ``env.yaml`` and never reach this
-        object — but ``env_overrides`` is a free-form escape hatch, so its values are redacted by key
-        (see :func:`_redact_env_overrides`) rather than trusted.
+        object — but ``hydra_params`` and ``env_vars`` are free-form escape hatches, so their values
+        are redacted by key (see :func:`_redact_hydra_params`) rather than trusted. ``env_vars``
+        needs it at least as much: environment variables are the conventional way to pass an API
+        key, so a caller doing the obvious thing would otherwise write one into the run bundle.
         """
         cfg = self._config
         return RunnerInfo(
@@ -95,7 +97,8 @@ def runner_info(self) -> RunnerInfo:
                 "num_repeats": cfg.num_repeats,
                 "concurrency": cfg.concurrency,
                 "bind_resources_server": cfg.bind_resources_server,
-                "env_overrides": _redact_env_overrides(cfg.env_overrides),
+                "hydra_params": _redact_hydra_params(cfg.hydra_params),
+                "env_vars": _redact_hydra_params(cfg.env_vars),
                 "reward_key": cfg.reward_key,
             },
         )
@@ -201,7 +204,7 @@ async def _run_two_step(self, input_path: Path, output_path: Path, work_dir: Pat
         # detects a `uv run` ancestor and tries to replicate that uv project onto its workers,
         # asserting the project pyproject.toml lives in the driver's cwd — which aborts startup. That
         # hook is wrong for Gym (servers manage their own deps), so disable it for the subprocesses.
-        subprocess_env = {**os.environ, "RAY_ENABLE_UV_RUN_RUNTIME_ENV": "0"}
+        subprocess_env = _gym_invocation_env(cfg)
 
         selection = _selection_args(cfg, work_dir)