# NeMo Setup

Install {{platform_name}} and start working with AI agents.

## Prerequisites

- Python 3.11 or higher
- [Git](https://git-scm.com/), GNU Make, [uv](https://docs.astral.sh/uv/), [Node.js (≥22.18.0, <23)](https://nodejs.org/en/download) satisfying `web/package.json`, and [pnpm](https://pnpm.io/installation)
- 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

## Install

Clone the source repository and bootstrap the local environment:

```bash
git clone https://github.com/NVIDIA-NeMo/Platform.git
cd Platform
make bootstrap
source .venv/bin/activate
```

The `make bootstrap` target creates the Python environment, syncs Python dependencies, builds Studio assets, and installs local plugins.

If Studio asset bootstrap fails, the API can still run but Studio is unavailable until the web bundle is built. Install Node.js with pnpm using `pnpm env use --global 22.18.0`, 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. **Start services** — launches the platform locally
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. **Set a default model** — pick the model to use by default
6. **Install skills** — adds NeMo skills to detected coding agents (Cursor, Claude Code, Codex)
7. **Deploy agent** — starts the built-in NeMo agent on the platform

Each stage is idempotent — you can re-run `nemo setup` at any time to add more providers or update your configuration.

When setup completes, try chatting with the model you selected. Use the model name shown at the end of setup (or find it with `nemo models list`):

```bash
nemo chat <model-name>
```

## Work with agents

`nemo setup` can install two kinds of agent integration. Both are optional and enabled during the wizard.

### Platform agent

If you accepted **Deploy agent** during setup, the built-in NeMo agent is running on the platform. It can manage workspaces, run evaluations, and perform other platform tasks through natural language:

```bash
nemo agents invoke --agent nemo-agent \
    --input "Help me optimize my agent"
```

```bash
nemo agents invoke --agent nemo-agent \
    --input "Help me secure my agent"
```

### Coding agent skills

If you accepted **Install skills** during setup and use Cursor, Claude Code, or Codex, your coding agent now has NeMo skills. Ask it to:

- "Help me set up NeMo" or "spin up a local platform" — invokes the `nemo-setup` skill, which covers `make bootstrap`, plugin install, `nemo services run`, the local data dir (`NMP_DATA_DIR` / `XDG_DATA_HOME`), and DB reset
- "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`

### 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 platform services |
| `--install-skills` / `--no-install-skills` | prompt (interactive) or skip (auto) | Install NeMo skills for detected coding agents |
| `--deploy-agent` / `--no-deploy-agent` | prompt (interactive) or skip (auto) | Deploy the built-in NeMo agent |

Override the default model with `NEMO_DEFAULT_MODEL`:

```bash
export OPENAI_API_KEY=sk-...
export NEMO_DEFAULT_MODEL=default/openai-gpt-4.1
nemo setup --auto --start-services
```

### Examples

```bash
# Full automation: services, skills, and agent
export NVIDIA_API_KEY=nvapi-...
nemo setup --auto --start-services --install-skills --deploy-agent

# Provider only (platform already running)
export OPENAI_API_KEY=sk-...
nemo setup --auto

# Skip skills and agent
nemo setup --no-install-skills --no-deploy-agent
```

## What to explore next

| Goal | Command or link |
|------|-----------------|
| Chat with a model | `nemo chat <model-name>` |
| List available models | `nemo models list` |
| Open the Studio UI | [http://localhost:8080](http://localhost:8080) |
| Browse docs from the CLI | `nemo docs --list` |
| Evaluate a model | [Run LLM-as-a-Judge Evaluation](../evaluator/tutorials/run-llm-judge-evaluation.md) |
| Generate synthetic data | [Data Designer Tutorials](../data-designer/tutorials/index.md) |
| Optimize an agent | [Optimize Agents](../agents/optimization.md) |

## Python SDK

The `nemo-platform` package includes a Python SDK. After running `nemo setup`, the simplest initialization uses your CLI context:

```python
from nemo_platform import NeMoPlatform

client = NeMoPlatform()
```

For scripts or CI where you want explicit control:

```python
import os
from nemo_platform import NeMoPlatform

client = NeMoPlatform(
    base_url=os.environ.get("NMP_BASE_URL", "http://localhost:8080"),
    workspace="default",
)
```

An asynchronous client is also available. See the [SDK reference](../pysdk/index.md) for details.

## CLI and SDK initialization

The CLI and SDK each support several ways to specify the platform URL and workspace.

### CLI initialization

The CLI reads connection settings from `~/.config/nmp/config.yaml`.

**1. After `nemo setup` (default)**

`nemo setup` configures the CLI automatically. All commands use `http://localhost:8080` and the `default` workspace:

```bash
nemo models list
```

**2. Explicit local URL and workspace**

```bash
nemo config set --base-url http://localhost:8080 --workspace default
nemo models list
```

Override URL and workspace for a single command without changing the config. Replace `default` with another workspace name as needed:

```bash
nemo --base-url http://localhost:8080 models list --workspace default
```

### SDK initialization options

| Parameter | Description |
|-----------|-------------|
| `base_url` | URL of the {{platform_name}} deployment |
| `workspace` | Workspace to operate in |

**1. From CLI context (simplest after `nemo setup`)**

```python
from nemo_platform import NeMoPlatform

client = NeMoPlatform()
```

**2. Explicit URL and workspace**

```python
import os
from nemo_platform import NeMoPlatform

client = NeMoPlatform(
    base_url=os.environ.get("NMP_BASE_URL", "http://localhost:8080"),
    workspace="default",
)
```

### Documentation convention

Code examples in this documentation use:

```python
import os
from nemo_platform import NeMoPlatform

client = NeMoPlatform(
    base_url=os.environ.get("NMP_BASE_URL", "http://localhost:8080"),
    workspace="default",
)
```

- **`NMP_BASE_URL`** — Set this environment variable to point to your deployment. If not set, `http://localhost:8080` is used.
- **`workspace="default"`** — Examples use the `default` workspace. Replace with your own as needed.

#### Variable naming

When examples need both the platform SDK and an OpenAI-compatible client, the OpenAI client is named `oai_client` to avoid shadowing `client`:

```python
client = NeMoPlatform(...)
oai_client = client.models.get_openai_client()
```

## Troubleshooting

### Platform won't start

Check `.nemo-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 Node.js with pnpm using `pnpm env use --global 22.18.0`, then rerun `make bootstrap-studio` 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 separately:

```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
curl -s http://localhost:8080/health/ready   # check if running
cat .nemo-services.log                 # view service output
pkill -f "nemo services run"           # stop all services
```
