Detailed Setup Guide#

Goal: Get NeMo Gym installed and servers running, then verify all components work together.

In this tutorial, you will:

Clone the repository and install dependencies
Configure your OpenAI API key
Start the NeMo Gym servers
Test the setup

Requirements#

Hardware Requirements#

NeMo Gym is designed to run on standard development machines without specialized hardware:

GPU: Not required for NeMo Gym library operation
- GPU may be needed for specific resource servers or model inference (see individual server documentation). E.g. if you are intending to train your model with NeMo-RL, GPU resources are required (see training documentation)
CPU: Any modern x86_64 or ARM64 processor (e.g., Intel, AMD, Apple Silicon)
RAM: Minimum 8 GB (16 GB+ recommended for larger environments and datasets)
Storage: Minimum 2 GB free disk space for installation and basic usage

Software Requirements#

Operating System:
- Linux (Ubuntu 20.04+, CentOS 7+, or equivalent)
- macOS (11.0+ for x86_64, 12.0+ for Apple Silicon)
- Windows via WSL2 (Ubuntu 20.04+ recommended)
Python: 3.12 or higher (required)
Git: For cloning the repository
curl or wget: For installing the UV package manager
Internet Connection: Required for:
- Downloading dependencies
- Accessing model APIs (OpenAI, Azure, etc.)
- Downloading datasets

Additional Requirements#

API Keys: Model provider access
- OpenAI API key with available credits (for quickstart and most examples)
- OR Azure OpenAI credentials
- OR self-hosted model setup (via vLLM or compatible inference server)
Ray: Automatically installed as a dependency for distributed processing (no separate setup required)

Verified Configurations#

The following configurations have been tested and verified:

Operating System	Architecture	Python Version	Status
Ubuntu 22.04 LTS	x86_64	3.12	✅ Verified
macOS 14+	Apple Silicon (M1/M2/M3)	3.12	✅ Verified
macOS 13+	x86_64 (Intel)	3.12	✅ Verified
Windows 11	x86_64 (via WSL2)	3.12	✅ Verified

Note

While NeMo Gym itself does not require a GPU, some resource servers (particularly those involving local model inference or training) may have GPU requirements. Check the individual resource server documentation for specific requirements.

Before You Start#

Make sure you have these prerequisites ready before beginning:

Git (for cloning the repository)
OpenAI API key with available credits (for the tutorial agent)

1. Clone and Install#

Clone the NeMo Gym repository and install dependencies:

# Clone the repository
git clone git@github.com:NVIDIA-NeMo/Gym.git
cd Gym

# Install UV (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Create virtual environment
uv venv --python 3.12
source .venv/bin/activate

# Install NeMo Gym
uv sync --extra dev --group docs

✅ Success Check: Verify that you can see something that indicates a newly activated environment such as (.venv) or (NeMo-Gym) in your terminal prompt.

2. Configure Your API Key#

Create an env.yaml file in the project root to configure your Policy Model credentials:

# Create env.yaml with your OpenAI credentials
cat > env.yaml << EOF
policy_base_url: https://api.openai.com/v1
policy_api_key: sk-your-actual-openai-api-key-here
policy_model_name: gpt-4.1-2025-04-14
EOF

Important

Replace sk-your-actual-openai-api-key-here with your real OpenAI API key. This file keeps secrets out of version control while making them available to NeMo Gym.

Requirements:

Your API key must have available credits (check OpenAI billing 🔗)
The model must support function calling (most GPT-4 models do)
Refer to OpenAI’s models documentation 🔗 for available models

Refer to Configuration Reference for additional env.yaml options.

Why GPT-4.1? We use GPT-4.1 for getting started because it provides low latency (no reasoning step) and reliable function calling support out-of-the-box, letting you focus on learning NeMo Gym without configuration complexity.

Can I use my own model? Yes! NeMo Gym works with any OpenAI-compatible inference server that supports function calling:

Self-hosted models: Use vLLM to serve your own models (see the vLLM setup guide)
Other providers: Any inference server that implements the OpenAI API specification

Simply update policy_base_url, policy_api_key, and policy_model_name in your env.yaml to point to your chosen endpoint.

3. Start the Servers#

# Define which servers to start
config_paths="resources_servers/example_single_tool_call/configs/example_single_tool_call.yaml,\
responses_api_models/openai_model/configs/openai_model.yaml"

# Start all servers
ng_run "+config_paths=[${config_paths}]"

✅ Success Check: Verify that you can see output like:

INFO:     Started server process [12345]
INFO:     Uvicorn running on http://127.0.0.1:11000 (Press CTRL+C to quit)
INFO:     Started server process [12346]  
INFO:     Uvicorn running on http://127.0.0.1:62920 (Press CTRL+C to quit)
...

Note

The head server always uses port 11000. Other servers get automatically assigned ports (like 62920, 52341, etc.) - your port numbers will differ from the example above.

When you ran ng_run, it started all the servers you configured:

Head server: coordinating all components
Resources server: defining tools and verification
Model server: providing LLM inference
Agent server: orchestrating how the model interacts with the resources. The agent server calls the model and resources servers using REST requests.

4. Test the Setup#

Open a new terminal (keep servers running in the first one):

# Navigate to project directory
cd /path/to/Gym

# Activate virtual environment
source .venv/bin/activate

# Test the agent
python responses_api_agents/simple_agent/client.py

✅ Success Check: Verify that you can see JSON output showing:

Agent calling the weather tool
Weather tool returning data
Agent responding to the user

Example output:

[
    {
        "arguments": "{\"city\":\"San Francisco\"}",
        "call_id": "call_OnWAk719Jr3tte4OmCJtJOB4",
        "name": "get_weather",
        "type": "function_call",
        "id": "fc_68a3739f2f0081a1aae4b93d5df07c100cb216b5cc4adbc4",
        "status": "completed"
    },
    {
        "call_id": "call_OnWAk719Jr3tte4OmCJtJOB4",
        "output": "{\"city\": \"San Francisco\", \"weather_description\": \"The weather in San Francisco is cold.\"}",
        "type": "function_call_output",
        "id": null,
        "status": null
    },
    {
        "id": "msg_68a373a1099081a1bb265ecf3b26c0dc0cb216b5cc4adbc4",
        "content": [
            {
                "annotations": [],
                "text": "The weather in San Francisco tonight is cold. You might want to wear layers or bring a jacket to stay comfortable while you're out. Let me know if you want outfit advice or tips on where to go!",
                "type": "output_text",
                "logprobs": []
            }
        ],
        "role": "assistant",
        "status": "completed",
        "type": "message"
    }
]

File Structure After Setup#

Your directory should look like this:

Gym/
├── env.yaml                    # Your API credentials (git-ignored)
├── .venv/                      # Virtual environment (git-ignored)
├── nemo_gym/                   # Core library code
├── resources_servers/          # Tools and environments
├── responses_api_models/       # Model integrations  
├── responses_api_agents/       # Agent implementations
└── docs/                       # Documentation files