Configuration

Complete syntax and field specifications for NeMo Gym configuration files.

File Locations

Artifact Roots (results_dir, cache_dir)

Two opt-in top-level config keys that servers can consult for state that outlives a request:

These are opt-in settings, not a global redirect: components that don’t consult them (profiling output, rollout capture, logs, Hugging Face caches, other agents) keep their own locations, and the module-level RESULTS_DIR/CACHE_DIR constants remain unchanged defaults for such consumers. New artifact producers are encouraged to read these keys.

Both are independently overridable (results_dir=/shared/results cache_dir=/shared/cache), and relative values are normalized to absolute paths at parse time so all server processes agree. uv_venv_dir keeps its own key and default.

On multi-node deployments, the swe_agents server embeds these paths in commands executed from other nodes, so both roots must resolve to the same content at the same path on every node that runs rollout workers: use a shared filesystem, or pre-stage identical trees at the same path on each node (for example, baked into the container image). A cache that exists only on the head node breaks remote rollouts.

Servers that pre-staged setup trees next to the package (the layout before cache_dir existed, for example baked container images) keep using those trees only while cache_dir is left at its default — explicitly configuring cache_dir opts out, and removing the pre-staged trees migrates a default-config deployment. Contents accumulate across runs; both directories are safe to delete when no run is active.

Path Resolution and External Roots

Gym resolves every relative path — config_paths, env.yaml, prompt configs, dataset files, the --<component> selectors (--benchmark, --environment, --model-type, --resources-server), and server directories (used by gym env test) — against an ordered list of roots, returning the first one where the path exists:

1. Extra roots from NEMO_GYM_EXTRA_ROOTS (or --search-dir), in the order listed.
2. The current working directory — your project.
3. The Gym install root, where the built-in components live (in both editable and wheel installs).

Earlier roots win, so a component you provide shadows a same-named built-in. Absolute paths are used unchanged.

External roots (NEMO_GYM_EXTRA_ROOTS)

Point Gym at one or more extra roots so your own benchmarks, environments, resources servers, agents, models, configs, prompts, and data resolve by name — without forking Gym or copying files into the install tree. Each root uses the same layout as the Gym repo:

<root>/
├── benchmarks/<name>/
├── environments/<name>/
├── resources_servers/<name>/
├── responses_api_agents/<name>/
└── responses_api_models/<name>/

Set it as an os.pathsep-separated list (: on Linux/macOS):

$
export NEMO_GYM_EXTRA_ROOTS=~/my-plugins:~/team-benchmarks
$
$
gym list benchmarks                 # your benchmarks appear alongside the built-ins
$
gym eval run --benchmark my_bench --model-type vllm_model

The variable is inherited by the servers Gym spawns, so plugin components resolve inside them too.

--search-dir

--search-dir DIR (repeatable) is the per-invocation equivalent: Gym sets NEMO_GYM_EXTRA_ROOTS to its value for the duration of that command, then restores it. Use it for one-off runs instead of exporting the variable.

$
gym list benchmarks --search-dir ~/my-plugins
$
gym eval run --benchmark my_bench --model-type vllm_model --search-dir ~/my-plugins

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

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, translation, e2e, rlhf, 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

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.

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: multi-node setups
13
use_absolute_ip: true           # Bind servers to the host's IP instead of 127.0.0.1 (default: false)
14
15
# Optional: validation behavior
16
error_on_almost_servers: true   # Exit on invalid configs (default: true)

Multi-Node Configuration

use_absolute_ip — Controls the default host servers bind to.

• Default: false — servers use 127.0.0.1 (localhost).
• When to use: Set to true for multi-node setups (e.g. multi-node Ray clusters) where servers must communicate across machines.
• Effect: Resolves and uses the host’s IP address (gethostbyname(gethostname())) instead of localhost.

Command Line Usage

To run servers, use gym env start. NeMo Gym uses Hydra for configuration management.

Loading Configs

$
# Load one or more config files
$
gym env start \
>
    --config config1.yaml \
>
    --config config2.yaml
$
$
# Use paths stored in env.yaml
$
gym env start "+config_paths=${my_config_paths}"

Overriding Values

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

Troubleshooting