Configuration

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.

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

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

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

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

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

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)

$	# 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}"

$	# 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