DEV Community

Prem Naraindas
Prem Naraindas

Posted on Originally published at katonic.ai AI-assisted

Installing NVIDIA NeMo Helix on a clean machine: the five fixes I needed

#nvidia #ai #agents #python

NVIDIA deprecated the NeMo Agent Toolkit in October 2026 and replaced it with three open-source projects: NeMo Relay, NeMo Fabric and NeMo Helix. Helix is the one with a web interface, NeMo Studio, for evaluating and improving agents.

I wanted to see it for myself, so I installed it on a clean machine the way the documentation recommends. It took five fixes before the sample agent answered. None of them is hard once you know it. This post is the list, so you can skip the afternoon I spent finding them.

Everything here was tested on NeMo Helix 0.9.1 on 14 November 2026, and each problem was rechecked against the main branch the same day. I have reported them to NVIDIA, and the issue links are at the end.

The setup

  • Ubuntu 24.04, four CPU cores, 16 GB of memory, no GPU
  • Python 3.12, uv, and Docker (Helix starts a ClickHouse container to store traces)
  • A hosted model API for the agent to call

You do not need a GPU to run the sample agent or an evaluation. You do need one to deploy or fine-tune a model inside NeMo Studio.

The short version

If you only want the working commands:

# 1. Install, with the extra the sample agent needs
uv tool install "nemo-helix[all,nemo-agents-plugin-deepagents]"

# 2. Point the agent adapter at the right Python, for services and for jobs
export ADAPTER_PYTHON="$HOME/.local/share/uv/tools/nemo-helix/bin/python"
export VIRTUAL_ENV="$HOME/.local/share/uv/tools/nemo-helix"
export PATH="$VIRTUAL_ENV/bin:$PATH"

# 3. Set up a model provider (use a hostname, not an IP address)
nemo setup

# 4. Start and open NeMo Studio
nemo services start
# http://localhost:8080/studio
Enter fullscreen mode Exit fullscreen mode

Then in NeMo Studio: create the sample workspace, open the agent, and send a message in its chat tab. If the sample agent's default model is not one your API key can call, edit the agent configuration to one that is.

The rest of this post explains each line.

Fix 1: nemo setup --auto rejects an IP address

I pointed setup at a local model server by IP:

export NEMO_DEFAULT_INFERENCE_BASE_URL=http://127.0.0.1:11434/v1
export NEMO_DEFAULT_INFERENCE_KEY=placeholder
nemo setup --auto
Enter fullscreen mode Exit fullscreen mode

It failed with:

Invalid input:
  name  String should match pattern '^[a-z](?!.*--)[a-z0-9\-@.+_]{1,62}(?<!-)$'
Enter fullscreen mode Exit fullscreen mode

The error does not say which name. Setup derives the provider's name from the host in the address, turning dots into hyphens, so 127.0.0.1 becomes 127-0-0-1. Names must start with a letter, so it is rejected.

Fix: use a hostname. http://localhost:11434/v1 works.

Fix 2: the sample agent's runtime is not installed

With the documented install, uv tool install "nemo-helix[all]", the sample agent deploys and shows as running. Every call then fails with an HTTP 502. The real error, in the adapter's output, is:

RuntimeError: the 'deepagents' package is required for the Deep Agents adapter
Enter fullscreen mode Exit fullscreen mode

The sample agent is built on the Deep Agents harness. The all extra installs the adapter for that harness but not the library the adapter needs.

Fix: add the extra that brings it in.

uv tool install --force "nemo-helix[all,nemo-agents-plugin-deepagents]"
Enter fullscreen mode Exit fullscreen mode

Fix 3: the adapter starts under the wrong Python

The next call failed with:

/usr/bin/python3: Error while finding module specification for
'nemo_fabric_adapters.deepagents.adapter'
(ModuleNotFoundError: No module named 'nemo_fabric_adapters')
Enter fullscreen mode Exit fullscreen mode

Note the path: /usr/bin/python3. Helix runs agents through NeMo Fabric, and Fabric starts each agent adapter as a separate process. It picks the interpreter in this order: an ADAPTER_PYTHON variable, then the active virtual environment, then a python next to the running program, then python3 on the path.

A uv tool install sets neither variable. The third step should catch it, but it looks next to the resolved location of the interpreter, which is the system Python, not the tool environment. So it falls through to the system python3, which has none of the packages.

Fix: tell Fabric which Python to use, before starting services.

export ADAPTER_PYTHON="$HOME/.local/share/uv/tools/nemo-helix/bin/python"
Enter fullscreen mode Exit fullscreen mode

This is not specific to Helix. Any NeMo Fabric install that runs without an activated environment hits it.

Fix 4: jobs ignore ADAPTER_PYTHON

With fix 3 in place the deployed agent answered. Running the same agent as a job did not:

nemo agents execute --agent email-security-triage --input "..."
Enter fullscreen mode Exit fullscreen mode

The job ended with the same /usr/bin/python3 error. Jobs are started with a short list of environment variables carried over from the services process, and ADAPTER_PYTHON is not on it. PATH and VIRTUAL_ENV are.

Fix: set those two as well, so jobs find the right Python through the virtual environment rule.

export VIRTUAL_ENV="$HOME/.local/share/uv/tools/nemo-helix"
export PATH="$VIRTUAL_ENV/bin:$PATH"
Enter fullscreen mode Exit fullscreen mode

Then restart services.

Fix 5: the sample agent's default model

The sample agent's configuration names a default model. With my API key, the hosted API returned a 404 for that model. I have not reported this one, because it may depend on which models a key is entitled to.

Fix: edit the agent's configuration to name a model your key can call, and register it again.

A small local model on CPU was too slow for the sample agent, which has a two-minute limit. Use a hosted model or a GPU.

Two more things worth knowing

Failed runs are listed as successful. While I was working through the fixes above, every failed call showed in the trace list with status success and zero errors, and filtering by error returned nothing. The error is recorded in the event file for the run, but it is lost on the way to the trace store. Until that is fixed, do not rely on the status column to find failures.

Use full paths when registering an agent on 0.9.1. Registering or redeploying with a bare file name crashed, and redeploy removed the agent before it crashed. NVIDIA has already fixed this on main.

Was it worth it?

Yes. Once it runs, the evaluation and trace tooling is the best part of the stack. I ran an experiment that compared models on a sample dataset end to end, and every agent run is laid out step by step.

It helps to know what Helix is. It is a workbench for engineers who already have agents. There is no visual builder: agents are configuration files that you register from the command line or with a coding assistant. All three projects were before version 1.0 when I tested them, so pin your versions.

The reports

If you hit something I did not, I would like to hear about it.

I am the founder of Katonic AI. We build an enterprise agent platform whose agents compile to NVIDIA's open agent software, which is why we test that software ourselves. A longer version of this, with what each of the three projects does, is on our site.

Top comments (0)