From 7538a0841b3a07116f03cd9652ba4db6f5ba62e0 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Thu, 4 Jun 2026 14:30:24 -0700 Subject: [PATCH 1/2] chore: refresh user reference skill --- skills/nemoclaw-user-reference/SKILL.md | 13 +- .../nemoclaw-user-reference/evals/evals.json | 89 +- .../references/architecture.md | 78 +- .../references/cli-selection-guide.md | 126 +-- .../references/commands.md | 980 ++++++++++++++---- .../references/network-policies.md | 25 +- .../references/troubleshooting.md | 544 ++++++---- 7 files changed, 1228 insertions(+), 627 deletions(-) diff --git a/skills/nemoclaw-user-reference/SKILL.md b/skills/nemoclaw-user-reference/SKILL.md index 020f52f5df4..25cb810e52c 100644 --- a/skills/nemoclaw-user-reference/SKILL.md +++ b/skills/nemoclaw-user-reference/SKILL.md @@ -1,18 +1,15 @@ --- name: "nemoclaw-user-reference" -description: "Describes the NemoClaw plugin and blueprint architecture and how they orchestrate the OpenClaw sandbox. Use when looking up architecture, plugin structure, or blueprint design. Trigger keywords - nemoclaw architecture, nemoclaw plugin blueprint structure, nemoclaw vs openshell, which cli, nemoclaw cli, openshell cli, sandbox commands, nemoclaw cli commands, nemoclaw command reference, nemoclaw network policy, sandbox egress control operator approval, nemoclaw troubleshooting, nemoclaw debug sandbox issues." +description: "Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. Use when looking up architecture, agent integration, plugin structure, or blueprint design. Trigger keywords - nemoclaw architecture, nemoclaw agent architecture, nemoclaw plugin blueprint structure, nemoclaw vs openshell, which cli, nemoclaw cli, openshell cli, sandbox commands, nemoclaw cli commands, nemoclaw command reference, nemoclaw network policy, sandbox egress control operator approval, nemoclaw troubleshooting, nemoclaw debug sandbox issues." license: "Apache-2.0" --- - - - -# Architecture Details +# NemoClaw User Reference ## References -- **Load [references/architecture.md](references/architecture.md)** when looking up architecture, plugin structure, or blueprint design. Describes the NemoClaw plugin and blueprint architecture and how they orchestrate the OpenClaw sandbox. -- **[references/cli-selection-guide.md](references/cli-selection-guide.md)** — Explains when to use `nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations. -- **Load [references/commands.md](references/commands.md)** when looking up a specific `nemoclaw` or `/nemoclaw` subcommand, flag, argument, or exit code. Includes the full CLI reference for slash commands and standalone NemoClaw commands. +- **Load [references/architecture.md](references/architecture.md)** when looking up architecture, agent integration, plugin structure, or blueprint design. Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. +- **[references/cli-selection-guide.md](references/cli-selection-guide.md)** — Explains when to use `$$nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations. +- **Load [references/commands.md](references/commands.md)** when looking up a specific `$$nemoclaw`, `nemohermes`, or `/nemoclaw` subcommand, flag, argument, or exit code. Includes the full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands. - **Load [references/network-policies.md](references/network-policies.md)** when looking up a specific default endpoint, filesystem path, or the runtime approval sequence NemoClaw applies on blocked requests. Covers the baseline network policy, filesystem rules, and operator approval flow. - **Load [references/troubleshooting.md](references/troubleshooting.md)** when diagnosing a reported NemoClaw error, a failed onboard, or unexpected sandbox behavior. Lists fixes for common installation, onboarding, and runtime issues. diff --git a/skills/nemoclaw-user-reference/evals/evals.json b/skills/nemoclaw-user-reference/evals/evals.json index d303e6d5cd9..b7d114b0976 100644 --- a/skills/nemoclaw-user-reference/evals/evals.json +++ b/skills/nemoclaw-user-reference/evals/evals.json @@ -3,90 +3,9 @@ "id": "docs-reference-architecture-001", "question": "I'm using the architecture reference. Help me verify implementation and operations details so I can make changes or debug behavior from the right mental model.", "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user verify implementation and operations details and gives enough concrete guidance, decision criteria, verification steps, or risk framing to make changes or debug behavior from the right mental model." - }, - { - "id": "docs-reference-architecture-002", - "question": "I'm locating the right layer for a change. Help me connect structure, lifecycle, and ownership so I can edit the plugin, blueprint, or sandbox layer intentionally.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user connect structure, lifecycle, and ownership and gives enough concrete guidance, decision criteria, verification steps, or risk framing to edit the plugin, blueprint, or sandbox layer intentionally." - }, - { - "id": "docs-reference-architecture-003", - "question": "I'm modifying architecture-sensitive files. Help me understand the invariants that must remain true so I can avoid breaking sandbox creation or operation.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user understand the invariants that must remain true and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid breaking sandbox creation or operation." - }, - { - "id": "docs-reference-cli-selection-guide-001", - "question": "I'm choosing between `nemoclaw` and `openshell`. Help me pick the command surface that owns my operation so I can complete the task without breaking NemoClaw management.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user pick the command surface that owns my operation and gives enough concrete guidance, decision criteria, verification steps, or risk framing to complete the task without breaking NemoClaw management." - }, - { - "id": "docs-reference-cli-selection-guide-002", - "question": "I'm tempted to run a low-level OpenShell command. Help me understand when it bypasses NemoClaw lifecycle expectations so I can avoid unsupported or confusing states.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user understand when it bypasses NemoClaw lifecycle expectations and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid unsupported or confusing states." - }, - { - "id": "docs-reference-cli-selection-guide-003", - "question": "I'm doing onboarding, policy, debugging, or low-level sandbox work. Help me apply a simple CLI selection rule so I can move quickly without memorizing every command boundary.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user apply a simple CLI selection rule and gives enough concrete guidance, decision criteria, verification steps, or risk framing to move quickly without memorizing every command boundary." - }, - { - "id": "docs-reference-commands-001", - "question": "I'm opening the CLI command reference. Help me find the exact action, flag, or recovery path I need so I can run the right command without scanning source code.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user find the exact action, flag, or recovery path I need and gives enough concrete guidance, decision criteria, verification steps, or risk framing to run the right command without scanning source code." - }, - { - "id": "docs-reference-commands-002", - "question": "I'm choosing among setup, lifecycle, policy, inference, and diagnostic commands. Help me see command groups and examples clearly so I can locate the right command faster.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user see command groups and examples clearly and gives enough concrete guidance, decision criteria, verification steps, or risk framing to locate the right command faster." - }, - { - "id": "docs-reference-commands-003", - "question": "I'm using `nemoclaw` in scripts or CI. Help me understand example output and exit behavior so I can automate safely and handle failures correctly.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user understand example output and exit behavior and gives enough concrete guidance, decision criteria, verification steps, or risk framing to automate safely and handle failures correctly." - }, - { - "id": "docs-reference-network-policies-001", - "question": "I'm reading the network policy reference. Help me understand baseline access decisions so I can assess the sandbox's default exposure.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user understand baseline access decisions and gives enough concrete guidance, decision criteria, verification steps, or risk framing to assess the sandbox's default exposure." - }, - { - "id": "docs-reference-network-policies-002", - "question": "I'm reviewing default rules and filesystem constraints. Help me know what is allowed before any customization so I can decide what needs to change for my environment.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user know what is allowed before any customization and gives enough concrete guidance, decision criteria, verification steps, or risk framing to decide what needs to change for my environment." - }, - { - "id": "docs-reference-network-policies-003", - "question": "I'm tracing a denied request. Help me understand how operator approval turns into policy so I can audit and reason about egress changes.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user understand how operator approval turns into policy and gives enough concrete guidance, decision criteria, verification steps, or risk framing to audit and reason about egress changes." - }, - { - "id": "docs-reference-troubleshooting-001", - "question": "I'm troubleshooting a NemoClaw problem. Help me map my symptom to the fastest safe recovery step so I can get unstuck without making the environment worse.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user map my symptom to the fastest safe recovery step and gives enough concrete guidance, decision criteria, verification steps, or risk framing to get unstuck without making the environment worse." - }, - { - "id": "docs-reference-troubleshooting-002", - "question": "I'm uncertain which subsystem failed. Help me run diagnostics that separate install, onboarding, runtime, policy, and inference issues so I can focus on the likely cause.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user run diagnostics that separate install, onboarding, runtime, policy, and inference issues and gives enough concrete guidance, decision criteria, verification steps, or risk framing to focus on the likely cause." - }, - { - "id": "docs-reference-troubleshooting-003", - "question": "I'm asking the community or filing an issue. Help me collect the right logs, versions, and error details so I can give maintainers enough information to help.", - "expected_skill": "nemoclaw-user-reference", - "ground_truth": "A NemoClaw-specific answer that helps the user collect the right logs, versions, and error details and gives enough concrete guidance, decision criteria, verification steps, or risk framing to give maintainers enough information to help." + "ground_truth": "A NemoClaw-specific answer that helps the user verify implementation and operations details and gives enough concrete guidance, decision criteria, verification steps, or risk framing to make changes or debug behavior from the right mental model.", + "expected_behavior": [ + "Uses the expected_skill and does not make up answers if it cannot find the answer from the skill." + ] } ] diff --git a/skills/nemoclaw-user-reference/references/architecture.md b/skills/nemoclaw-user-reference/references/architecture.md index 07e193434aa..07bbfc2ba9f 100644 --- a/skills/nemoclaw-user-reference/references/architecture.md +++ b/skills/nemoclaw-user-reference/references/architecture.md @@ -1,12 +1,10 @@ - - # Architecture Details -NemoClaw combines a host CLI, a TypeScript plugin that runs with OpenClaw inside the sandbox, and a versioned YAML blueprint that defines the sandbox image, policies, and inference profiles applied through OpenShell. +NemoClaw combines a host CLI, an in-sandbox integration layer, and a versioned YAML blueprint that defines the sandbox image, policies, and inference profiles applied through OpenShell. ## System Overview -NVIDIA OpenShell is a general-purpose agent runtime. It provides sandbox containers, a credential-storing gateway, inference proxying, and policy enforcement, but has no opinions about what runs inside. NemoClaw is an opinionated reference stack built on OpenShell that handles what goes in the sandbox and makes the setup accessible. +NVIDIA OpenShell is a general-purpose agent runtime. It provides sandbox containers, a credential-storing gateway, inference proxying, and policy enforcement, but has no opinions about what runs inside. NemoClaw is an opinionated reference stack built on OpenShell that handles what goes in the sandbox, prepares agent-specific integration, and makes the setup accessible. ```mermaid graph LR @@ -42,8 +40,8 @@ graph LR subgraph SANDBOX["Sandbox Container 🔒"] direction TB - AGENT["Agent
OpenClaw or any
compatible agent"]:::agent - PLUG["NemoClaw Plugin
Extends agent with
managed configuration"]:::sandbox + AGENT["Compatible Agent
OpenClaw, Hermes,
or another supported runtime"]:::agent + PLUG["NemoClaw Integration
Managed configuration
and runtime context"]:::sandbox end end end @@ -91,7 +89,7 @@ graph TB subgraph DOCKER["Docker daemon"] direction TB - SANDBOX["Sandbox container 🔒
Landlock + seccomp + netns
OpenClaw agent + NemoClaw plugin"]:::sandbox + SANDBOX["Sandbox container 🔒
Landlock + seccomp + netns
Compatible agent + NemoClaw integration"]:::sandbox end end @@ -115,44 +113,33 @@ Layering from top to bottom: | Host CLI | Host process (`nemoclaw` on Node.js) | Orchestrates OpenShell via `openshell` CLI calls. | | OpenShell gateway | Host process by default; optional Linux compatibility container when the gateway binary needs a newer host ABI | Hosts the credential store, owns sandbox lifecycle coordination, and provides the L7 proxy. | | Docker daemon | Host service | Runs the Docker-driver sandbox container and, on affected Linux hosts, the optional gateway compatibility container. | -| Sandbox container | Docker container | Runs the OpenClaw agent and the NemoClaw plugin under Landlock + seccomp + netns. | +| Sandbox container | Docker container | Runs the selected compatible agent and NemoClaw integration under Landlock + seccomp + netns. | | OpenShell L7 proxy | Gateway process | Intercepts agent egress and rewrites `Authorization` headers (Bearer/Bot) and URL-path segments to inject the real credential at the network boundary. | NemoClaw never gives the sandbox a raw provider key. At onboard time it registers credentials with OpenShell's provider/placeholder system, and the L7 proxy substitutes the real value into outbound requests at egress. -The CLI helper `isInferenceRouteReady` (in `src/lib/onboard.ts`) is a host-side readiness check used by the resume flow to decide whether the active route already covers the chosen provider and model — it is not a runtime component. +The CLI helper `isInferenceRouteReady` (in `src/lib/onboard.ts`) is a host-side readiness check used by the resume flow to decide whether the active route already covers the chosen provider and model. +It is not a runtime component. For the DGX Spark-specific variant of this topology (cgroup v2, aarch64, unified memory), refer to the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw). -## NemoClaw Plugin +## NemoClaw Agent Integration -The plugin is a thin TypeScript package that registers an inference provider and the `/nemoclaw` slash command. -It runs in-process with the OpenClaw gateway inside the sandbox. -It also registers runtime hooks that keep the agent aware of its environment. -Before an agent turn starts, the plugin prepends a short context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. +NemoClaw integrates with each supported agent through a runtime layer that adapts the agent to OpenShell-managed providers, policies, and sandbox state. +The concrete files differ by agent because each runtime has its own plugin system, config format, state layout, and startup command. + +| Agent | Integration files | Runtime behavior | +|---|---|---| +| OpenClaw | `nemoclaw/openclaw.plugin.json`, `nemoclaw/src/runtime-context.ts`, and the TypeScript package under `nemoclaw/src/` | Registers the `/nemoclaw` slash command, adds the NemoClaw inference provider, and injects sandbox and policy context into OpenClaw turns. | +| Hermes | `agents/hermes/manifest.yaml`, `agents/hermes/plugin/plugin.yaml`, `agents/hermes/generate-config.ts`, `agents/hermes/config/`, and `agents/hermes/start.sh` | Declares the Hermes agent contract, installs the NemoClaw Hermes plugin, writes `/sandbox/.hermes/config.yaml` and `/sandbox/.hermes/.env`, and launches `hermes gateway run` behind the OpenShell proxy. | + +The OpenClaw integration is a thin TypeScript plugin that runs in-process with the OpenClaw gateway inside the sandbox. +Before an OpenClaw turn starts, the plugin prepends a short context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. When the policy or phase changes during a session, the plugin sends a smaller update block instead of repeating the full context. -```text -nemoclaw/ -├── src/ -│ ├── index.ts Plugin entry: registers all commands -│ ├── cli.ts Commander.js subcommand wiring -│ ├── runtime-context.ts Sandbox and policy context injection -│ ├── commands/ -│ │ ├── launch.ts Fresh install into OpenShell -│ │ ├── connect.ts Interactive shell into sandbox -│ │ ├── status.ts Blueprint run state + sandbox health -│ │ ├── logs.ts Stream blueprint and sandbox logs -│ │ └── slash.ts /nemoclaw chat command handler -│ └── blueprint/ -│ ├── resolve.ts Version resolution, cache management -│ ├── fetch.ts Download blueprint from OCI registry -│ ├── verify.ts Digest verification, compatibility checks -│ ├── exec.ts Subprocess execution of blueprint runner -│ └── state.ts Persistent state (run IDs) -├── openclaw.plugin.json Plugin manifest -└── package.json Commands declared under openclaw.extensions -``` +The Hermes integration follows the generic agent-manifest path instead of the OpenClaw plugin package path. +The manifest declares Hermes' binary, health probe, config directory, state directories, messaging support, and OpenAI-compatible API endpoint. +The build-time config generator turns NemoClaw onboarding choices into Hermes YAML and environment files, and the Hermes plugin manifest exposes NemoClaw tools and an `on_session_start` hook. ## NemoClaw Blueprint @@ -166,10 +153,13 @@ nemoclaw-blueprint/ ├── model-specific-setup/ Agent-scoped model/provider compatibility manifests ├── router/ Model Router config and routing engine ├── policies/ -│ └── openclaw-sandbox.yaml Default network + filesystem policy +│ └── openclaw-sandbox.yaml Default network + filesystem policy for the OpenClaw profile ``` -The blueprint runtime (TypeScript) lives in the plugin source tree: +Hermes keeps its agent-owned image, plugin, config, entrypoint, and policy additions under `agents/hermes/`. +The default Hermes policy starts from `agents/hermes/policy-additions.yaml`. + +The current blueprint runner implementation lives in the `nemoclaw/` TypeScript package: ```text nemoclaw/src/blueprint/ @@ -189,8 +179,8 @@ flowchart LR D --> E[status] ``` -1. Resolve. The plugin locates the blueprint artifact and checks the version against `min_openshell_version` and `min_openclaw_version` constraints in `blueprint.yaml`. -2. Verify. The plugin checks the artifact digest against the expected value. +1. Resolve. The integration layer locates the blueprint artifact and checks the version against the OpenShell and agent runtime constraints in `blueprint.yaml`. +2. Verify. The integration layer checks the artifact digest against the expected value. 3. Plan. The runner determines what OpenShell resources to create or update, such as the gateway, providers, sandbox, inference route, and policy. 4. Apply. The runner executes the plan by calling `openshell` CLI commands. 5. Status. The runner reports current state. @@ -203,11 +193,11 @@ base image and layers the NemoClaw runtime Dockerfile on top. The direct bluepri runner still carries a pinned OpenShell Community OpenClaw image for legacy `openshell sandbox create --from` compatibility. Inside the sandbox: -- OpenClaw runs with the NemoClaw plugin pre-installed. +- The selected compatible agent runs with the NemoClaw integration layer installed or generated for that agent. - Inference calls are routed through OpenShell to the configured provider. -- Network egress is restricted by the baseline policy in `openclaw-sandbox.yaml`. +- Network egress is restricted by the baseline policy for the selected agent profile. - Filesystem access is confined to `/sandbox` and `/tmp` for read-write access, with system paths read-only. -- The NemoClaw plugin injects sandbox and policy context into agent turns so the agent can report policy blocks accurately. +- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can report policy blocks accurately. - The image exposes a Docker health check that probes the in-sandbox gateway, so container runtimes can report whether the agent service is responding. - The image includes common runtime compatibility helpers such as Homebrew and a `python` to `python3` symlink for tools that still invoke `python`. @@ -217,14 +207,14 @@ Inference requests from the agent never leave the sandbox directly. OpenShell intercepts them and routes to the configured provider: ```text -Agent (sandbox) ──▶ OpenShell gateway ──▶ NVIDIA Endpoint (build.nvidia.com) +Compatible agent (sandbox) ──▶ OpenShell gateway ──▶ Provider endpoint ``` When you select the Model Router provider, the OpenShell gateway routes to a host-side router process instead of a single upstream model. The router selects from the configured pool, then calls the upstream NVIDIA endpoint with the credential held outside the sandbox. Some model and provider combinations need agent-specific compatibility setup. -NemoClaw keeps those declarations under `nemoclaw-blueprint/model-specific-setup//` so OpenClaw and Hermes fixes can be tested and reviewed independently. +NemoClaw keeps those declarations under `nemoclaw-blueprint/model-specific-setup//` so fixes for each supported agent can be tested and reviewed independently. Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill) for provider configuration details. diff --git a/skills/nemoclaw-user-reference/references/cli-selection-guide.md b/skills/nemoclaw-user-reference/references/cli-selection-guide.md index 0be1cf3147a..3614b9fafce 100644 --- a/skills/nemoclaw-user-reference/references/cli-selection-guide.md +++ b/skills/nemoclaw-user-reference/references/cli-selection-guide.md @@ -1,6 +1,4 @@ - - -# CLI Selection Guide +# Choose Between NemoClaw and OpenShell CLIs NemoClaw uses two host-side CLIs. Use `nemoclaw` for NemoClaw-managed workflows. @@ -21,52 +19,52 @@ Use `nemoclaw` for operations where NemoClaw adds product-specific state, safety - Install, onboard, or recreate a NemoClaw sandbox: - ```console - $ nemoclaw onboard - $ nemoclaw onboard --resume --recreate-sandbox + ```bash + nemoclaw onboard + nemoclaw onboard --resume --recreate-sandbox ``` - List, connect to, check, or delete NemoClaw-managed sandboxes: - ```console - $ nemoclaw list - $ nemoclaw my-assistant connect - $ nemoclaw my-assistant status - $ nemoclaw my-assistant logs --follow - $ nemoclaw my-assistant destroy + ```bash + nemoclaw list + nemoclaw my-assistant connect + nemoclaw my-assistant status + nemoclaw my-assistant logs --follow + nemoclaw my-assistant destroy ``` - Rebuild or upgrade while preserving workspace state: - ```console - $ nemoclaw my-assistant rebuild - $ nemoclaw upgrade-sandboxes --check + ```bash + nemoclaw my-assistant rebuild + nemoclaw upgrade-sandboxes --check ``` - Snapshot, restore, or mount sandbox state: - ```console - $ nemoclaw my-assistant snapshot create --name before-change - $ nemoclaw my-assistant snapshot restore before-change - $ nemoclaw my-assistant share mount + ```bash + nemoclaw my-assistant snapshot create --name before-change + nemoclaw my-assistant snapshot restore before-change + nemoclaw my-assistant share mount ``` - Add or remove NemoClaw policy presets: - ```console - $ nemoclaw my-assistant policy-add pypi --yes - $ nemoclaw my-assistant policy-list - $ nemoclaw my-assistant policy-remove pypi --yes + ```bash + nemoclaw my-assistant policy-add pypi --yes + nemoclaw my-assistant policy-list + nemoclaw my-assistant policy-remove pypi --yes ``` - Manage NemoClaw messaging channels, credentials, diagnostics, and cleanup: - ```console - $ nemoclaw my-assistant channels add slack - $ nemoclaw credentials list - $ nemoclaw credentials reset nvidia-prod - $ nemoclaw debug --sandbox my-assistant - $ nemoclaw gc --dry-run + ```bash + nemoclaw my-assistant channels add slack + nemoclaw credentials list + nemoclaw credentials reset nvidia-prod + nemoclaw debug --sandbox my-assistant + nemoclaw gc --dry-run ``` ## Use `openshell` For OpenShell Operations @@ -75,40 +73,40 @@ Use `openshell` when the docs explicitly call for a live OpenShell gateway opera - Open the OpenShell TUI for network approvals and live activity: - ```console - $ openshell term + ```bash + openshell term ``` - Manage dashboard or service port forwards: - ```console - $ openshell forward start --background - $ openshell forward list + ```bash + openshell forward start --background + openshell forward list ``` - Inspect the underlying sandbox state: - ```console - $ openshell sandbox list - $ openshell sandbox get - $ openshell logs -n 20 - $ openshell doctor check + ```bash + openshell sandbox list + openshell sandbox get + openshell logs -n 20 + openshell doctor check ``` -- Run one-off commands or move files without starting a NemoClaw chat session: +- Move files, or run raw one-off commands when you intentionally want to bypass NemoClaw's sandbox registry and wrappers: - ```console - $ openshell sandbox exec -n -- ls -la /sandbox - $ openshell sandbox upload ./local-file /sandbox/ - $ openshell sandbox download /sandbox/output ./output + ```bash + openshell sandbox upload ./local-file /sandbox/ + openshell sandbox download /sandbox/output ./output + openshell sandbox exec -n -- env | grep '^HOME=' ``` - Inspect or replace raw OpenShell policy: - ```console - $ openshell policy get --full > live-policy.yaml - $ openshell policy update --add-endpoint api.example.com:443:read-only:rest:enforce - $ openshell policy set --policy live-policy.yaml + ```bash + openshell policy get --full > live-policy.yaml + openshell policy update --add-endpoint api.example.com:443:read-only:rest:enforce + openshell policy set --policy live-policy.yaml ``` `openshell policy update` merges specific endpoint and rule changes into the live sandbox policy. @@ -134,10 +132,18 @@ It waits for readiness, handles stale SSH host keys after gateway restarts, and Use `openshell sandbox connect ` only when you intentionally want the raw OpenShell connection path. -For a one-off command, use `openshell sandbox exec` instead of opening an interactive shell. +For a one-off command in a NemoClaw-managed sandbox, use `nemoclaw exec` instead of opening an interactive shell. +It resolves the sandbox by its NemoClaw registry name and runs through the standard NemoClaw CLI surface. +The command executes as the sandbox user with `HOME=/sandbox` inside the provisioned sandbox, where the agent configuration, inference routing, and policy state are already in place. -```console -$ openshell sandbox exec -n my-assistant -- cat /tmp/gateway.log +```bash +nemoclaw my-assistant exec -- cat /tmp/gateway.log +``` + +Use `openshell sandbox exec` for the raw OpenShell execution path, for example when addressing a sandbox by its gateway name or intentionally bypassing the NemoClaw CLI and registry. + +```bash +openshell sandbox exec -n my-assistant -- cat /tmp/gateway.log ``` ### Check Health or Logs @@ -159,27 +165,27 @@ Approved endpoints are session-scoped unless you also add them to the policy thr Use the NemoClaw commands for model or provider inspection and switches so the OpenShell route and the running agent config stay consistent: -```console -$ nemoclaw inference get -$ nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b +```bash +nemoclaw inference get +nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b ``` For Hermes sandboxes, use the alias; it updates the route and `/sandbox/.hermes/config.yaml` without a rebuild or restart: -```console -$ nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini +```bash +nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini ``` For a build-time agent setting change, rerun onboarding so the sandbox configuration is recreated consistently: -```console -$ nemoclaw onboard --resume --recreate-sandbox +```bash +nemoclaw onboard --resume --recreate-sandbox ``` Verify either path with: -```console -$ nemoclaw status +```bash +nemoclaw status ``` ### Update Network Policy diff --git a/skills/nemoclaw-user-reference/references/commands.md b/skills/nemoclaw-user-reference/references/commands.md index ad608672ea0..4a632f4f6ab 100644 --- a/skills/nemoclaw-user-reference/references/commands.md +++ b/skills/nemoclaw-user-reference/references/commands.md @@ -1,12 +1,50 @@ - - # NemoClaw CLI Commands Reference +import { AgentOnly } from "../_components/AgentGuide"; + + + The `nemoclaw` CLI is the primary interface for managing NemoClaw sandboxes. It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`). For guidance on when to use `nemoclaw` versus the underlying `openshell` CLI, see [CLI Selection Guide](cli-selection-guide.md). -## `/nemoclaw` Slash Command + + + +The `nemohermes` alias is the primary interface for managing Hermes sandboxes through NemoClaw. +It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes bash`). +Most commands in this reference use the same arguments and subcommands across agent variants. +Use `nemohermes` when you want Hermes selected by default. +For guidance on choosing between the agent CLIs and the underlying `openshell` CLI, see [CLI Selection Guide](cli-selection-guide.md). + + + +## Agent Selection + + + +Use `nemoclaw` for the OpenClaw variant. +OpenClaw is the default agent for `nemoclaw onboard` unless you pass `--agent hermes` or set `NEMOCLAW_AGENT=hermes`. +OpenClaw-specific sections below describe the `/nemoclaw` slash command, the OpenClaw dashboard URL, the OpenClaw gateway token, and OpenClaw config paths under `/sandbox/.openclaw`. + + + + +Use `nemohermes` for the Hermes variant. +It selects Hermes by default during onboarding and for other commands. +Use `--agent hermes` during onboarding or set `NEMOCLAW_AGENT=hermes` when you need the same selection through another entry point. +Hermes-specific sections below describe the OpenAI-compatible API endpoint, optional Hermes dashboard, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`. + +```bash +nemohermes onboard # selects Hermes by default +nemohermes my-sandbox connect # connects to a Hermes sandbox +``` + + + +## In-Sandbox Commands + + The `/nemoclaw` slash command is available inside the OpenClaw chat interface for quick actions: @@ -17,25 +55,34 @@ The `/nemoclaw` slash command is available inside the OpenClaw chat interface fo | `/nemoclaw onboard` | Show onboarding status and reconfiguration guidance | | `/nemoclaw eject` | Show rollback instructions for returning to the host installation | + + + +Hermes does not use the OpenClaw chat slash command. +Use the host-side `nemohermes` commands for lifecycle, status, policy, and inference operations. +The in-sandbox Hermes integration installs the NemoClaw Hermes plugin, which exposes tools for status, environment information, and skill reload support, plus an `on_session_start` hook. + + + ## Standalone Host Commands -The `nemoclaw` binary handles host-side operations that run outside the OpenClaw plugin context. +The CLI handles host-side operations that run outside the selected agent runtime. ### `nemoclaw help`, `nemoclaw --help`, `nemoclaw -h` Show the top-level usage summary and command groups. Running `nemoclaw` with no arguments shows the same help output. -```console -$ nemoclaw help +```bash +nemoclaw help ``` ### `nemoclaw --version`, `nemoclaw -v` Print the installed NemoClaw CLI version. -```console -$ nemoclaw --version +```bash +nemoclaw --version ``` ### `nemoclaw resources` @@ -43,8 +90,8 @@ $ nemoclaw --version Display host hardware inventory and configured sandbox resource profiles. Use `--json` for machine-readable CPU, memory, GPU, Kubernetes allocatable-capacity, and profile data. -```console -$ nemoclaw resources [--json] +```bash +nemoclaw resources [--json] ``` If the gateway is not running, Kubernetes allocatable fields are omitted and host CPU/RAM totals are still shown. @@ -55,33 +102,58 @@ Run the interactive setup wizard (recommended for new installs). The wizard creates an OpenShell gateway, registers inference providers, builds the sandbox image, and creates the sandbox. Use this command for new installs and for recreating a sandbox after changes to policy or configuration. -```console -$ nemoclaw onboard [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from ] [--name ] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device ] [--agent ] [--control-ui-port ] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software] +```bash +nemoclaw onboard [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from ] [--name ] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device ] [--agent ] [--control-ui-port ] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software] ``` + + +For Hermes, use the alias or pass the agent explicitly: + +```bash +nemohermes onboard [options] +nemoclaw onboard --agent hermes [options] +``` + + + +#### `--resume` and `--fresh` + +NemoClaw records onboarding progress so interrupted runs can continue. +Use `--resume` to continue a resumable onboarding session with the provider, model, sandbox name, agent, and custom Dockerfile path recorded by the original run. +If the recorded session conflicts with flags you pass on the recovery run, NemoClaw exits and tells you to either rerun with the original settings or start over. + +Use `--fresh` to discard the saved onboarding session and start the wizard from the beginning. +This clears stale or failed session state before NemoClaw creates a new session record. +The installer also accepts `--fresh` and forwards it to `nemoclaw onboard`, which skips automatic resume detection. +`--resume` and `--fresh` are mutually exclusive. + **Warning:** For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox. Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemoclaw onboard`. +Use `--fresh` to ignore any saved onboarding session and restart the wizard from scratch. This is useful after an interrupted `nemoclaw onboard` run when you want to discard saved state instead of continuing it with `--resume`. + The installer detects existing sandbox sessions before onboarding and prints a warning if any are found. To make the installer abort instead of continuing, set `NEMOCLAW_SINGLE_SESSION=1`: -```console -$ NEMOCLAW_SINGLE_SESSION=1 curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +```bash +NEMOCLAW_SINGLE_SESSION=1 curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` When existing sandboxes were created with OpenShell earlier than `0.0.37`, the installer prompts before running the new automatic gateway upgrade path. For scripted installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1` to allow the installer to back up registered sandbox state, retire the old gateway, install the current supported OpenShell release, and restore state during onboarding. The automatic path is disabled if the existing `nemoclaw` CLI does not advertise `backup-all`; preserve sandbox state manually before retiring the old gateway in that case. -To perform those steps manually, run `nemoclaw backup-all`, retire the old gateway with `openshell gateway destroy -g nemoclaw || openshell gateway destroy`, then rerun the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. +To perform those steps manually, run `nemoclaw backup-all`, retire the old gateway registration with `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (both verbs are tried so the right one runs on either OpenShell release), stop any remaining privileged host gateway with `sudo pkill -f openshell-gateway`, then rerun the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. The wizard prompts for a provider first, then collects the provider credential if needed. Supported non-experimental choices include NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints. Credentials are registered with the OpenShell gateway and never persisted to host disk. See Credential Storage (use the `nemoclaw-user-configure-security` skill) for details on inspection, rotation, and migration from earlier releases. The legacy `nemoclaw setup` command is deprecated; use `nemoclaw onboard` instead. -After provider selection, the wizard prompts for a **policy tier** that controls the default set of network policy presets applied to the sandbox. +After provider selection, the wizard reviews the provider, model, credential state, and sandbox name before registering inference. +It then prompts for optional web search and messaging channels, builds and starts the sandbox, and asks for a **policy tier** that controls the default set of network policy presets applied to the sandbox. Three tiers are available: | Tier | Description | @@ -92,11 +164,13 @@ Three tiers are available: After selecting a tier, the wizard shows a combined preset and access-mode screen where you can include or exclude individual presets and toggle each between read and read-write access. For details on tiers and the presets each includes, see [Network Policies](network-policies.md#policy-tiers). +When you finish the policy step, NemoClaw records the finalized built-in preset selection for that sandbox. +Later re-onboard runs seed from that finalized selection, so presets you intentionally removed stay removed unless you select them again or override the policy mode. In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `balanced`): -```console -$ NEMOCLAW_POLICY_TIER=restricted nemoclaw onboard --non-interactive --yes-i-accept-third-party-software +```bash +NEMOCLAW_POLICY_TIER=restricted nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` `NEMOCLAW_POLICY_MODE` controls how non-interactive onboarding reconciles the tier-derived suggestions against the sandbox's currently-applied presets. @@ -113,34 +187,37 @@ NemoClaw filters tier suggestions and resume selections by active agent support, | `custom` | Apply exactly `NEMOCLAW_POLICY_PRESETS`. Previously-applied presets not in the list are removed. Alias: `list`. | | `skip` | Skip the policy step entirely. Aliases: `none`, `no`. | + + If you enable Brave Search during onboarding, NemoClaw registers a Brave Search OpenShell provider and keeps `openclaw.json` on an OpenShell credential placeholder. At egress, OpenShell rewrites Brave's `X-Subscription-Token` header with the real `BRAVE_API_KEY`. Treat Brave Search as an explicit opt-in and use a dedicated low-privilege Brave key. + For non-interactive onboarding, you must explicitly accept the third-party software notice: -```console -$ nemoclaw onboard --non-interactive --yes-i-accept-third-party-software +```bash +nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` or: -```console -$ NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 nemoclaw onboard --non-interactive +```bash +NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 nemoclaw onboard --non-interactive ``` For scripted installer runs, pass explicit acceptance to the `bash` side of the installer pipe: -```console -$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash +```bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash ``` If the installer cannot prompt for the notice in a terminal and no explicit acceptance is set, it exits before installing Node.js or the NemoClaw CLI. To enable Brave Search in non-interactive mode, set: -```console -$ BRAVE_API_KEY=... \ +```bash +BRAVE_API_KEY=... \ nemoclaw onboard --non-interactive ``` @@ -150,7 +227,8 @@ After fixing the key, re-enable web search with `nemoclaw config web-search`. The wizard prompts for a sandbox name. Names must be 1 to 63 characters, lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number. -Uppercase letters are automatically lowercased. +The CLI rejects names that do not match these rules. +It also prints a `Try: ` recovery line whenever it can derive a valid lowercase, hyphen-separated form from the input, so passing `--name MyAssistant` reports `Try: myassistant`. Names that match global CLI commands (`status`, `list`, `debug`, etc.) are rejected to avoid routing conflicts. Use `--agent ` to target a specific installed agent profile during onboarding. @@ -172,18 +250,32 @@ If you enable Telegram during onboarding, the wizard can also prompt for whether Set `TELEGRAM_REQUIRE_MENTION=1` for non-interactive onboarding when you want mention-only group replies. Pairing and `TELEGRAM_ALLOWED_IDS` still govern direct messages. -If you run onboarding again with the same sandbox name and choose a different inference provider or model, NemoClaw detects the drift and recreates the sandbox so the running OpenClaw UI matches your selection. +If you cancel a brand-new onboarding run at the policy preset step, NemoClaw rolls back the sandbox, registry entry, and onboarding session instead of leaving a default sandbox with unfinished policy state. +Existing live sandboxes are not deleted by this cancel rollback path. + +If you run onboarding again with the same sandbox name and choose a different inference provider or model, NemoClaw detects the drift and recreates the sandbox so the running agent config matches your selection. In interactive mode, the wizard asks for confirmation before delete and recreate. In non-interactive mode, NemoClaw recreates automatically when the stored selection is readable and differs; if NemoClaw cannot read the stored selection, NemoClaw reuses by default. Set `NEMOCLAW_RECREATE_SANDBOX=1` to force recreation even when no drift is detected. -Before deleting an existing sandbox during recreation, NemoClaw backs up the workspace state (agents, extensions, workspace, skills, hooks, identity, devices, canvas, cron, memory, telegram, wechat, credentials) and restores it into the new sandbox once it is live. -This applies whether the existing sandbox is ready or marked not-ready, so cross-version upgrades that pass `NEMOCLAW_RECREATE_SANDBOX=1` no longer drop user files under `/sandbox/.openclaw/workspace/`. +Before deleting an existing sandbox during recreation, NemoClaw backs up the workspace state declared by the selected agent profile and restores it into the new sandbox once it is live. +This applies whether the existing sandbox is ready or marked not-ready, so cross-version upgrades that pass `NEMOCLAW_RECREATE_SANDBOX=1` no longer drop user files from the selected agent workspace. The behaviour matches `nemoclaw rebuild --force`. NemoClaw aborts the recreate when the backup cannot complete in full — including when individual state directories or files fail mid-backup — so failed entries are not silently dropped on delete. Set `NEMOCLAW_RECREATE_WITHOUT_BACKUP=1` to skip the pre-recreate backup. The destination sandbox starts with a fresh workspace. + + +For OpenClaw, the backed-up paths include agents, extensions, workspace, skills, hooks, identity, devices, canvas, cron, memory, telegram, wechat, credentials, and `/sandbox/.openclaw/workspace/`. + + + + +For Hermes, the backed-up paths come from `agents/hermes/manifest.yaml`, including `/sandbox/.hermes` state such as memories, sessions, skills, plugins, cron, logs, plans, workspace, messaging platform state, and `runtime/state.db`. + + + Before creating the gateway, the wizard runs preflight checks. It verifies that Docker is reachable, warns on untested runtimes such as Podman, and prints host remediation guidance when prerequisites are missing. The preflight also enforces the OpenShell version range declared in the blueprint (`min_openshell_version` and `max_openshell_version`). @@ -197,7 +289,9 @@ On the Docker-driver gateway path, preflight stays read-only when it detects a s It prints a `⚠ Gateway will be recreated when sandbox creation starts` notice and defers the actual teardown to step `[2/8] Starting OpenShell gateway`. This means pressing `Ctrl+C` between preflight and step `[2/8]` leaves the running gateway and existing sandbox containers untouched, so `nemoclaw onboard` is safe to run just to check preflight output. For Linux Docker-driver gateways, onboarding also checks that a helper container on the OpenShell Docker network can reach `host.openshell.internal:`. -If a host firewall blocks that sandbox path, onboarding exits with a `sudo ufw allow from to any port proto tcp` command before it reports the gateway healthy. +If a host firewall blocks that sandbox path, onboarding exits with a `sudo ufw allow from to port proto tcp` command before it reports the gateway healthy. +Set `NEMOCLAW_AUTO_FIX_FIREWALL=1` to opt in to automatic UFW remediation for this specific failure: NemoClaw uses `sudo -n` only, validates the Docker bridge subnet/gateway/port, applies the narrow UFW rule only after a proven TCP reachability failure, and re-probes before continuing. +If passwordless sudo, UFW, or active UFW is unavailable, NemoClaw falls back to the manual guidance path without prompting for a password. Tune the wait via `NEMOCLAW_REUSE_HEALTH_POLL_COUNT` (default `6`) and `NEMOCLAW_REUSE_HEALTH_POLL_INTERVAL` (default `5` seconds). The poll count is clamped to a minimum of `1` so the probe always runs at least once, and the interval is clamped to a minimum of `0` (no sleep between attempts). @@ -211,8 +305,8 @@ Other build outputs such as `dist/`, `target/`, or `build/` are still included. If the staged context is larger than 100 MB, onboarding prints a warning before the Docker build starts. If the directory contains unreadable files (for example, Windows system files visible in WSL), onboarding exits with an error suggesting you move the Dockerfile to a dedicated directory. -```console -$ nemoclaw onboard --from path/to/Dockerfile +```bash +nemoclaw onboard --from path/to/Dockerfile ``` The Dockerfile path must exist. @@ -232,8 +326,8 @@ All NemoClaw build arguments (`NEMOCLAW_MODEL`, `NEMOCLAW_PROVIDER_KEY`, `NEMOCL In non-interactive mode, the path can also be supplied via the `NEMOCLAW_FROM_DOCKERFILE` environment variable. You must also supply a sandbox name via `--name ` or `NEMOCLAW_SANDBOX_NAME` so a `--from` build cannot silently clobber the default `my-assistant` sandbox. -```console -$ NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_FROM_DOCKERFILE=path/to/Dockerfile NEMOCLAW_SANDBOX_NAME=my-build nemoclaw onboard +```bash +NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_FROM_DOCKERFILE=path/to/Dockerfile NEMOCLAW_SANDBOX_NAME=my-build nemoclaw onboard ``` If a `--resume` is attempted with a different `--from` path than the original session, onboarding exits with a conflict error rather than silently building from the wrong image. @@ -244,8 +338,8 @@ Set the sandbox name without going through the interactive prompt. The same name format and reserved-name rules that the wizard enforces apply here too. Names must be 1 to 63 characters, lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number. Names that match a NemoClaw CLI command (`status`, `list`, `debug`, etc.) are rejected up front. -```console -$ nemoclaw onboard --non-interactive --name my-build --from path/to/Dockerfile +```bash +nemoclaw onboard --non-interactive --name my-build --from path/to/Dockerfile ``` The flag wins over `NEMOCLAW_SANDBOX_NAME`. @@ -258,13 +352,15 @@ Combining `--from ` with non-interactive onboarding requires one of Use a custom Dockerfile for the sandbox image. This variant of `nemoclaw onboard` accepts a `--from ` argument to build the sandbox from a user-supplied Dockerfile instead of the default NemoClaw image. -```console -$ nemoclaw onboard --from ./Dockerfile.custom +```bash +nemoclaw onboard --from ./Dockerfile.custom ``` ### GPU passthrough -When `nemoclaw onboard` detects an NVIDIA GPU on the host (`nvidia-smi` succeeds), it enables OpenShell GPU passthrough at both the gateway and sandbox level by default. +When `nemoclaw onboard` detects an NVIDIA GPU on the host, it enables OpenShell GPU passthrough at both the gateway and sandbox level by default. +Detection proceeds along two paths. The `nvidia-smi`-based paths (the primary `--query-gpu=name,memory.total,memory.free` probe and the unified-memory `--query-gpu=name` fallback) require `nvidia-smi` to succeed and, on hosts whose firmware does not classify as a known NVIDIA platform (DGX Spark, DGX Station, Jetson, or Tegra), additionally require that the GPU name does not match the placeholder family observed on the Windows-on-ARM WSL2 nvidia-smi shim (`JMJWOA-Generic-*`) and that either the host is not ARM64 Linux (the observed shim is Windows-on-ARM only) or the NVIDIA kernel driver is bound (`/proc/driver/nvidia/` present), so that placeholder shims on non-NVIDIA hardware are not mistaken for real GPUs. +Jetson/Tegra hosts that ship without `nvidia-smi` continue to be detected via the devicetree firmware fallback (`/sys/firmware/devicetree/base/model`) or the Tegra device-node fallback (`/dev/nvhost-gpu`, `/dev/nvhost-ctrl-gpu`, `/dev/nvhost-ctrl`, or `/dev/nvmap`); both bypass the trust-tier gate above. Use `--no-gpu` to opt out when you want host-side inference providers only and do not need direct GPU access inside the sandbox. Use `--gpu` to require GPU passthrough and fail fast if an NVIDIA GPU is not detected. Use `--sandbox-gpu` or `--no-sandbox-gpu` to control only direct NVIDIA GPU access inside the sandbox. @@ -274,7 +370,9 @@ If the patch fails, onboarding keeps diagnostics and prints a manual cleanup com Prerequisites: -- NVIDIA GPU drivers installed and working (`nvidia-smi` must succeed). +- Ensure NVIDIA GPU drivers are installed and working. + - On generic NVIDIA hosts, `nvidia-smi` must succeed. + - On Jetson/Tegra hosts shipping without `nvidia-smi`, the devicetree firmware fallback substitutes. - NVIDIA Container Toolkit configured for Docker. When GPU passthrough is enabled and a gateway already exists without it, onboarding first checks whether replacing the CPU-only gateway is safe. @@ -290,9 +388,9 @@ Pass `--json` for machine-readable output that includes a `schemaVersion`, the d Sandboxes with an active SSH session are marked with a `●` indicator so you can tell at a glance which sandbox you are already connected to in another terminal. When a sandbox has a recorded dashboard port, the output includes its local dashboard URL. -```console -$ nemoclaw list [--json] -$ nemoclaw list --json +```bash +nemoclaw list [--json] +nemoclaw list --json ``` ### `nemoclaw deploy` @@ -307,8 +405,8 @@ This command remains as a compatibility wrapper for the older Brev-specific boot The Brev instance name is the positional argument. The sandbox name comes from `NEMOCLAW_SANDBOX_NAME` and defaults to `my-assistant`; invalid sandbox names fail before Brev provisioning starts. -```console -$ nemoclaw deploy +```bash +nemoclaw deploy ``` ### `nemoclaw connect` @@ -323,12 +421,20 @@ Set `NEMOCLAW_NO_CONNECT_HINT=1` to suppress the hint in scripted workflows. If the sandbox is running an outdated agent version, a non-blocking warning prints before connecting with a `nemoclaw rebuild` hint. If another terminal is already connected to the sandbox, `connect` prints a note with the number of existing sessions before proceeding. Multiple concurrent sessions are allowed. +`connect` does not pull or serve a model itself, but it does inspect `NEMOCLAW_VLLM_MODEL` if you exported it for the managed-vLLM install path. +An unknown slug or a gated model (for example `deepseek-r1-distill-70b`) with no `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN` exits non-zero with the same error the installer would emit, before any sandbox readiness probe or SSH attach. +Unset the variable, or supply the missing token, before retrying. + +When the live OpenShell gateway inference route differs from the route recorded in the NemoClaw registry, `connect` prints an explicit warning and realigns the shared gateway to the recorded route. +Use `nemoclaw inference set --provider --model ` to make an intentional route change. +If the sandbox is registered locally but missing from a healthy gateway, `connect` preserves the registry entry and points you to `rebuild --yes`, `onboard`, or `destroy` instead of deleting the metadata needed for recovery. + After a host reboot, the OpenShell gateway rotates its SSH host keys. `connect` detects the resulting identity drift, prunes stale `openshell-*` entries from `~/.ssh/known_hosts`, and retries automatically. You no longer need to re-run `nemoclaw onboard` after a reboot in this case. -```console -$ nemoclaw my-assistant connect [--probe-only] +```bash +nemoclaw my-assistant connect [--probe-only] ``` The `--probe-only` flag verifies the sandbox is reachable over SSH and exits without opening a shell. @@ -337,14 +443,30 @@ Use it for health checks and scripted readiness probes. ### `nemoclaw exec` Run a single command non-interactively in a running sandbox via the OpenShell exec endpoint. -The command runs as the sandbox user with `HOME=/sandbox`, so in-sandbox tooling resolves NemoClaw-provisioned config under `/sandbox/.openclaw` the same way it does for `connect` and `openshell sandbox connect`. -This is the supported substitute for `docker exec` on the sandbox container; raw `docker exec` runs as root and lands on `HOME=/root`, where the agent config is not present and `openclaw agent` falls back to its built-in defaults. +The command runs as the sandbox user with `HOME=/sandbox`, so in-sandbox tooling resolves NemoClaw-provisioned config the same way it does for `connect` and `openshell sandbox connect`. +This is the supported substitute for `docker exec` on the sandbox container; raw `docker exec` runs as root and lands on `HOME=/root`, where the selected agent config is not present. -```console -$ nemoclaw my-assistant exec -- openclaw agent -m "What is 2+2?" -$ nemoclaw my-assistant exec --workdir /sandbox/workspace -- ls -la + + +OpenClaw config resolves under `/sandbox/.openclaw`. + +```bash +nemoclaw my-assistant exec -- openclaw agent -m "What is 2+2?" +nemoclaw my-assistant exec --workdir /sandbox/workspace -- ls -la +``` + + + + +Hermes config resolves under `/sandbox/.hermes`. + +```bash +nemohermes my-assistant exec -- hermes --version +nemohermes my-assistant exec --workdir /sandbox/workspace -- ls -la ``` + + Everything after `--` is forwarded verbatim to the sandbox command, including flags the inner command needs. The exit code is the remote command's exit code. @@ -363,14 +485,29 @@ Use this after a sandbox pod restart, a sandbox crash, or whenever `nemoclaw status` Show sandbox status, health, and inference configuration. +Pass `--json` to emit a structured per-sandbox report instead of the text renderer. +The JSON output includes at least `schemaVersion`, `name`, `found`, `model`, `provider`, `phase`, `gatewayState`, `inferenceHealth`, `rpcIssue`, `hostGpuDetected`, `sandboxGpuEnabled`, `sandboxGpuMode`, `sandboxGpuDevice`, `openshellDriver`, `openshellVersion`, `policies`, `failureLayer`, and `dockerPaused`. +`openshellDriver` and `openshellVersion` are always strings (falling back to `"unknown"` when the registry has no value), so consumers can rely on `typeof` checks. +`failureLayer` is `null` when no preflight failure was detected and otherwise one of `docker_unreachable`, `sandbox_container_stopped`, or `sandbox_dashboard_port_conflict`; when set, `inferenceHealth` is suppressed to `null` so automation does not see a stale remote-provider healthy status during a local outage. +`dockerPaused` is `true` when NemoClaw detects that the Docker-driver sandbox container is paused. +In that case, text output keeps OpenShell's authoritative phase but prints a `docker unpause ` recovery hint instead of sending you directly to rebuild. +The command exits non-zero when the sandbox is missing locally, the gateway state is not `present`, the gateway reports a schema/protobuf mismatch (mirrored as `rpcIssue`), or `failureLayer` is non-null. +The alias form `nemoclaw status --json` requires the sandbox to be registered locally; the canonical form `nemoclaw sandbox status --json` is the one to use from automation that may run against an unknown sandbox name, since it still emits a JSON document with `found: false` instead of a text error. + +```bash +nemoclaw my-assistant status +nemoclaw my-assistant status --json +nemoclaw sandbox status my-assistant --json +``` + The command probes every inference provider and reports one of three states on the `Inference` line: | State | Meaning | @@ -389,9 +526,19 @@ Use that line to distinguish a healthy backend from a broken proxy path that the For cloud-only providers, the output omits the NIM status line unless a NIM container is registered or an unexpected NIM container is running. +When the sandbox's recorded driver is `docker` and the host Docker daemon is not reachable, the command prints `Failure layer: docker_unreachable — Docker daemon is not reachable.` as the first line of stdout, suppresses the host-side `Inference` probe (which otherwise hits the remote provider directly and is misleading when the local stack is down), and exits with a non-zero status. + +When the host Docker daemon is reachable but the per-sandbox container is stopped, the command prints `Failure layer: sandbox_container_stopped — sandbox container exists but is not running.` as the first line of stdout, suppresses the host-side `Inference` probe, and exits with a non-zero status. +If the sandbox's recorded dashboard port is also held by a foreign listener, the header escalates to `Failure layer: sandbox_dashboard_port_conflict — sandbox container is stopped and the dashboard port is held by a foreign listener.` so the operator can recover the port before restarting the sandbox. + If the sandbox or gateway cannot be verified, the command exits non-zero instead of reporting healthy inference from stale registry state. +When a locally registered sandbox is missing from the live gateway, status preserves the registry entry so the suggested `rebuild --yes` recovery can still find the sandbox metadata. Gateway and dashboard health checks treat HTTP `401` from device auth as a live service, not as an offline gateway. +When sandbox GPU passthrough is enabled, the `Sandbox GPU` line includes the last CUDA usability proof state. +It reports `(CUDA verified)`, `(CUDA unverified)`, or `(last CUDA proof failed: