> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/gym/_mcp/server.

# nemo_gym.global_config

## Module Contents

### Classes

| Name                                                                                   | Description |
| -------------------------------------------------------------------------------------- | ----------- |
| [`GlobalConfigDictParser`](#nemo_gym-global_config-GlobalConfigDictParser)             | -           |
| [`GlobalConfigDictParserConfig`](#nemo_gym-global_config-GlobalConfigDictParserConfig) | -           |

### Functions

| Name                                                                                   | Description                                                                                                                                           |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`_apply_verbosity`](#nemo_gym-global_config-_apply_verbosity)                         | Set logging to DEBUG when `verbose` is in the config. Runs in the CLI process and, because the                                                        |
| [`_find_open_port_using_range`](#nemo_gym-global_config-_find_open_port_using_range)   | -                                                                                                                                                     |
| [`_load_config_yaml`](#nemo_gym-global_config-_load_config_yaml)                       | `OmegaConf.load`, converting a YAML syntax error into a clean `ConfigError` naming file + line/column.                                                |
| [`find_open_port`](#nemo_gym-global_config-find_open_port)                             | -                                                                                                                                                     |
| [`format_almost_server_warning`](#nemo_gym-global_config-format_almost_server_warning) | Format user-friendly warning. Union literal errors are consolidated.                                                                                  |
| [`get_first_server_config_dict`](#nemo_gym-global_config-get_first_server_config_dict) | -                                                                                                                                                     |
| [`get_global_config_dict`](#nemo_gym-global_config-get_global_config_dict)             | This function provides a handle to the global configuration dict `global_config_dict`. We try to have one source of truth for everything in NeMo gym. |
| [`get_hf_token`](#nemo_gym-global_config-get_hf_token)                                 | -                                                                                                                                                     |
| [`get_wandb_run`](#nemo_gym-global_config-get_wandb_run)                               | -                                                                                                                                                     |
| [`set_global_config_dict`](#nemo_gym-global_config-set_global_config_dict)             | -                                                                                                                                                     |

### Data

[`AGENT_REF_KEY_NAME`](#nemo_gym-global_config-AGENT_REF_KEY_NAME)

[`CONFIG_PATHS_KEY_NAME`](#nemo_gym-global_config-CONFIG_PATHS_KEY_NAME)

[`COPY_KEY_NAME`](#nemo_gym-global_config-COPY_KEY_NAME)

[`DEFAULT_HEAD_SERVER_PORT`](#nemo_gym-global_config-DEFAULT_HEAD_SERVER_PORT)

[`DEFAULT_HOST_KEY_NAME`](#nemo_gym-global_config-DEFAULT_HOST_KEY_NAME)

[`DELETE_KEY_KEY_NAME`](#nemo_gym-global_config-DELETE_KEY_KEY_NAME)

[`DISALLOWED_PORTS_KEY_NAME`](#nemo_gym-global_config-DISALLOWED_PORTS_KEY_NAME)

[`DRY_RUN_KEY_NAME`](#nemo_gym-global_config-DRY_RUN_KEY_NAME)

[`ENTRYPOINT_KEY_NAME`](#nemo_gym-global_config-ENTRYPOINT_KEY_NAME)

[`HEAD_SERVER_DEPS_KEY_NAME`](#nemo_gym-global_config-HEAD_SERVER_DEPS_KEY_NAME)

[`HEAD_SERVER_KEY_NAME`](#nemo_gym-global_config-HEAD_SERVER_KEY_NAME)

[`HF_TOKEN_KEY_NAME`](#nemo_gym-global_config-HF_TOKEN_KEY_NAME)

[`INHERIT_FROM_KEY_NAME`](#nemo_gym-global_config-INHERIT_FROM_KEY_NAME)

[`JSON_OUTPUT_KEY_NAME`](#nemo_gym-global_config-JSON_OUTPUT_KEY_NAME)

[`NEMO_GYM_CONFIG_DICT_ENV_VAR_NAME`](#nemo_gym-global_config-NEMO_GYM_CONFIG_DICT_ENV_VAR_NAME)

[`NEMO_GYM_CONFIG_PATH_ENV_VAR_NAME`](#nemo_gym-global_config-NEMO_GYM_CONFIG_PATH_ENV_VAR_NAME)

[`NEMO_GYM_LOG_DIR_KEY_NAME`](#nemo_gym-global_config-NEMO_GYM_LOG_DIR_KEY_NAME)

[`NEMO_GYM_RESERVED_TOP_LEVEL_KEYS`](#nemo_gym-global_config-NEMO_GYM_RESERVED_TOP_LEVEL_KEYS)

[`PIP_INSTALL_VERBOSE_KEY_NAME`](#nemo_gym-global_config-PIP_INSTALL_VERBOSE_KEY_NAME)

[`POLICY_API_KEY_KEY_NAME`](#nemo_gym-global_config-POLICY_API_KEY_KEY_NAME)

[`POLICY_BASE_URL_KEY_NAME`](#nemo_gym-global_config-POLICY_BASE_URL_KEY_NAME)

[`POLICY_MODEL_KEY_NAME`](#nemo_gym-global_config-POLICY_MODEL_KEY_NAME)

[`POLICY_MODEL_NAME_KEY_NAME`](#nemo_gym-global_config-POLICY_MODEL_NAME_KEY_NAME)

[`PORT_RANGE_HIGH_KEY_NAME`](#nemo_gym-global_config-PORT_RANGE_HIGH_KEY_NAME)

[`PORT_RANGE_LOW_KEY_NAME`](#nemo_gym-global_config-PORT_RANGE_LOW_KEY_NAME)

[`PYTHON_VERSION_KEY_NAME`](#nemo_gym-global_config-PYTHON_VERSION_KEY_NAME)

[`QUERY_KEY_NAME`](#nemo_gym-global_config-QUERY_KEY_NAME)

[`RAY_HEAD_NODE_ADDRESS_KEY_NAME`](#nemo_gym-global_config-RAY_HEAD_NODE_ADDRESS_KEY_NAME)

[`RESPONSES_CREATE_PARAMS_KEY_NAME`](#nemo_gym-global_config-RESPONSES_CREATE_PARAMS_KEY_NAME)

[`RESPONSE_KEY_NAME`](#nemo_gym-global_config-RESPONSE_KEY_NAME)

[`ROLLOUT_INDEX_KEY_NAME`](#nemo_gym-global_config-ROLLOUT_INDEX_KEY_NAME)

[`SKILLS_REF_KEY_NAME`](#nemo_gym-global_config-SKILLS_REF_KEY_NAME)

[`SKIP_VENV_IF_PRESENT_KEY_NAME`](#nemo_gym-global_config-SKIP_VENV_IF_PRESENT_KEY_NAME)

[`TASK_INDEX_KEY_NAME`](#nemo_gym-global_config-TASK_INDEX_KEY_NAME)

[`USE_ABSOLUTE_IP`](#nemo_gym-global_config-USE_ABSOLUTE_IP)

[`UV_CACHE_DIR_KEY_NAME`](#nemo_gym-global_config-UV_CACHE_DIR_KEY_NAME)

[`UV_PIP_SET_PYTHON_KEY_NAME`](#nemo_gym-global_config-UV_PIP_SET_PYTHON_KEY_NAME)

[`UV_VENV_DIR_KEY_NAME`](#nemo_gym-global_config-UV_VENV_DIR_KEY_NAME)

[`VERBOSE_KEY_NAME`](#nemo_gym-global_config-VERBOSE_KEY_NAME)

[`_GLOBAL_CONFIG_DICT`](#nemo_gym-global_config-_GLOBAL_CONFIG_DICT)

[`_MISSING_REF`](#nemo_gym-global_config-_MISSING_REF)

[`_WANDB_RUN`](#nemo_gym-global_config-_WANDB_RUN)

### API

```python
class nemo_gym.global_config.GlobalConfigDictParser()
```

**Bases:** `BaseModel`

```python
nemo_gym.global_config.GlobalConfigDictParser._recursive_index_dict_using_path(
    dict_config: omegaconf.DictConfig,
    path: typing.List[str]
) -> omegaconf.DictConfig | object
```

```python
nemo_gym.global_config.GlobalConfigDictParser._recursively_hide_secrets(
    dict_config: omegaconf.DictConfig
) -> None
```

```python
nemo_gym.global_config.GlobalConfigDictParser._recursively_hide_secrets_helper(
    dict_config: omegaconf.DictConfig
) -> None
```

```python
nemo_gym.global_config.GlobalConfigDictParser._recursively_swap_keys(
    dict_config: omegaconf.DictConfig
) -> None
```

```python
nemo_gym.global_config.GlobalConfigDictParser._recursively_swap_keys_helper(
    dict_config: omegaconf.DictConfig,
    original_dict_config: omegaconf.DictConfig,
    frozen_dict_config: omegaconf.DictConfig
) -> None
```

```python
nemo_gym.global_config.GlobalConfigDictParser._walk_missing_value_paths(
    node,
    prefix: str = ''
) -> typing.List[str]
```

```python
nemo_gym.global_config.GlobalConfigDictParser.collect_missing_value_paths(
    config: omegaconf.DictConfig
) -> typing.List[str]
```

Return the dotted paths of every unset (OmegaConf '???') leaf, without raising.

We convert to a plain container with `resolve=False, throw_on_missing=False` so that
neither MISSING values nor unresolved interpolations (`${...}`) cause an exception — then
walk the plain structure. Iterating or indexing the live DictConfig would raise.

```python
nemo_gym.global_config.GlobalConfigDictParser.detect_and_report_almost_servers(
    global_config_dict: omegaconf.DictConfig
) -> typing.List[typing.Tuple[str, pydantic.ValidationError]]
```

```python
nemo_gym.global_config.GlobalConfigDictParser.filter_for_server_instance_configs(
    global_config_dict: omegaconf.DictConfig
) -> typing.List[nemo_gym.config_types.ServerInstanceConfig]
```

```python
nemo_gym.global_config.GlobalConfigDictParser.load_extra_config_paths(
    config_paths: typing.List[str]
) -> typing.Tuple[typing.List[str], typing.List[omegaconf.DictConfig]]
```

Returns the new total config\_paths and the extra configs

```python
nemo_gym.global_config.GlobalConfigDictParser.parse(
    parse_config: typing.Optional[nemo_gym.global_config.GlobalConfigDictParserConfig] = None
) -> omegaconf.DictConfig
```

```python
nemo_gym.global_config.GlobalConfigDictParser.parse_global_config_dict_from_cli() -> omegaconf.DictConfig
```

```python
nemo_gym.global_config.GlobalConfigDictParser.parse_no_environment(
    initial_global_config_dict: typing.Optional[omegaconf.DictConfig] = None
) -> omegaconf.DictConfig
```

```python
nemo_gym.global_config.GlobalConfigDictParser.raise_on_missing_values(
    global_config_dict: omegaconf.DictConfig
) -> None
```

Fail fast with one actionable error listing every unset '???' value.

Without this, the first unset value surfaces deep in the run pipeline as an opaque
omegaconf MissingMandatoryValue, one field at a time and with no override guidance.

```python
nemo_gym.global_config.GlobalConfigDictParser.raise_on_no_server_instances(
    global_config_dict: omegaconf.DictConfig
) -> None
```

Fail fast if a run has no server instances to start.

Without this, `gym env start` with an empty/omitted `config_paths` starts the head server and Ray
and then hangs with nothing to run. We catch it before Ray initialises with an actionable
message instead.

```python
nemo_gym.global_config.GlobalConfigDictParser.validate_and_populate_defaults(
    server_instance_configs: typing.List[nemo_gym.config_types.ServerInstanceConfig],
    default_host: str,
    port_range_low: int,
    port_range_high: int,
    initial_disallowed_ports: typing.Optional[typing.List[int]] = None
) -> typing.List[int]
```

```python
class nemo_gym.global_config.GlobalConfigDictParserConfig()
```

**Bases:** `BaseModel`

```python
nemo_gym.global_config._apply_verbosity(
    global_config_dict: omegaconf.DictConfig
) -> None
```

Set logging to DEBUG when `verbose` is in the config. Runs in the CLI process and, because the
config dict is forwarded to every spun-up server, in each server process too.

```python
nemo_gym.global_config._find_open_port_using_range(
    disallowed_ports: typing.List[int],
    port_range_low: int,
    port_range_high: int,
    max_retries: int = 50
) -> int
```

```python
nemo_gym.global_config._load_config_yaml(
    config_path
)
```

`OmegaConf.load`, converting a YAML syntax error into a clean `ConfigError` naming file + line/column.

`FileNotFoundError` is left to propagate so callers can report a missing-path error themselves.

```python
nemo_gym.global_config.find_open_port(
    disallowed_ports: typing.Optional[typing.List[int]] = None,
    max_retries: int = 50
) -> int
```

```python
nemo_gym.global_config.format_almost_server_warning(
    server_name: str,
    error: pydantic.ValidationError
) -> str
```

Format user-friendly warning. Union literal errors are consolidated.
Union discriminator noise is filtered out. Explanation:
Pydantic validation is quirky- it will report all failures in the union if any union member fails. Example:
If an agent server contains an invalid license, it will not only show the error for the invalid license in ResponsesAPIAgentServerInstanceConfig, but also missing values for ResponsesAPIModelServerInstanceConfig `responses_api_models` and ResourcesServerInstanceConfig `resources_servers`.

```python
nemo_gym.global_config.get_first_server_config_dict(
    global_config_dict: omegaconf.DictConfig,
    top_level_path: str
) -> omegaconf.DictConfig
```

```python
nemo_gym.global_config.get_global_config_dict(
    global_config_dict_parser_config: typing.Optional[nemo_gym.global_config.GlobalConfigDictParserConfig] = None,
    global_config_dict_parser_cls: typing.Type[nemo_gym.global_config.GlobalConfigDictParser] = GlobalConfigDictParser
) -> omegaconf.DictConfig
```

This function provides a handle to the global configuration dict `global_config_dict`. We try to have one source of truth for everything in NeMo gym.
This config is resolved once and only once, immediately on a run command.

On first initialization, the global config dict will be loaded from the following sources in order of priority (later items are higher priority):

1. Configuration yamls specified in `config_paths` parameter.
2. Configuration (usually sensitive values like API keys, etc) from a local `.env.yaml` file.
3. Command line argument configuration.

Validation is performed on the passed in configs:

1. If a host or port is not provided for a server, defaults will be provided. Ports are resolved by the OS.
2. If there are server reference configs, the respective server names and types will be validated against the remainder of the config.

Then, the global config dict will be cached and reused.

If this function is run by a child server of the main proc, that child will have been spun up with an environment variable with key NEMO\_GYM\_CONFIG\_DICT\_ENV\_VAR\_NAME. The config dict will be read directly off this variable, cached, and returned with no additional validation.

```python
nemo_gym.global_config.get_hf_token() -> typing.Optional[str]
```

```python
nemo_gym.global_config.get_wandb_run() -> typing.Optional[wandb.Run]
```

```python
nemo_gym.global_config.set_global_config_dict(
    global_config_dict_parser_config: typing.Optional[nemo_gym.global_config.GlobalConfigDictParserConfig] = None,
    global_config_dict_parser_cls: typing.Type[nemo_gym.global_config.GlobalConfigDictParser] = GlobalConfigDictParser
) -> None
```

```python
nemo_gym.global_config.AGENT_REF_KEY_NAME = 'agent_ref'
```

```python
nemo_gym.global_config.CONFIG_PATHS_KEY_NAME = 'config_paths'
```

```python
nemo_gym.global_config.COPY_KEY_NAME = '_copy'
```

```python
nemo_gym.global_config.DEFAULT_HEAD_SERVER_PORT = 11000
```

```python
nemo_gym.global_config.DEFAULT_HOST_KEY_NAME = 'default_host'
```

```python
nemo_gym.global_config.DELETE_KEY_KEY_NAME = '_delete_key'
```

```python
nemo_gym.global_config.DISALLOWED_PORTS_KEY_NAME = 'disallowed_ports'
```

```python
nemo_gym.global_config.DRY_RUN_KEY_NAME = 'dry_run'
```

```python
nemo_gym.global_config.ENTRYPOINT_KEY_NAME = 'entrypoint'
```

```python
nemo_gym.global_config.HEAD_SERVER_DEPS_KEY_NAME = 'head_server_deps'
```

```python
nemo_gym.global_config.HEAD_SERVER_KEY_NAME = 'head_server'
```

```python
nemo_gym.global_config.HF_TOKEN_KEY_NAME = 'hf_token'
```

```python
nemo_gym.global_config.INHERIT_FROM_KEY_NAME = '_inherit_from'
```

```python
nemo_gym.global_config.JSON_OUTPUT_KEY_NAME = 'json'
```

```python
nemo_gym.global_config.NEMO_GYM_CONFIG_DICT_ENV_VAR_NAME = 'NEMO_GYM_CONFIG_DICT'
```

```python
nemo_gym.global_config.NEMO_GYM_CONFIG_PATH_ENV_VAR_NAME = 'NEMO_GYM_CONFIG_PATH'
```

```python
nemo_gym.global_config.NEMO_GYM_LOG_DIR_KEY_NAME = 'nemo_gym_log_dir'
```

```python
nemo_gym.global_config.NEMO_GYM_RESERVED_TOP_LEVEL_KEYS = [CONFIG_PATHS_KEY_NAME, ENTRYPOINT_KEY_NAME, DEFAULT_HOST_KEY_NAME, HEAD_SERVER_...
```

```python
nemo_gym.global_config.PIP_INSTALL_VERBOSE_KEY_NAME = 'pip_install_verbose'
```

```python
nemo_gym.global_config.POLICY_API_KEY_KEY_NAME = 'policy_api_key'
```

```python
nemo_gym.global_config.POLICY_BASE_URL_KEY_NAME = 'policy_base_url'
```

```python
nemo_gym.global_config.POLICY_MODEL_KEY_NAME = 'policy_model'
```

```python
nemo_gym.global_config.POLICY_MODEL_NAME_KEY_NAME = 'policy_model_name'
```

```python
nemo_gym.global_config.PORT_RANGE_HIGH_KEY_NAME = 'port_range_high'
```

```python
nemo_gym.global_config.PORT_RANGE_LOW_KEY_NAME = 'port_range_low'
```

```python
nemo_gym.global_config.PYTHON_VERSION_KEY_NAME = 'python_version'
```

```python
nemo_gym.global_config.QUERY_KEY_NAME = 'query'
```

```python
nemo_gym.global_config.RAY_HEAD_NODE_ADDRESS_KEY_NAME = 'ray_head_node_address'
```

```python
nemo_gym.global_config.RESPONSES_CREATE_PARAMS_KEY_NAME = 'responses_create_params'
```

```python
nemo_gym.global_config.RESPONSE_KEY_NAME = 'response'
```

```python
nemo_gym.global_config.ROLLOUT_INDEX_KEY_NAME = '_ng_rollout_index'
```

```python
nemo_gym.global_config.SKILLS_REF_KEY_NAME = 'skills_ref'
```

```python
nemo_gym.global_config.SKIP_VENV_IF_PRESENT_KEY_NAME = 'skip_venv_if_present'
```

```python
nemo_gym.global_config.TASK_INDEX_KEY_NAME = '_ng_task_index'
```

```python
nemo_gym.global_config.USE_ABSOLUTE_IP = 'use_absolute_ip'
```

```python
nemo_gym.global_config.UV_CACHE_DIR_KEY_NAME = 'uv_cache_dir'
```

```python
nemo_gym.global_config.UV_PIP_SET_PYTHON_KEY_NAME = 'uv_pip_set_python'
```

```python
nemo_gym.global_config.UV_VENV_DIR_KEY_NAME = 'uv_venv_dir'
```

```python
nemo_gym.global_config.VERBOSE_KEY_NAME = 'verbose'
```

```python
nemo_gym.global_config._GLOBAL_CONFIG_DICT = None
```

```python
nemo_gym.global_config._MISSING_REF = object()
```

```python
nemo_gym.global_config._WANDB_RUN: Optional[Run] = None
```