> This page is for version Latest (default). > For other versions, use one of these documentation indexes: > - Latest (default): https://docs.nvidia.com/nemo-helix/latest/llms.txt > - 0.8.0: https://docs.nvidia.com/nemo-helix/v0.8.0/llms.txt > - 0.7.1: https://docs.nvidia.com/nemo-helix/v0.7.1/llms.txt > - 0.7.0: https://docs.nvidia.com/nemo-helix/v0.7.0/llms.txt > - 0.6.0: https://docs.nvidia.com/nemo-helix/v0.6.0/llms.txt > - 0.5.1: https://docs.nvidia.com/nemo-helix/v0.5.1/llms.txt > - 0.5.0: https://docs.nvidia.com/nemo-helix/v0.5.0/llms.txt > - 0.4.0: https://docs.nvidia.com/nemo-helix/v0.4.0/llms.txt > - 0.3.0: https://docs.nvidia.com/nemo-helix/v0.3.0/llms.txt > - 0.2.0: https://docs.nvidia.com/nemo-helix/v0.2.0/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo-helix/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo-helix/_mcp/server. # Setup Install NeMo Helix and start working with AI agents. ## Prerequisites * Python 3.12-3.14 * An API key from one of: [NVIDIA Build](https://build.nvidia.com), [OpenAI](https://platform.openai.com/api-keys), [Anthropic](https://console.anthropic.com/settings/keys), [Google Gemini](https://aistudio.google.com/apikey), or a local [Ollama](https://ollama.com) instance (no key needed) * 16 GB available disk space and 8 GB RAM * [Docker](https://docs.docker.com/get-docker/) for the control plane's default local operating mode (`nemo setup --start-services` or default `nemo services run`), because the deployments service defaults to the Docker executor. Remote-deployment, CLI-only, and configs that omit or reconfigure deployments do not require it. See [Local Docker and Executors](/documentation/get-started/local-docker-and-executors) for when jobs and agents use subprocess instead. * For the PyPI install: [uv](https://docs.astral.sh/uv/) `>=0.10.10`, or `pip` in a Python environment * For the source checkout install: [Git](https://git-scm.com/), GNU Make, a C compiler, and [Flox](https://flox.dev/docs/install-flox/install) (recommended). A system-toolchain alternative is documented below. ## Install Choose the install path that matches what you want to do. ### Install from PyPI Use the [PyPI package](https://pypi.org/project/nemo-helix/) for the quickest local install. The `all` extra includes the SDK, CLI, Helix services, and default first-party plugins; drop it for the SDK and CLI alone. #### uv tool (recommended) One command, `nemo` available everywhere, nothing to activate. ```bash uv tool install "nemo-helix[all]" uv tool update-shell # Then restart the shell ``` #### Virtual environment Use when you also import the SDK from your own code. `nemo` works only while the environment is active. ```bash uv venv source .venv/bin/activate uv pip install "nemo-helix[all]" ``` Plain `pip install "nemo-helix[all]"` works in an environment you manage yourself. Continue with `nemo setup`. ### Install from source Use the source checkout when you are contributing to NeMo Helix, editing local plugins, building Studio assets from source, or running development workflows: > **Note** > > Install [Flox](https://flox.dev/docs/install-flox/install) before running `make bootstrap` for the smoothest setup. It supplies the repository-pinned uv, Node.js, and pnpm toolchain; you do not need to activate it first. ```bash git clone https://github.com/NVIDIA-NeMo/nemo-helix.git cd nemo-helix make bootstrap flox -q activate ``` The `make bootstrap` target creates the Python environment, syncs Python dependencies, builds Studio assets, and installs local plugins. Activate Flox afterward to continue development with the managed toolchain. Without Flox, install the system toolchain versions printed by `make toolchain-versions`, plus a C compiler, then run `make TOOLCHAIN=system bootstrap` followed by `source .venv/bin/activate`. If Studio asset bootstrap fails, the API can still run but Studio is unavailable until the web bundle is built. Ensure Flox is installed, or provide the required system Node.js and pnpm versions with `TOOLCHAIN=system`, then rerun `make bootstrap-studio` from the repository root. Verify the installation: ```bash nemo --help ``` ## Set up the platform ```bash nemo setup ``` The wizard walks through each stage: 1. **Connect to the platform** — uses a running platform, starts services locally, or connects to a remote instance 2. **Choose a provider** — select your model provider and enter your API key 3. **Register the provider** — connects the provider to the platform 4. **Discover models** — finds available models from your provider 5. **Select agent models** — pick a default model for quality-critical work and a fast model for latency-sensitive work; reuse the default if one model is enough 6. **Install skills** — adds NeMo skills to detected coding agents (Cursor, Claude Code, Codex) 7. **Choose a path** — optionally creates a sample workspace with a Fabric email security agent and evaluation artifacts Each stage is idempotent — you can re-run `nemo setup` at any time to add more providers or update your configuration. ### Connect to an existing deployment When the configured platform is not reachable, the setup wizard offers three choices: ```text Platform not reachable at http://localhost:8080. Start local services? 1. Yes, start services now 2. No, I want to connect to a remote Platform instance 3. No, I'll start them myself ``` Choose the remote option and enter the deployment's base URL. Setup verifies the URL, saves it to the active CLI context, and starts the existing OIDC login flow when the deployment has authentication enabled. It then continues with provider, model, skills, and the optional sample workspace. This connects the local CLI to an existing deployment; it does not install the platform on a remote host. The CLI and Python SDK then use this deployment for every command and tutorial. To configure remote access without rerunning setup, or to keep separate local and remote targets, follow [Connect with CLI Contexts](/documentation/reference/cli-reference/connect-to-deployments). ### Auth and OIDC source installs `nemo setup` and `nemo services run` do not create authorization role bindings by themselves. If you enable auth in source config with `auth.enabled: true` and set `auth.admin_email`, run the platform seed task so the bootstrap IAM bindings exist. For local single-process source runs, enable startup seeding before starting services: ```bash export NHX_SEED_ON_STARTUP=true nemo services run ``` You can set `platform.seed_on_startup: true` in platform config instead. If services are already running, wait for readiness and run the seed task manually from the repository root: ```bash curl -sf "${NHX_BASE_URL:-http://localhost:8080}/health/ready" uv run python -m nhx.platform_seed ``` `uv run nemo-helix run task --task nhx.platform_seed` is equivalent. The seed task is idempotent. It creates the **HelixAdmin** binding in the `system` workspace for `auth.admin_email`, the wildcard **Editor** binding for the default workspace, the wildcard **Viewer** binding for the `system` workspace, and the wildcard **WorkspaceCreator** binding for the `system` workspace. Without this step, OIDC login can succeed but admin operations may still return `403 Forbidden` because the RBAC bindings are missing. When setup completes, try chatting with the default model you selected: ```bash nemo chat ``` Use `--fast` for the fast model, or `--model ` for any other model from `nemo models list`. ### Sample workspace If you chose **Create a sample workspace and demo agent**, setup creates the `sample` workspace and deploys the Fabric email security agent. Use the Studio link printed at the end of setup to explore its dataset and evaluation config. ### Coding agent skills If you accepted **Install skills** during setup, your coding agent now has NeMo skills. Ask it to: * "Help me optimize my agent" — invokes the `nemo-agents-optimize` skill which analyzes deployed agents, compares models, suggests improvements * "Help me secure my agent" — invokes the `nemo-agents-secure` skill which runs audit scans, adds guardrails, flags vulnerabilities * "Evaluate my model \[model\_name] for helpfulness of responses on the HuggingFace nvidia/HelpSteer2 dataset. Limit evaluation to 5 samples" — runs evaluation * "Generate training data for \[task]" — builds Data Designer configurations Run `nemo skills list` to see which skills are installed for the current environment — the agent can only invoke what's in that list. ## Supported providers | Provider | Env var | Base URL | | -------------- | ---------------------------- | --------------------------------------------------------- | | NVIDIA Build | `NVIDIA_API_KEY` | `https://integrate.api.nvidia.com` | | OpenAI | `OPENAI_API_KEY` | `https://api.openai.com/v1` | | Anthropic | `ANTHROPIC_API_KEY` | `https://api.anthropic.com` | | Google Gemini | `GEMINI_API_KEY` | `https://generativelanguage.googleapis.com/v1beta/openai` | | Ollama (local) | — | `http://localhost:11434/v1` | | Custom | `NEMO_DEFAULT_INFERENCE_KEY` | Set via `NEMO_DEFAULT_INFERENCE_BASE_URL` | Ollama requires no API key but must be running before `nemo setup`. Start it with `ollama serve`. ## Non-interactive setup For CI pipelines, scripts, or automated environments, use `--auto`. Set one provider environment variable — the first match wins. ```bash export OPENAI_API_KEY=sk-... nemo setup --auto --start-services ``` **Priority order:** `NEMO_DEFAULT_INFERENCE_KEY` > `NVIDIA_API_KEY` > `OPENAI_API_KEY` > `ANTHROPIC_API_KEY` > `GEMINI_API_KEY` If your key is valid only against a non-default endpoint, set `NEMO_DEFAULT_INFERENCE_BASE_URL` with `NEMO_DEFAULT_INFERENCE_KEY`, or pass `--inference-base-url`: ```bash export NEMO_DEFAULT_INFERENCE_KEY=nvapi-... export NEMO_DEFAULT_INFERENCE_BASE_URL=https://inference-api.nvidia.com/v1 nemo setup --auto --start-services # Equivalent flag form export NVIDIA_API_KEY=nvapi-... nemo setup --auto --start-services --inference-base-url https://inference-api.nvidia.com/v1 ``` ### Flags | Flag | Default | Description | | ------------------------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------ | | `--auto` | off | Non-interactive mode: register provider from environment variables | | `--workspace`, `-w` | `default` | Target workspace | | `--start-services` / `--no-start-services` | prompt (interactive) or skip (auto) | Start local Helix services | | `--install-skills` / `--no-install-skills` | prompt (interactive) or skip (auto) | Install NeMo skills for detected coding agents | | `--inference-base-url` | provider default | Provider base URL to use in `--auto` mode; equivalent to `NEMO_DEFAULT_INFERENCE_BASE_URL` | Override the default and fast models with `NEMO_DEFAULT_MODEL` and `NEMO_FAST_MODEL`. If the fast override is omitted, it reuses the default. ```bash export OPENAI_API_KEY=sk-... export NEMO_DEFAULT_MODEL=default/openai-gpt-4.1 export NEMO_FAST_MODEL="$NEMO_DEFAULT_MODEL" nemo setup --auto --start-services ``` ### Examples ```bash # Full automation: services and skills export NVIDIA_API_KEY=nvapi-... nemo setup --auto --start-services --install-skills # Provider only (platform already running) export OPENAI_API_KEY=sk-... nemo setup --auto # Connect to an authenticated remote platform without prompts or a saved CLI context export NHX_BASE_URL=https://nhx.example.com export NHX_ACCESS_TOKEN=... export OPENAI_API_KEY=sk-... nemo setup --auto --no-start-services # Skip skills nemo setup --no-install-skills ``` ## What to explore next | Goal | Command or link | | --------------------------------------- | ------------------------------------------------------------------------------------------------------- | | Chat with the default model | `nemo chat` | | Chat with another model | `nemo chat --model ` | | List available models | `nemo models list` | | Open the Studio UI | [http://localhost:8080/studio/](http://localhost:8080/studio/) | | Browse docs from the CLI | `nemo docs --list` | | Understand Docker vs subprocess locally | [Local Docker and Executors](/documentation/get-started/local-docker-and-executors) | | Evaluate a model | [Run LLM-as-a-Judge Evaluation](/documentation/evaluate-models/tutorials/run-llm-as-a-judge-evaluation) | | Generate synthetic data | [Data Designer Tutorials](/documentation/design-synthetic-data/tutorials) | | Optimize an agent | [Optimize Agents](/documentation/agents/optimize-agents) | ## Python SDK The `nemo-helix` package includes a Python SDK. After running `nemo setup`, the simplest initialization reads your CLI context with `NemoClient.from_config()`: ```python from nemo_helix_plugin.client.client import NemoClient client = NemoClient.from_config() ``` The client uses the deployment, default workspace, and credentials from your current CLI context, so it follows `nemo config use-context` the same way the CLI does. In CI jobs or containers without a CLI configuration file, set `NHX_BASE_URL` and, for authenticated deployments, `NHX_ACCESS_TOKEN`; `from_config()` reads them. For details, see [Connect with CLI Contexts](/documentation/reference/cli-reference/connect-to-deployments). An asynchronous client, `AsyncNemoClient`, is also available with `AsyncNemoClient.from_config()`. See the [SDK reference](/documentation/reference/python-sdk) for details. ## Troubleshooting ### Docker daemon not available Default local startup fails closed when the resolved run starts the deployments service or controller with a Docker-backed `default_executor` and the Docker daemon is unreachable. Install and start Docker, then retry `nemo setup --start-services` or `nemo services run`. If Intake is selected and `NHX_INTAKE_CLICKHOUSE_URL` is unset, Intake also provisions a local ClickHouse container and needs Docker. Set `NHX_INTAKE_CLICKHOUSE_URL` to an external ClickHouse to skip that path. For the subprocess-vs-Docker matrix and escape hatches (`--config`, omit deployments), see [Local Docker and Executors](/documentation/get-started/local-docker-and-executors). ### Platform won't start Check `~/.local/state/nhx/instances//services.log` in the directory where you ran `nemo setup`. The most common cause is port 8080 already in use. ### Studio returns 404 or unavailable Studio requires the FastAPI web assets built by `make bootstrap-studio`. If `make bootstrap` warned that Studio asset bootstrap did not complete, install Flox or provide the versions printed by `make toolchain-versions` with `TOOLCHAIN=system`, then rerun `make bootstrap-studio` and `nemo services restart` from the repository root. ### No models discovered The provider may still be syncing. Wait 30 seconds and run `nemo models list`. If still empty, verify your API key is valid and the provider endpoint is reachable. ### "Platform not reachable" error Start services explicitly: ```bash nemo setup --start-services ``` Or start them in a separate terminal: ```bash nemo services run ``` ### Re-running setup `nemo setup` is idempotent. Existing secrets, providers, and agent deployments are detected and skipped. Run it again to add a second provider or re-attempt a stage that failed. ### Managing services ```bash nemo services ls # running instances only nemo services ls --all # include stopped instance directories (with logs on disk) nemo services rm # remove one stopped instance directory nemo services prune # remove all stopped instance directories curl -s http://localhost:8080/health/ready # check if running cat ~/.local/state/nhx/instances//services.log # view service output nemo services stop # stop the running instance for this scope ``` ### Stopped instance directories cluttering `ls --all` After stopping or crashing local services, stopped scope directories can remain under `~/.local/state/nhx/instances//`. Empty lock-only ghosts are cleaned automatically; directories with service logs stay until you remove them: ```bash nemo services ls --all # see stopped scopes nemo services logs --instance # inspect logs before removing nemo services rm # remove one stopped instance directory nemo services prune # remove all stopped instance directories ```