> 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.3: https://docs.nvidia.com/nemo-helix/v0.7.3/llms.txt
> - 0.7.2: https://docs.nvidia.com/nemo-helix/v0.7.2/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.

# Troubleshooting

> **Warning**
>
> Agent Governance is released with *early access* availability and is subject to limited support and potential API changes in future releases.

Start with `nemo agent-hardener doctor`. It is read-only and checks the five host
prerequisites: the agent-hardener virtual environment, the garak virtual
environment, the inference credential, the Docker daemon and the OpenShell
gateway.

## Setup

**`openshell status` reports "connection refused" or "no compute driver" on macOS.**
The gateway is running but has no driver. Point OpenShell at Docker:

```bash
DOCKER_SOCK=$(docker context inspect --format '{{.Endpoints.docker.Host}}')
brew services stop openshell
launchctl setenv OPENSHELL_DRIVERS docker
launchctl setenv DOCKER_HOST "$DOCKER_SOCK"
brew services restart openshell
openshell status
```

Then re-run `nemo agent-hardener setup` to re-register the `auto-defender` gateway.

**The OpenShell CLI is present but a war-game says the gateway is missing.**
Installing OpenShell as a standalone CLI tool gives you the command without the
gateway service. Use the native installer instead.

## Runs

**A run fails immediately with `smart-benign validation requires an explicit benign suite`.**
`nemo agent-hardener run` consumes a benign suite and never generates one. Create it
first:

```bash
nemo agent-hardener synth-benign --manifest-id <name>
```

The suite is cached on the manifest and reused by later runs.

**A run reports success but the agent's tools were never exercised.**
The sandbox drops outbound traffic that the manifest does not allow-list. When a
tool call is dropped, the model usually answers from its own knowledge, so the
run looks clean. Add the hosts and re-create the manifest:

```bash
nemo agent-hardener init --agent <name> --egress <host>
```

A bare host opens port 443 only. Write `host:80` for plain HTTP. Hosts cannot be
discovered automatically for an agent whose tool code lives in an installed
package.

**A run does not reflect a change made to the agent.**
Runs target a frozen manifest, so editing the agent does not change an existing
one. Pick up the change deliberately:

```bash
nemo agent-hardener refresh --manifest-id <name>
```

In Studio, use **Refresh Target**. A run logs a warning when the agent is newer
than its manifest.

**The agent cannot reach a service on the host.**
Declare it when you create the manifest with `--backend NAME:PORT[,PORT]`. The
sandbox reaches it through `host.docker.internal`, not `localhost`.

**A run fails in seconds with `model_unavailable`.**
Every model group you set explicitly — `--attack-model`, `--analysis-model` and
`--safety-model`, together with their `--*-base-url` and `--*-key-secret` — is
probed against its endpoint before the sandbox is built, so a wrong model name or
key fails immediately rather than minutes in. The error lists the models the
credentials can actually reach; pick one of those. Built-in defaults are not
probed.

**The guardrails defender runs but proposes no change.**
An unreachable safety model does not raise: the guardrail fails open, which
reads as "ran, proposed nothing". Preflight catches this whenever `--safety-model`
or `--safety-base-url` is set explicitly, so check that first if you left them at
their defaults. Unset safety fields fall back to the analysis endpoint and key.

## The Victim Sandbox

**`Missing required secrets: <NAME>`.**
The agent config references `${<NAME>}` and nothing supplies it. Required secrets
are derived from the agent's stored config, so this means the variable was unset
when the agent was registered. Export it and re-run `nemo agents create`, or
supply it with `--env-file` or `--secrets NAME=workspace/secret`.

**A run fails with `could not read secret <workspace>/<name>`.**
The manifest maps a secret to a Secrets-store entry the run cannot read, or that
is empty. Check it with `nemo secrets list --workspace <workspace>`. For a
deployed agent, the mapping comes from its running deployment; `refresh` the
manifest after changing it.

**A model call fails with `401` although the key in `~/.agent-hardener/.env` works.**
The environment of the shell that started the platform wins over that file, and
the run logs `the platform environment overrides <NAME>`. Unset the variable
there, or remove its export from your shell profile, and restart the platform.

**The victim never becomes healthy, and its log shows a pydantic `union_tag_invalid` for a `_type`.**
The agent references a component the scaffolded victim cannot resolve. The victim
installs a minimal dependency set, not the platform's full plugin list. Platform
telemetry is stripped automatically; anything else means the agent needs a real
project, so pass `--project-dir` to `init` and let the project's own
dependencies supply it.

**The victim is healthy but every request returns 422 with `Invalid model`.**
The workflow's `model_name` is not a model entity the platform knows. Entity names
are lowercase letters, digits and hyphens, so a provider id containing a slash is
rejected. Check `nemo models list`, then re-register the agent with that exact
name. The value is resolved when the agent is registered, so it must be correct
at `nemo agents create` time.

## Studio

**Agent Hardening is missing from the Studio side nav.**
The UI ships with the plugin, so a missing entry means Studio did not load its
bundle. Confirm the plugin is registered and the bundle is served:

```bash
curl -s "${NHX_BASE_URL:-http://localhost:8080}/apis/plugins"
curl -s -o /dev/null -w "%{http_code}\n" "${NHX_BASE_URL:-http://localhost:8080}/plugin-ui/agent-hardener/index.js"
```

If your CLI context points at a remote deployment, export its URL as `NHX_BASE_URL` before running
these commands. For details, refer to [When to use `NHX_BASE_URL`](/documentation/reference/cli-reference/connect-to-deployments#when-to-use-nhx-base-url).

The first should list `agent-hardener` with a `bundleUrl`, and the second should print `200`. Then
hard-reload the browser.

**Applied guardrails have no effect on the running agent.**
Applying updates the stored agent config without redeploying. Redeploy the agent
for the guardrails to take effect.