> This page is for version 0.9.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo-helix/latest/llms.txt
> - 0.9: https://docs.nvidia.com/nemo-helix/v0.9/llms.txt
> - 0.8: https://docs.nvidia.com/nemo-helix/v0.8/llms.txt
> - 0.7: https://docs.nvidia.com/nemo-helix/v0.7/llms.txt
> - 0.6: https://docs.nvidia.com/nemo-helix/v0.6/llms.txt
> - 0.5: https://docs.nvidia.com/nemo-helix/v0.5/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.

# Run Mini-SWE-Agent

> Install, deploy and use Mini-SWE-Agent 2.x with NeMo Helix.

Mini-SWE-Agent 2.x runs shell tasks through `nvidia.fabric.mini-swe-agent`.
This example needs a running Helix 0.9 platform, a configured
[CLI context](/nemo-helix/v0.9/documentation/reference/cli-reference/connect-to-deployments),
permission to create resources in `default`, and `NVIDIA_API_KEY` for the
example's NVIDIA Build model. See [Setup](/nemo-helix/v0.9/documentation/get-started/setup) first.

> **Warning**
>
> A subprocess agent executes shell commands with the platform process's
> permissions. Use a disposable workspace and trusted tasks; this is not a sandbox.

## Install and configure

Install the optional harness on the **platform host**, not just the CLI machine,
and restart the platform if its environment changed. For the standard published
installation:

```bash
uv tool install --reinstall "nemo-helix[all,nemo-agents-plugin-mini-swe-agent]==0.9.0"
```

Preserve your existing extras if you use a custom installation instead of `all`.
From a checkout, use `uv sync --frozen --package nemo-agents-plugin --extra mini-swe-agent`.
[Agent packaging](/nemo-helix/v0.9/documentation/agents/deploy-agents#build-and-publish-agent-images)
selects the same extra for a Mini-SWE container image.

Save the shipped
[`agent-mini-swe-agent.yaml`](https://github.com/NVIDIA-NeMo/nemo-helix/blob/release/0.9/plugins/nemo-agents/examples/nemo-agent-config/agent-mini-swe-agent.yaml)
as `mini-swe-demo/agent.yaml` in a new directory, so registration does not upload
unrelated files. It uses a direct NVIDIA endpoint and disables ordinary
telemetry export; credentials are bound below, not embedded in YAML.

## Register, deploy and invoke

With `NVIDIA_API_KEY` set in your shell, create uniquely named example resources:

```bash
printf '%s' "$NVIDIA_API_KEY" | nemo secrets create mini-swe-model-key --from-file - --workspace default
nemo agents environment-specs create mini-swe-env --workspace default \
  --spec '{"secrets":{"NVIDIA_API_KEY":"default/mini-swe-model-key"}}'
nemo agents environments create mini-swe-env --workspace default \
  --environment-spec default/mini-swe-env
nemo agents register --name mini-swe-demo --workspace default \
  --agent-config ./mini-swe-demo/agent.yaml
nemo agents deploy --agent mini-swe-demo --name mini-swe-demo-deployment \
  --mode subprocess --environment default/mini-swe-env --workspace default
nemo agents deployments get mini-swe-demo-deployment --workspace default
```

Wait until the deployment is ready, then invoke it:

```bash
nemo agents invoke --agent-deployment mini-swe-demo-deployment --workspace default \
  --input "Use the shell to print hello, then finish with hello as your final answer."
```

Check terminal status `succeeded` and text `response`, not an exact live-model
answer. Helix preserves structured `output`; when it lacks `response` but has
a string `output`, that string becomes the normalized response, including any
trailing newline. Output text alone does not make an error result successful.

## Sessions and telemetry

In an **interactive terminal**, start a conversation, then detach and resume:

```bash
nemo agents chat --agent-deployment mini-swe-demo-deployment --workspace default \
  --session-name mini-swe-demo-session --input "Inspect the workspace and remember what you find."
# After leaving the chat:
nemo agents chat --session mini-swe-demo-session --workspace default
```

Session turns reuse runtime/history; independent one-shot invocations do not.
Resuming does not redisplay prior messages. Closing a session releases its
runtime; a persisted record does not reconstruct it after a host restart.
Use `invoke` for scripts: `chat` requires an interactive terminal.

Helix enables serving-owned Relay for sessions/streaming even with the example's
ordinary export disabled. Correlate stream metadata `nemo_fabric_request_id`
with the terminal result's `request_id`; each turn has its own ID. Use the
terminal result for success, not the first scope event. This is not a guarantee
of token-by-token model streaming or complete per-tool-result telemetry.

To export ordinary trajectories to Intake, remove the example's telemetry
opt-out and follow [Collect Agent Traces](/nemo-helix/v0.9/documentation/agents/traces-and-insights/collect-agent-traces).
For missing traces, see [gateway routing](/nemo-helix/v0.9/documentation/agents/fabric-upgrade#telemetry-routing-through-gateways).
The optional-harness integration gate uses a local model stub; validate your
own credentials, deployment network and collector separately.

## Limits and troubleshooting

| Setting or symptom                              | Scope or action                                                                 |
| ----------------------------------------------- | ------------------------------------------------------------------------------- |
| `harnesses.mini-swe-agent.settings.timeout`     | Per-shell-command timeout; example: 30 seconds.                                 |
| `runtime.timeout_seconds` / `runtime.max_turns` | Invocation limit / turn budget; example: 1800 seconds / 50 turns.               |
| CLI `invoke` / `chat` `--timeout`               | Client wait, independent of the shell limit.                                    |
| Missing runtime                                 | Install the harness on the platform host or selected-harness image.             |
| Model authentication error                      | Check secret access, `api_key_env` and endpoint/model; never log the key.       |
| Missing history or traces                       | Check session identity and telemetry export separately from invocation success. |

The adapter supports **replacement** system instructions, not appended
instructions, skills, MCP servers or tool policy. A replacement prompt must
still let the harness finish the task.

## Cleanup

Close the session before removing the deployment; skip that command if you only
used one-shot invocation:

```bash
nemo agents sessions close mini-swe-demo-session --workspace default
nemo agents undeploy --agent mini-swe-demo --workspace default
nemo agents delete mini-swe-demo --workspace default
nemo agents environments delete mini-swe-env --workspace default
nemo agents environment-specs delete mini-swe-env --workspace default
nemo secrets delete mini-swe-model-key --workspace default
```

Inspect any retained agent filesets before deleting them; they may be shared.