Configuration | NeMo Gym

Complete syntax and field specifications for NeMo Gym configuration files.

Configuration for understanding how configs are structured and how servers connect.

File Locations

File	Location	Version Control
Server configs	`<server_type>/<implementation>/configs/*.yaml`	✅ Committed
env.yaml	Repository root (`./env.yaml`)	❌ Gitignored (user creates)

Server Configuration

All servers share this structure:

1 server_id:                    # Your unique name for this server
2   server_type:                # responses_api_models | resources_servers | responses_api_agents
3     implementation:           # Directory name inside the server type directory
4       entrypoint: app.py      # Python file to run
5       # ... additional fields vary by server type

Model Server Fields

1 policy_model:                                 # Server ID (use "policy_model" — agent configs expect this name)
2   responses_api_models:                       # Server type (must be "responses_api_models" for model servers)
3     openai_model:                             # Implementation (use "openai_model", "vllm_model", or "azure_openai_model")
4       entrypoint: app.py                      # Python file to run
5       openai_base_url: ${policy_base_url}     # API endpoint URL
6       openai_api_key: ${policy_api_key}       # Authentication key
7       openai_model: ${policy_model_name}      # Model identifier

Keep the server ID as policy_model — agent configs reference this name by default. The ${policy_base_url}, ${policy_api_key}, and ${policy_model_name} placeholders should be defined in env.yaml at the repository root, allowing you to change model settings in one place.

Resources Server Fields

1 my_resource:                                  # Server ID (your choice — agents reference this name)
2   resources_servers:                          # Server type (must be "resources_servers" for resources servers)
3     example_single_tool_call:                   # Implementation (must match a directory in resources_servers/)
4       entrypoint: app.py                      # Python file to run
5       domain: agent                           # Server category (see values below)
6       verified: false                         # Passed reward profiling and training checks (default: false)
7       description: "Short description"        # Server description
8       value: "What this improves"             # Training value provided

Domain values: math, coding, agent, knowledge, instruction_following, long_context, safety, games, e2e, other (see Domain)

Agent Server Fields

Agent servers must include both a resources_server and model_server block to specify which servers to use.

1 my_agent:                                     # Server ID (your choice — used in API requests)
2   responses_api_agents:                       # Server type (must be "responses_api_agents" for agent servers)
3     simple_agent:                             # Implementation (must match a directory in responses_api_agents/)
4       entrypoint: app.py                      # Python file to run
5       resources_server:                       # Specifies which resources server to use
6         type: resources_servers               # Always "resources_servers"
7         name: my_resource                     # Server ID of the resources server
8       model_server:                           # Specifies which model server to use
9         type: responses_api_models            # Always "responses_api_models"
10         name: policy_model                    # Server ID of the model server
11       datasets:                               # Optional: define for training workflows
12         - name: train                         # Dataset identifier
13           type: train                         # example | train | validation
14           jsonl_fpath: path/to/data.jsonl     # Path to data file
15           license: Apache 2.0                 # Required for train/validation

Dataset Configuration

Define datasets associated with agent servers for training and evaluation.

1 datasets:
2   - name: my_dataset
3     type: train
4     jsonl_fpath: path/to/data.jsonl
5     license: Apache 2.0
6     num_repeats: 1

Field	Required	Description
`name`	Yes	Dataset identifier
`type`	Yes	`example`, `train`, or `validation`
`jsonl_fpath`	Yes	Path to data file
`license`	For train/validation	License identifier (see values below)
`num_repeats`	No	Repeat dataset n times (default: `1`)

Dataset types:

example — For testing and development
train — Training data (requires license)
validation — Evaluation data (requires license)

License values: Apache 2.0, MIT, Creative Commons Attribution 4.0 International, Creative Commons Attribution-ShareAlike 4.0 International, TBD (see license)

Local Configuration (env.yaml)

Store secrets and local settings at the repository root. This file is gitignored.

1 # Policy model (required for most setups)
2 # Reference these variables in server configs using `${variable_name}` syntax (e.g., `${policy_base_url}`)
3 policy_base_url: https://api.openai.com/v1
4 policy_api_key: sk-your-api-key
5 policy_model_name: gpt-4o-2024-11-20
6 
7 # Optional: store config paths for reuse
8 my_config_paths:
9   - responses_api_models/openai_model/configs/openai_model.yaml
10   - resources_servers/example_single_tool_call/configs/example_single_tool_call.yaml
11 
12 # Optional: validation behavior
13 error_on_almost_servers: true   # Exit on invalid configs (default: true)

Command Line Usage

To run servers, use ng_run. NeMo Gym uses Hydra for configuration management.

Loading Configs

$ # Load one or more config files
$ ng_run "+config_paths=[config1.yaml,config2.yaml]"
$ 
$ # Use paths stored in env.yaml
$ ng_run "+config_paths=${my_config_paths}"

Overriding Values

$ # Override nested values (use dot notation after server ID)
$ ng_run "+config_paths=[config.yaml]" \
>     +my_server.resources_servers.my_impl.domain=coding
$ 
$ # Override policy model
$ ng_run "+config_paths=[config.yaml]" \
>     +policy_model_name=gpt-4o-mini
$ 
$ # Disable strict validation
$ ng_run "+config_paths=[config.yaml]" +error_on_almost_servers=false

Troubleshooting

Configuration for common configuration errors and solutions.