Install NeMo Helix
How to install NVIDIA NeMo Helix: what worked on a clean machine
NVIDIA NeMo Helix installs with one command, uv tool install "nemo-helix[all]", followed by nemo setup and nemo services start, and NeMo Studio then opens on port 8080. On a clean Ubuntu 24.04 machine in November 2026 that path needed five fixes before the sample agent answered. This page lists the requirements, the steps and each fix. We reported the problems to NVIDIA, and one has already been fixed on the main branch.
What you need
- A Linux machine. We used Ubuntu 24.04 with four CPU cores and 16 GB of memory.
- Python 3.12, the uv tool and Docker. Helix starts a ClickHouse container for traces.
- A model to call. A hosted model API works, so no GPU is needed to run the sample agent.
- Release tested: NeMo Helix 0.9.1. We also checked each problem against the main branch on 14 November 2026.
The steps
- Install: uv tool install "nemo-helix[all,nemo-agents-plugin-deepagents]". The second extra is fix 2 below.
- Point the adapter at the right Python before starting services. This is fixes 3 and 4 below.
- Run nemo setup and add a model provider. Use a hostname in the address, not an IP address. This is fix 1.
- Run nemo services start and open http://localhost:8080/studio.
- In NeMo Studio, create the sample workspace, open the agent and send a message in its chat tab.
The five fixes
| # | What you see | Fix | Reported |
|---|---|---|---|
| 1 | nemo setup --auto fails with a name pattern error when the model address uses an IP such as 127.0.0.1 | Use a hostname such as localhost | nemo-helix issue 4093 |
| 2 | The sample agent deploys and shows as running, then every call fails: the deepagents package is missing | Install with the extra nemo-agents-plugin-deepagents | nemo-helix issue 4092 |
| 3 | Calls fail with "No module named nemo_fabric_adapters" under /usr/bin/python3 | Set ADAPTER_PYTHON to the Python inside the Helix tool environment before starting services | NeMo-Fabric issue 635 |
| 4 | The deployed agent works but jobs such as nemo agents execute fail with the same error | Also set VIRTUAL_ENV to the tool environment and put its bin folder first on PATH | nemo-helix issue 4094 |
| 5 | The sample agent's default model returned a 404 from the hosted API with our key | Edit the agent configuration to a model your key can call | Not reported: it may depend on the key |
Two more things to know
- Runs that fail are listed as successful with zero errors in the trace list, so do not rely on the status column to find failures. Reported as nemo-helix issue 4091.
- In release 0.9.1, registering or redeploying an agent with a bare file name crashed, and redeploy removed the agent first. Use a full path. NVIDIA has already fixed this on the main branch.
How long it takes
With the fixes known, the install and the first working chat take well under an hour, most of it downloads. A small local model on CPU was too slow for the sample agent, which has a two-minute limit, so use a hosted model or a GPU.
Where Katonic fits
Helix is a workbench for engineers and installs on one machine. Katonic is the governed platform an organisation runs agents on. Every agent built in Katonic is a declarative definition that compiles to NVIDIA's open agent software. We test that software ourselves and report what we find, which is where this page comes from.
Read next
- What is NVIDIA NeMo Helix? →
- NVIDIA NeMo Helix, Relay and Fabric: field guide →
- Issue 4093: setup and IP addresses →
- Issue 4092: the all extra and deepagents →
- Issue 635: adapter starts under system Python →
- Issue 4094: jobs and ADAPTER_PYTHON →
- Issue 4091: failed runs stored as success →
- NeMo Helix on GitHub →
Questions and answers
How do I install NVIDIA NeMo Helix?
Run uv tool install "nemo-helix[all]", then nemo setup and nemo services start. NeMo Studio opens on port 8080. On a clean machine in November 2026 we also needed the five fixes on this page.
Can I run NeMo Helix without a GPU?
Yes, if your agents call a hosted model API. We ran it on four CPU cores. Model deployment and fine-tuning need GPUs.
Why does the NeMo Helix sample agent return a 502 error?
The usual causes are the missing deepagents package, the adapter starting under the system Python, or a model your key cannot call. Fixes 2, 3 and 5 on this page cover them.
What does "No module named nemo_fabric_adapters" mean?
NeMo Fabric started the adapter under the system Python. Set ADAPTER_PYTHON to the Python inside the Helix tool environment.
Does NeMo Helix need Docker?
Yes for the default setup. It starts a ClickHouse container to store traces.
Which version did you test?
NeMo Helix 0.9.1, with each problem rechecked on the main branch on 14 November 2026.