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:

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

Model Server Fields

policy_model:                                 # Server ID (use "policy_model" — agent configs expect this name)
  responses_api_models:                       # Server type (must be "responses_api_models" for model servers)
    openai_model:                             # Implementation (use "openai_model", "vllm_model", or "azure_openai_model")
      entrypoint: app.py                      # Python file to run
      openai_base_url: ${policy_base_url}     # API endpoint URL
      openai_api_key: ${policy_api_key}       # Authentication key
      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

my_resource:                                  # Server ID (your choice — agents reference this name)
  resources_servers:                          # Server type (must be "resources_servers" for resources servers)
    example_single_tool_call:                   # Implementation (must match a directory in resources_servers/)
      entrypoint: app.py                      # Python file to run
      domain: agent                           # Server category (see values below)
      verified: false                         # Passed reward profiling and training checks (default: false)
      description: "Short description"        # Server description
      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.

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

Dataset Configuration

Define datasets associated with agent servers for training and evaluation.

datasets:
  - name: my_dataset
    type: train
    jsonl_fpath: path/to/data.jsonl
    license: Apache 2.0
    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, CC BY-SA 4.0, CC BY-NC 3.0, TBD (see license)

Local Configuration (env.yaml)

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

# Policy model (required for most setups)
# Reference these variables in server configs using `${variable_name}` syntax (e.g., `${policy_base_url}`)
policy_base_url: https://api.openai.com/v1
policy_api_key: sk-your-api-key
policy_model_name: gpt-4o-2024-11-20
# Optional: store config paths for reuse
my_config_paths:
  - responses_api_models/openai_model/configs/openai_model.yaml
  - resources_servers/example_single_tool_call/configs/example_single_tool_call.yaml
# Optional: validation behavior
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.