Run Mini-SWE-Agent | NVIDIA 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, permission to create resources in default, and NVIDIA_API_KEY for the example’s NVIDIA Build model. See Setup first.

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:

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 selects the same extra for a Mini-SWE container image.

Save the shipped 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:

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:

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:

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. For missing traces, see gateway routing. 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:

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.