> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemoclaw/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemoclaw/_mcp/server. # NemoHermes CLI Commands Reference > Full CLI reference for standalone NemoHermes commands and Hermes-specific in-sandbox commands. 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, refer to [CLI Selection Guide](cli-selection-guide). ## Agent Selection 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 built-in Hermes dashboard, the separate OpenAI-compatible API endpoint, 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 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. ## Hosted Installer Options The hosted installer accepts options after `bash -s --`. These options control installation and the onboarding run that follows it. ### `--local-model-runtime=vllm` Enable the fixed vLLM local model profile. The flag accepts only `vllm`. It makes the remaining onboarding non-interactive and disables Express profile selection. ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | \ NEMOCLAW_AGENT=hermes \ NEMOCLAW_SANDBOX_NAME=my-assistant \ NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 \ bash -s -- --local-model-runtime=vllm ``` The profile selects a fixed catalog model and serving command from the managed-inference catalog. The hosted installer rejects `NEMOCLAW_PROVIDER`, `NEMOCLAW_MODEL`, and a vLLM `NEMOCLAW_VLLM_PORT` override before onboarding. The dedicated vLLM onboarder rejects `NEMOCLAW_VLLM_MODEL`, `NEMOCLAW_VLLM_PORT`, and `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` before it installs vLLM. The hosted installer's equivalent environment-variable form requires both `NEMOCLAW_ENABLE_LOCAL_MODEL_PROFILE=1` and `NEMOCLAW_LOCAL_MODEL_RUNTIME`. Use the installer flag unless an automation boundary cannot pass installer arguments. For prerequisites, effects, verification, and recovery, refer to [Choose a Local Inference Server](../inference/local-inference/choose-local-inference-server#install-a-fixed-vllm-profile). ## Hosted Installer Exit Statuses The hosted installer reports how a run stopped through its exit status. When you interrupt it at a prompt, it exits `130`, the same status that `nemohermes onboard` reports for that interrupt. An interrupted onboarding run still prints `[ERROR] Onboarding did not complete successfully.` before it exits, so read the exit status rather than that line. The installer preserves no other signal status, and a progress step stopped by `SIGTERM` also exits `130`, so a script that stops the installer itself cannot read `130` as a deliberate interrupt. DGX Station host preparation exits `10` when it requires a reboot and `11` when it requires a new login session, and prints the command that resumes the install. Treat every other non-zero status as a failure. ## Standalone Host Commands The CLI handles host-side operations that run outside the selected agent runtime. ### `nemohermes help`, `nemohermes --help`, `nemohermes -h` Show the top-level usage summary and command groups. Running `nemohermes` with no arguments shows the same help output. ```bash nemohermes help ``` ### `nemohermes --version`, `nemohermes -v` Print the installed NemoClaw CLI version. ```bash nemohermes --version ``` ### `nemohermes completion` Generate a tab-completion script for Bash, Zsh, or Fish from the commands and flags available in the installed CLI. The script completes public global commands, the sandbox-first `nemohermes ...` grammar, flags, shell choices, and locally registered sandbox names. If you omit the shell name, `nemohermes completion` detects the target from `$SHELL` and defaults to Bash when it cannot identify Zsh or Fish. The generated script is bound to the CLI name that created it, so install a separate script for each CLI alias you use. It loads sandbox names from the local registry the first time completion runs and caches them for the rest of that shell session. For Bash, source the generated script and add the same line to `~/.bashrc` for future sessions. ```bash source <(nemohermes completion bash) ``` For Zsh, source the generated script and add the same line to `~/.zshrc` for future sessions. ```zsh source <(nemohermes completion zsh) ``` For Fish, write the generated script to Fish's completions directory. ```fish mkdir -p ~/.config/fish/completions nemohermes completion fish > ~/.config/fish/completions/nemohermes.fish ``` Start a new shell session to refresh the cached sandbox names after creating or removing a sandbox. ### `nemohermes resources` Display host hardware inventory and configured sandbox resource profiles. Use `--json` for machine-readable CPU, memory, GPU, Kubernetes allocatable-capacity, and profile data. ```bash nemohermes resources [--json] ``` If the gateway is not running, Kubernetes allocatable fields are omitted and host CPU/RAM totals are still shown. ### `nemohermes host probe` Inspect host capabilities and gateway authority before onboarding without changing host, Docker, gateway, credential, policy, or sandbox state. Use `--json` for the schema-versioned report. The command exits with `0` for `supported`, `2` for `incompatible`, and `3` for `inconclusive`. ```bash nemohermes host probe [--json] ``` For capability IDs, evidence bounds, and compatibility guidance, refer to [System Readiness](system-readiness). ### `nemohermes agents list` List the installed agent runtimes that can be selected with `nemohermes onboard --agent `. Use this global command when you need valid runtime names before creating or recreating a sandbox. It lists runtime names with the descriptions from their installed manifests. ```bash nemohermes agents list ``` Expected output: ```text openclaw Gateway-based AI agent with plugin ecosystem (openclaw.ai) hermes Self-improving AI agent with learning loop (Nous Research) langchain-deepagents-code Terminal coding agent built on the Deep Agents SDK ``` ### `nemohermes profiles list` List the serving profiles installed with NemoClaw and evaluate them against the current host. The command reports each profile's stable ID, display name, inference backend, model, topology, selection mode, support state, estimated downloads, and incompatibility reason. It reads the serving catalog and host readiness state without downloading a model or changing host, gateway, inference, or sandbox resources. ```bash nemohermes profiles list ``` Use `--json` for machine-readable output with the same profile fields. ```bash nemohermes profiles list --json ``` Use the stable `id` value with `nemohermes onboard --profile `. Display names are accepted when they identify exactly one profile, but stable IDs are suitable for scripts and automation. ### `nemohermes onboard` 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. ```bash nemohermes onboard [--profile ] [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from ] [--name ] [--host-mount ] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device ] [--agent ] [--agents ] [--tool-disclosure ] [--observability | --no-observability] [--control-ui-port ] [--events=jsonl] [--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] ``` `--agent` accepts the canonical manifest names from `nemohermes agents list` plus common aliases. For example, `nemohermes` resolves to `hermes`, while `dcode`, `deepagents`, `deepagents-code`, and `langchain` resolve to `langchain-deepagents-code`. #### `--profile ` Select one serving profile from `nemohermes profiles list` for interactive or non-interactive onboarding. The flag is generic and does not add a model-specific command or flag. NemoClaw maps a unique display name to its stable catalog ID and passes that ID to the managed inference path. ```bash nemohermes onboard --profile ``` NemoClaw rejects an unknown, ambiguous, disabled, or incompatible profile before image or model downloads begin. It also rejects `--profile` when you combine it with `NEMOCLAW_PROVIDER`, `NEMOCLAW_MODEL`, `NEMOCLAW_VLLM_MODEL`, `NEMOCLAW_MANAGED_CLUSTER_PEERS`, or `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` overrides. If `NEMOCLAW_SERVING_PRESET` is already set, it must select the same stable profile ID; a different ID conflicts with `--profile`. Run `nemohermes profiles list` to inspect an incompatibility reason before onboarding. If you omit `--profile`, onboarding uses the same provider and model defaults as an installation without this feature. The onboarding review screen identifies the resolved profile, recipe, model, runtime image, support state, and download estimates before confirmation. After creation, human status shows the profile, recipe, and catalog digest; JSON status includes the complete secret-free `servingProfileProvenance` record for diagnostics and automation. #### `--host-mount` On Linux and Windows Subsystem for Linux 2 (WSL2), repeat `--host-mount ` to expose existing host directories read-only inside the sandbox. The option requires a NemoClaw-managed Docker-driver gateway and does not provide a read-write mode. Refer to [Mount a Host Directory for Read-Only Access](../manage-sandboxes/state-and-backups/understand-sandbox-state#mount-a-host-directory-for-read-only-access) for validation rules, security considerations, persistence, and verification. #### `--events=jsonl` Emit a read-only stream of canonical onboarding FSM events as JSON Lines on stdout. Each line is one JSON object with the version 1 envelope: ```json {"schemaVersion":1,"session":"","type":"state.entered","timestamp":"2026-07-13T12:34:56.789Z","payload":{"state":"inference","step":"inference","context":{"agent":"openclaw","sandboxName":"alpha","provider":"nvidia-prod","model":"nvidia/test-model","endpointOrigin":"https://integrate.api.nvidia.com","credentialEnv":"NVIDIA_API_KEY"},"error":null,"metadata":{}}} ``` In this mode, human progress remains available on stderr so stdout stays valid JSONL. Payloads contain only the existing bounded, redacted machine-event context: credential environment variable names may appear, but credential values and secret-bearing URL components are redacted. For a `compatible-endpoint` route that uses `openai-completions`, the context includes `reasoningEffort` as `low`, `medium`, `high`, or `endpoint-default`. Other provider and API-family routes omit this field. Treat new event `type` values and new payload fields as additive changes. A breaking envelope or field-semantics change increments `schemaVersion`. This surface observes the canonical onboarding session and does not accept input, cancel onboarding, or create another state machine. It does not provide event history, reconnect, or replay; use the existing `--resume` behavior after an interrupted onboarding process. Closing the output pipe or applying sustained backpressure disables observation without cancelling, rolling back, or otherwise changing onboarding. Without `--events=jsonl`, terminal output and behavior are unchanged. #### `--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, observability choice, custom Dockerfile path, read-only host-mount declarations, and any explicitly selected serving-profile provenance recorded by the original run. For a profile-backed session, resume requires the same catalog, preset, and recipe digests and exits before effects if the installed definition changed. Omit `--profile` to reuse that recorded selection, or pass the same profile explicitly; use `--fresh` to adopt a changed catalog definition. Sessions without a serving-profile provenance record can resume when their checkpoint uses schema 4, but they cannot acquire a new `--profile` selection during resume. Checkpoint schema 4 records whether onboarding uses the default profile or the portable experimental profile. For the portable profile, it also records the current user's canonical home reported by the operating system, that home's exact `.config` directory, the runtime root, rootless Podman endpoint path, and runtime ownership. It does not record ambient Docker or Podman runtime selector values. The runtime authority record contains no credentials. A plain `--resume` restores the recorded profile. You can also run `nemohermes onboard --experimental-profile portable --resume` when the recorded profile is portable. NemoClaw rejects an explicit profile that conflicts with the checkpoint before it changes portable configuration, activates the user-scoped Podman socket, or changes gateway and sandbox resources. Portable resume derives `DOCKER_HOST`, `CONTAINERS_CONF`, and `NETAVARK_FW` again while it holds the onboarding lock. It ignores ambient Docker and Podman runtime selectors during that derivation. NemoClaw scopes the derived values to onboarding and restores the process environment after success or failure. It verifies the current user, canonical roots, socket path and ownership, Podman identity and version, and required configuration before a resumed onboarding step changes resources. Resume stops before writes or activation if an existing socket or configuration path is a symlink, has the wrong owner, or has an unsafe type or mode. NemoClaw can create missing descendants beneath a validated current-user root and reconcile content drift in its own portable configuration files. A missing user-scoped socket after a host reboot can be activated and verified at the recorded path. A new socket inode or a supported Podman upgrade does not invalidate the checkpoint. Portable onboarding always uses the `.config` directory beneath the canonical home reported by the operating system. `HOME` and `XDG_CONFIG_HOME` never select or override this authority. NemoClaw ignores ambient `XDG_CONFIG_HOME` during onboarding and restores its exact prior presence and value afterward. Resume rejects a checkpoint that records another configuration root. It also rejects stored authority or filesystem ownership drift without falling back to Docker. #### Checkpoint Resume Compatibility An active onboarding session with checkpoint schema 1, 2, or 3 cannot resume because those schemas did not record the default or portable profile authority. NemoClaw preserves the older session and exits before portable configuration, socket activation, or resource changes. Run `nemohermes onboard --fresh` to discard the active session and start fresh onboarding. If you intend to use the portable experimental profile, run `nemohermes onboard --experimental-profile portable --fresh`. This compatibility restriction does not prevent NemoClaw from reading a completed older session during status inspection. Before the configuration review, NemoClaw records the sandbox name and the selected provider and model as an incomplete choice. If onboarding stops at the review prompt, an interactive `--resume` run shows the prompt again. A non-interactive `--resume` run reuses the recorded choice and continues to inference setup. After you choose **Apply configuration**, NemoClaw records the choice before inference setup starts. If inference setup fails, `--resume` reuses the accepted provider, model, and sandbox name. If you choose **Exit onboarding**, onboarding exits with a nonzero status and clears those recorded choices. Run `nemohermes onboard` to make new choices after exit. During a resume without terminal input, `--yes` or `NEMOCLAW_YES=1` also selects non-interactive resume behavior. For a new or fresh session, `--yes` and `NEMOCLAW_YES=1` accept supported confirmations but do not replace `--non-interactive`. If onboarding returns without reaching the final `complete` state, the command exits with status `1`. When that result is resumable, NemoClaw keeps the session `in_progress` at its last checkpoint instead of marking it failed, so correct the reported condition and run `nemohermes onboard --resume`. Completed onboarding sessions are not resumable. Use `--resume` only for resumable interrupted or failed sessions, not to change provider, model, agent, or sandbox recreation settings after onboarding has completed. During resume, NemoClaw reruns preflight, gateway, provider, and sandbox repair checks even when the saved session has already reached a later nonterminal onboarding phase. 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. An active same-name replacement is separate from ordinary onboarding-step resume. If onboarding printed `Journaled replacement` before it stopped, rerun the original onboarding command with the same target settings. The replacement can continue without an explicit `--resume` flag. Refer to [Continue an Interrupted Replacement](../manage-sandboxes/operate-sandboxes/recover-and-rebuild-sandboxes#continue-an-interrupted-replacement) for the identity checks and failure conditions. 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. It also bypasses locally recorded sandbox base-image resolution metadata and reruns normal candidate resolution. `--fresh` takes precedence over a base-image hint carried from a rebuild, so NemoClaw does not use that recorded hint. The installer also accepts `--fresh` and forwards it to `nemohermes onboard`, which skips automatic resume detection. `--resume` and `--fresh` are mutually exclusive. For an existing completed sandbox, use `--fresh --name --recreate-sandbox` when you intentionally want onboarding to replace that sandbox with a new provider, model, agent, or build-time setting. Use `nemohermes rebuild` when you want NemoClaw to recreate the sandbox from its recorded registry metadata without changing those selections. #### `--tool-disclosure ` Choose how the selected agent presents its session-authorized tools to the model. `progressive` is the default: OpenClaw and Hermes use their native Tool Search implementations, while Deep Agents Code initially shows its core tools plus `search_tools` after at least one MCP tool loads successfully. `direct` restores the previous behavior and presents all registered tools directly. This setting changes model context only; it does not bypass OpenShell policy, credentials, approvals, hooks, or sandbox controls. The flag takes precedence over `NEMOCLAW_TOOL_DISCLOSURE`. A new sandbox defaults to `progressive` when neither is set. NemoClaw records the selected value with the onboarding session and sandbox so rebuilds preserve it and ambient shell variables cannot silently change an internal rebuild. Model-specific compatibility safeguards may downgrade a selected `progressive` mode to direct exposure for that model without changing the recorded preference. To change an existing sandbox, recreate it explicitly: ```bash nemohermes onboard --name my-assistant --recreate-sandbox --tool-disclosure direct ``` Without an explicit flag or environment value, recreation preserves the recorded setting and only falls back to `progressive` for legacy state. Resuming an interrupted session with a different explicit setting fails with a conflict instead of changing behavior mid-session. When Docker exposes the required identity metadata, NemoClaw records the base-image resolution on managed sandbox images. During a warm recreate or rebuild, it validates the local image identity and platform, plus the exact repository digest for a published image and any active OpenShell ABI requirement, before reusing it. A valid match avoids candidate discovery and a network pull. Set `NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1` to bypass the recorded hint without changing onboarding session handling: ```bash NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1 nemohermes onboard --recreate-sandbox NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1 nemohermes rebuild ``` Base-image selection follows this precedence: 1. `--fresh` or `NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1` bypasses recorded metadata and reruns normal candidate resolution. These controls are equivalent for base-image selection. 2. Without a bypass, NemoClaw validates and reuses the recorded hint when possible. 3. When the hint is absent or no longer valid, NemoClaw performs normal resolution. After a cache miss, source checkouts require a fresh local build before candidate selection when base-image inputs have dirty or staged changes, or Git cannot inspect the worktree safely. For a clean release checkout or versioned install, NemoClaw first accepts the exact release-version image. If that tag exists locally but fails compatibility validation, NemoClaw refreshes the same tag from the registry once and validates it again. If the release-version image is missing or still incompatible, NemoClaw builds a compatible local base instead of falling back to mutable `:latest`. For clean unversioned development checkouts, NemoClaw first tries the image tagged with the exact source commit. If that image is unavailable and committed base-image inputs differ from `main`, NemoClaw requires a compatible local build. When committed base-image inputs match `main`, NemoClaw tries the image tagged with the newest reachable release version from `origin` and only uses `:latest` when no version tag is discoverable. When a stable tag and a prerelease tag share the same version, NemoClaw prefers the stable tag. If `origin` tag lookup is unavailable, NemoClaw uses the newest reachable local release tag as a fallback. If that nearest release-version image is missing or incompatible, NemoClaw builds a compatible local base instead of falling back to mutable `:latest`. The required-build path does not reuse an older local tag. If local builds are disabled or the build fails, resolution stops instead of selecting a stale image. When the OpenShell sandbox ABI is required, NemoClaw also rejects a built image that does not report a compatible glibc version. Explicit base-image overrides are exact: NemoClaw validates the requested ref and fails closed when it cannot be pulled or does not satisfy required ABI, agent runtime, or dependency checks. Otherwise, normal resolution checks compatible images in Docker's local image store before attempting to pull a missing published candidate. For warm-hint reuse and unversioned development resolution, NemoClaw can reuse another validated local fallback when published candidates are unavailable or incompatible. When the OpenShell sandbox ABI is required, that local fallback must be ABI-compatible. An offline warm recreate or rebuild can therefore continue when the recorded image or another compatible candidate is available locally. When source inputs require a fresh local build, NemoClaw fails the operation if that build cannot be produced and validated instead of substituting an older local tag. When the OpenShell sandbox ABI is required, resolution also fails if no ABI-compatible image can be resolved instead of falling back to an unvalidated cached `:latest` image. For Hermes, warm-hint and candidate validation reruns a container probe for the MCP SDK and native Streamable HTTP integration. During normal resolution, NemoClaw tries the exact published digest declared by the final Hermes Dockerfile before release-version and source-commit candidates. The digest must also pass any active OpenShell ABI requirement, and a validated result can be recorded for warm-hint reuse. The final Hermes image accepts only the official published digest tracked by its Dockerfile or a repository-built local base, so an otherwise reachable or ABI-compatible image is not sufficient. Bypassing the recorded hint does not clear Docker's local image store or require a network pull. Only `--fresh` also discards the saved onboarding session; the refresh environment variable affects base-image selection only. For NemoClaw-managed environments, use `nemohermes onboard` when you need to create or recreate the OpenShell gateway or sandbox. Avoid `openshell self-update`, `npm update -g openshell`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemohermes onboard`. Use `--fresh` to ignore any saved onboarding session and restart the wizard from scratch. This is useful after an interrupted `nemohermes 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`: ```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 automatic gateway upgrade path. For scripted installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1` to allow the automatic path to prepare the current CLI without replacing OpenShell, back up every registered sandbox with the current state manifest, retire an installed gateway whose OpenShell version is outside the current release's supported range, install the supported OpenShell release, and recover the existing sandboxes. The installer reads that supported range from the prepared current source and stops without retiring the gateway if the installed version is unknown or the range is missing or invalid. When the installed OpenShell version is already supported, the installer keeps the running gateway through the host update. On Linux, if installed OpenShell lifecycle commands cannot retire the gateway, the installer checks a verified NemoClaw-managed gateway PID file for any configured gateway port. For the default gateway on port `8080`, the installer first checks a verified active `nemoclaw-openshell-gateway.service`, then checks the PID file. After either fallback confirms the gateway process is stopped, the installer tries to remove the selected OpenShell registration and warns if onboarding must replace a stale registration. If neither fallback can verify and stop the process, the installer stops after backup with every sandbox backup preserved. If any registered sandbox cannot be backed up, the installer aborts before it changes the gateway. After the automatic path retires an out-of-range gateway, it forces installation of the OpenShell version pinned by the prepared source before recovery. This mandatory installation applies to source and managed install modes and cannot remain deferred after gateway retirement. If the forced installation fails, the installer does not stage a gateway service or start recovery, preserves the backups, and tells you to rerun with `NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1`. When the registry contains a pre-fingerprint OpenClaw or Hermes entry with no recorded custom-image evidence, an interactive install asks you to confirm that the listed sandbox used a NemoClaw-managed image. For a non-interactive install, set `NEMOCLAW_CONFIRM_LEGACY_MANAGED_RECREATE` to the exact JSON array of names printed by the installer, such as `["my-assistant","preserve-hermes"]`, only after verifying every named sandbox used a managed image. The confirmation permits those legacy entries to recover onto the current managed image, but it does not override recorded custom-image evidence. After successful recovery, the installer skips generic onboarding. For any registered-sandbox upgrade that you already prepared manually, set `NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1` only after backing up every registered sandbox and retiring the old gateway. This environment variable asserts that those steps are complete, so the installer skips the repeated backup and gateway-retirement phase before it checks whether OpenShell is installed or whether its version is in range. For a non-default gateway, preserve the selected port on the `bash` side of the install pipeline. ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_GATEWAY_PORT= NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash ``` It reuses the latest backups, forces the pinned OpenShell installation, and starts recovery only after that installation succeeds. If the installation fails, rerun the same install-pipeline command to preserve `NEMOCLAW_GATEWAY_PORT` and `NEMOCLAW_OPENSHELL_UPGRADE_PREPARED`. #### Legacy Upgrade Recovery Scope Prepared backup recovery for a legacy sandbox restores only the managed state directory recorded in its validated manifest, such as `/sandbox/.openclaw` or `/sandbox/.hermes`. Files outside that recorded path, including `/sandbox/user-data`, are not preserved when the installer recreates the sandbox. Back up those paths outside the sandbox before you continue. The wizard prompts for a provider first, then collects the provider credential if needed. Supported non-experimental choices include NVIDIA Endpoints, OpenRouter, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints. Credentials are registered with the OpenShell gateway and never persisted to host disk. Refer to [Credential Storage](../security/credential-storage) for details on inspection, rotation, and migration from earlier releases. The legacy `nemohermes setup` command is deprecated; use `nemohermes onboard` instead. On a qualified DGX Spark, the provider menu also offers the experimental **NVIDIA Nemotron with managed llama.cpp (DGX Spark)** path. Select the same path non-interactively with the repository-owned recipe: ```bash NEMOCLAW_PROVIDER=install-llama-cpp \ NEMOCLAW_LLAMACPP_RECIPE=llama-cpp.nemotron-3-nano-30b-a3b.spark-single.v1 \ NEMOCLAW_SANDBOX_NAME=my-assistant \ nemohermes onboard --non-interactive --yes-i-accept-third-party-software ``` Do not set `NEMOCLAW_MODEL` for the managed llama.cpp path. For prerequisites, external traffic, verification, and recovery, refer to [Install Managed llama.cpp on DGX Spark](../inference/local-inference/choose-local-inference-server#install-managed-llamacpp-on-dgx-spark). After provider selection, the wizard reviews the provider, model, credential state, and sandbox name before registering inference. The interactive review offers these actions: * **Apply configuration** continues to provider registration. * **Edit inference provider or model** returns to provider and model selection. * **Edit sandbox name** prompts for the sandbox name again. * **Exit onboarding** stops onboarding before provider registration. When you edit inference, NemoClaw clears the credential staged for the discarded selection. NemoClaw preserves the sandbox name. When you edit the sandbox name, NemoClaw preserves the inference selection. The sandbox prompt shows the prior name as its default. After you apply the configuration, routine editing ends. If inference setup fails and offers a `back` recovery action, you can return to provider and model selection and then review the updated configuration again. 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. Four tiers are available: | Tier | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Restricted | No tier defaults. Web search or other integrations selected earlier can still add their required presets; deselect them during policy review for baseline-only access. | | Balanced (default) | Full dev tooling and a selected, supported web search provider. Package installs, model downloads, and inference. No messaging platform access by default. | | Open | Broad access across third-party services including supported messaging and productivity presets. Agent-specific unsupported presets are filtered out. | | Personal | Lets every sandbox binary open TCP connections to public and private address ranges on destination ports 80 and 443. Unspecified, loopback, and link-local ranges remain blocked. Also selects every maintained preset supported by the active agent. Intended only for trusted personal-use workloads. | 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, refer to [Network Policies](network-policies#policy-tiers). When you finish the policy step, NemoClaw records the finalized built-in preset selection for that sandbox. When onboarding creates or recreates a sandbox with presets, NemoClaw prints the exact finalized create-time policy scope before registering providers or creating the 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`): ```bash NEMOCLAW_POLICY_TIER=restricted nemohermes onboard --non-interactive --yes-i-accept-third-party-software ``` Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. In non-interactive mode, any non-blank value must be one of `restricted`, `balanced`, `open`, or `personal`; otherwise onboarding exits before preflight, gateway, or inference side effects with an error listing the valid options. Interactive onboarding ignores an invalid environment value and shows the normal tier prompt. `NEMOCLAW_POLICY_MODE` controls how non-interactive onboarding reconciles the tier-derived suggestions against the sandbox's currently-applied presets. The default is `suggested`, which is *additive*. Onboarding applies tier defaults and preserves any presets you previously added with [`nemohermes policy add`](#nemohermes-name-policy-add) across re-onboards. Use `custom` with `NEMOCLAW_POLICY_PRESETS` when you want the explicit list to be authoritative. Onboarding removes any preset that is not in the list. `skip` leaves the applied set untouched and does not apply tier defaults. NemoClaw filters tier suggestions and resume selections by active agent support and the selected web search provider. During automatic suggestion and resume reconciliation, it removes stale web-search selections when they conflict with the active agent or selected provider. The Personal tier is the exception: it preserves every applicable maintained web-search preset even when onboarding did not configure that provider. For Hermes, this includes replacing stale `nous-web` when Tavily is selected. An explicit `custom` preset list or interactive manual selection remains operator-controlled. Hermes managed-tool gateway selections add matching Hermes-specific policy presets, such as `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`, without applying unsupported OpenClaw-only presets. When Tavily Search is selected, it replaces `nous-web` as the Hermes web search and extract backend while the other selected Nous tools remain enabled. | Value | Behaviour | | --------------------- | --------------------------------------------------------------------------------------------------------------- | | `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`. | | `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`. | For non-interactive onboarding, you must explicitly accept the third-party software notice: ```bash nemohermes onboard --non-interactive --yes-i-accept-third-party-software ``` or: ```bash NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 nemohermes onboard --non-interactive ``` For scripted installer runs, pass explicit acceptance to the `bash` side of the installer pipe: ```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. Hermes supports Tavily Search through NemoClaw onboarding and does not support Brave Search. To enable Tavily in non-interactive mode, set the provider and matching key. ```bash NEMOCLAW_WEB_SEARCH_PROVIDER=tavily \ TAVILY_API_KEY=... \ nemohermes onboard --non-interactive ``` Set `NEMOCLAW_WEB_SEARCH_PROVIDER=none` to disable web search explicitly. When the selector is unset, NemoClaw enables Tavily when `TAVILY_API_KEY` is available and ignores `BRAVE_API_KEY` for Hermes. An explicit Tavily selection with no key exits before sandbox creation. A Tavily key that fails validation prints a warning, disables web search for that run, and lets the rest of onboarding continue. Changing or disabling Tavily recreates the sandbox because the Hermes backend, environment placeholder, and credential attachment are part of the image. If you also select the Nous-managed web gateway through Nous Portal OAuth, Tavily replaces `nous-web` while other selected Nous tools remain enabled. API-key mode is inference-only and does not enable managed Nous tool gateways. The wizard prompts for a sandbox name. Names must contain 1 to 19 characters. They must be lowercase, start with a letter, contain only letters, numbers, and single internal hyphens, and end with a letter or number. Consecutive hyphens (`--`) are not allowed. 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. The `nemohermes onboard --help` output lists installed runtime names inline, and `nemohermes agents list` shows the same runtimes with manifest descriptions. Use `--control-ui-port ` to choose the host dashboard port for a sandbox. The value must be an integer from `1024` through `65535`. This flag takes precedence over `CHAT_UI_URL`, `NEMOCLAW_DASHBOARD_PORT`, the previous registry value, and the default port. Do not use a port from `8642` through `8652` for any agent. NemoClaw allocates each Hermes sandbox's OpenAI-compatible API port from that range, so it rejects every port in the range as a dashboard port before sandbox creation. If you enable Slack during onboarding, the wizard collects both the Bot Token (`SLACK_BOT_TOKEN`) and the App-Level Token (`SLACK_APP_TOKEN`). Socket Mode requires both tokens. The app-level token is stored in a dedicated `slack-app` OpenShell provider and forwarded to the sandbox alongside the bot token. The wizard also accepts optional `SLACK_ALLOWED_USERS` and `SLACK_ALLOWED_CHANNELS` values so you can restrict Slack DMs, channel `@mention` users, and channel IDs before the sandbox image is built. If you enable Discord during onboarding, the wizard can also prompt for a Discord Server ID, whether the bot should reply only to `@mentions` or to all messages in that server, and an optional Discord User ID. NemoClaw bakes those values into the sandbox image as Discord guild workspace config so the bot can respond in the selected server, not just in DMs. If you leave the Discord User ID blank, the guild config omits the user allowlist and any member of the configured server can message the bot. Guild responses remain mention-gated by default unless you opt into all-message replies. If `DISCORD_SERVER_ID` is set and `DISCORD_REQUIRE_MENTION` is unset, NemoClaw records the existing mention-only default (`DISCORD_REQUIRE_MENTION=1`). If you enable Telegram during onboarding, the wizard can also prompt for whether group chats should reply only to `@mentions` or to all group messages. Mention-only group replies are the default. Set `TELEGRAM_REQUIRE_MENTION=0` for non-interactive onboarding when you want all group messages to trigger replies. For OpenClaw, Telegram group access defaults to `TELEGRAM_GROUP_POLICY=open`; set `TELEGRAM_GROUP_POLICY=allowlist` or `TELEGRAM_GROUP_POLICY=disabled` before non-interactive onboarding when you want stricter group access. Hermes does not have an equivalent disable-groups policy; `TELEGRAM_ALLOWED_IDS` maps to Hermes `TELEGRAM_ALLOWED_USERS`, which authorizes those users across DMs, groups, and forums. Pairing and `TELEGRAM_ALLOWED_IDS` still govern direct messages. 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. For managed Deep Agents Code sandboxes, NemoClaw also recreates when the live `dcode identity` selection is unreadable; other agent paths continue to reuse by default when their stored selection cannot be read. 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 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 `nemohermes 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. Before deletion, onboarding prints a `Journaled replacement` diagnostic with the replacement identifier, recorded OpenShell gateway, and current phase. If the process stops after this point, a later same-target onboarding run continues the active replacement without requiring `--resume`. It accepts a ready same-name replacement only when the live identity and sandbox registry generation match the journal. It fails closed if the gateway, source, target, durable source registry fields, or replacement settings changed. For Hermes, the backed-up paths come from `agents/hermes/manifest.yaml`, including `/sandbox/.hermes` state such as memories, sessions, skills, plugins, cron, scripts, logs, plans, workspace, messaging platform state, `runtime/state.db`, and the default kanban board in `kanban.db`. Kanban backup does not include named boards, attachments, worker logs, scratch workspaces under `kanban/`, or external directory or worktree targets. Before creating the gateway, the wizard runs preflight checks. It verifies that Docker is reachable and prints host remediation guidance when prerequisites are missing. Standard onboarding rejects unsupported runtimes such as Podman. The explicit portable experimental profile has one installer-preflight admission exception for the Podman unsupported-runtime finding. It does not waive any other readiness blocker or make Podman generally supported. The preflight also enforces the OpenShell version range declared in the blueprint (`min_openshell_version` and `max_openshell_version`). If the installed OpenShell version falls outside this range, onboarding exits with an actionable error and a link to compatible releases. For fresh OpenShell installs, NemoClaw queries published OpenShell releases and asks the installer to use a release that fits the blueprint range. If release metadata is unavailable, the installer uses its bundled fallback pin and the post-install version gate still enforces the range. When NemoClaw finds an existing gateway to reuse, it probes the host gateway HTTP endpoint before declaring the gateway reusable. If the container is running but the upstream is still warming up (for example, immediately after a Docker daemon restart), NemoClaw rebuilds the gateway instead of trusting stale metadata. On the Docker-driver gateway path, preflight stays read-only when it detects a stale gateway (for example, a Docker-driver runtime env hash drift). 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 `nemohermes onboard` is safe to run just to check preflight output. An interrupted run prints the resume command and exits with status `130` for `Ctrl+C` or `143` for `SIGTERM`. 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 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. For the portable experimental profile, the helper maps `host.openshell.internal` to the OpenShell Podman host gateway instead of the inspected network gateway. This path does not use Docker bridge UFW remediation. After all portable TCP probe attempts fail, onboarding prints commands for the user-scoped Podman service and socket. Onboarding prints the same commands when the portable probe cannot reach the user-scoped Podman service. The printed rerun command keeps the portable experimental profile selected. To tune the existing-gateway HTTP health poll, use `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 health probe always runs at least once, and the interval is clamped to a minimum of `0` (no sleep between attempts). #### `--from ` Build the sandbox image from a custom Dockerfile instead of the stock NemoClaw image. The supplied Dockerfile defines the complete sandbox image, and NemoClaw does not layer it on top of the stock managed runtime. The entire parent directory of the specified file is used as the Docker build context, so any files your Dockerfile references (scripts, config, etc.) must live alongside it. When the supplied path is the selected agent's own managed Dockerfile (for example, `agents/hermes/Dockerfile` in the NemoClaw checkout the CLI runs from), NemoClaw applies one exception and stages the repository root as the build context, exactly as the managed build does, because that Dockerfile copies repository-root paths. This lets you edit the managed Dockerfile in place (for example to add Python packages) and rebuild from it with `--from`. For this managed exception, onboarding applies the `.dockerignore` from the repository root. For every other `--from` path, onboarding applies a `.dockerignore` from the Dockerfile's parent directory while calculating the context size and staging files for Docker. NemoClaw also applies additional secret-safety exclusions that override `.dockerignore` negation rules: credential-style files and directories such as `.env*`, `.ssh/`, `.aws/`, `.netrc`, `.npmrc`, `secrets/`, `*.pem`, and `*.key` are still skipped even if `.dockerignore` tries to include them. Without a `.dockerignore`, onboarding still skips common large or local-only directories (`node_modules`, `.git`, `.venv`, and `__pycache__`) while staging this context. Other build outputs such as `dist/`, `target/`, or `build/` are included unless your `.dockerignore` excludes them. If the staged context is larger than 100 MB, onboarding prints a warning before the Docker build starts. Move the Dockerfile into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context. 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. NemoClaw builds user-supplied `--from` contexts with the OpenShell gateway builder. The host-side local BuildKit prebuild is limited to build contexts generated entirely by NemoClaw. On a local Docker-driver gateway, a `Local BuildKit build skipped` notice is expected and onboarding continues with the custom image. ```bash nemohermes onboard --from path/to/Dockerfile ``` The Dockerfile path must exist. Missing paths fail during command parsing before preflight, gateway setup, inference setup, or sandbox creation starts. The file can have any name; if it is not already named `Dockerfile`, onboard copies it to `Dockerfile` inside the staged build context automatically. To create an isolated build context, create a dedicated directory that contains only the Dockerfile and the files it needs: ```text build-dir/ ├── Dockerfile └── files-used-by-COPY/ ``` For faster custom builds, plan for Docker cache behavior: * Treat the first build on a fresh host as a cold build. Cold builds download the base image and package indexes, so they take longer than later warm rebuilds even when NemoClaw is healthy. * A warm rebuild reuses cached layers when the base image and earlier layers are unchanged, so it is much faster than the first build. * Order Dockerfile instructions from least-changing to most-changing: base image, system packages, dependency manifests, dependency install, then application source. This lets warm rebuilds reuse cached dependency layers instead of reinstalling on every source change. * Pin the base image to an explicit tag or digest so warm rebuilds resolve the same cached base instead of pulling a new one. To diagnose where a slow build spends time, set `NEMOCLAW_TRACE=1` and read the phase timings in [Onboard Profiling Traces](#onboard-profiling-traces). NemoClaw does not guarantee exact build timings. All NemoClaw build arguments (`NEMOCLAW_MODEL`, `NEMOCLAW_INFERENCE_PROVIDER_ID`, `NEMOCLAW_INFERENCE_BASE_URL`, etc.) are injected as `ARG` overrides at build time, so declare them in your Dockerfile if you need to reference them. `NEMOCLAW_INFERENCE_PROVIDER_ID` is a non-secret inference route identifier (for example `inference` for proxied providers, or a provider family such as `openai`), never a credential; provider credentials stay in OpenShell provider storage. It replaces the former `NEMOCLAW_PROVIDER_KEY` image argument, whose secret-shaped name triggered a BuildKit `SecretsUsedInArgOrEnv` warning. The host-side `NEMOCLAW_PROVIDER_KEY` credential alias is unchanged; this migration only renames the managed image route selector. Custom Dockerfiles that declare either `ARG NEMOCLAW_INFERENCE_PROVIDER_ID` or the legacy `ARG NEMOCLAW_PROVIDER_KEY` continue working in v0.0.91. NemoClaw updates whichever supported declaration is present, and runtime consumers read the legacy name as a fallback. Rename the legacy `ARG`/`ENV` declaration to `NEMOCLAW_INFERENCE_PROVIDER_ID`; the legacy fallback is retained for compatibility in this release and may be removed in a future release. Custom Dockerfiles must declare `ARG NEMOCLAW_TOOL_DISCLOSURE=progressive` exactly once in the final build stage and promote it into that stage's runtime environment. The usual runtime contract is: ```dockerfile ARG NEMOCLAW_TOOL_DISCLOSURE=progressive ENV NEMOCLAW_TOOL_DISCLOSURE=${NEMOCLAW_TOOL_DISCLOSURE} ``` Onboarding and rebuild preflight reject a missing, duplicate, or unconsumed declaration before replacing an existing sandbox. 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. ```bash NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_FROM_DOCKERFILE=path/to/Dockerfile NEMOCLAW_SANDBOX_NAME=my-build nemohermes 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. #### `--name ` 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 contain 1 to 19 characters. They must be lowercase, start with a letter, contain only letters, numbers, and single internal hyphens, and end with a letter or number. Consecutive hyphens (`--`) are not allowed. Names that match a NemoClaw CLI command (`status`, `list`, `debug`, etc.) are rejected up front. ```bash nemohermes onboard --non-interactive --name my-build --from path/to/Dockerfile ``` The flag wins over `NEMOCLAW_SANDBOX_NAME`. When prompting is possible, `NEMOCLAW_SANDBOX_NAME` fills the interactive default so you can press Enter to accept it. When prompting is impossible (no TTY or `--non-interactive`), the env var is also honoured so existing CI scripts keep working. Combining `--from ` with non-interactive onboarding requires one of `--name` or `NEMOCLAW_SANDBOX_NAME`; otherwise onboarding exits rather than silently defaulting to `my-assistant` and clobbering the default sandbox. ### `nemohermes onboard --from` Use a custom Dockerfile for the sandbox image. This variant of `nemohermes onboard` accepts a `--from ` argument to build the sandbox from a user-supplied Dockerfile instead of the default NemoClaw image. The user-supplied context uses the OpenShell gateway builder instead of NemoClaw's host-side local BuildKit prebuild. ```bash nemohermes onboard --from ./Dockerfile.custom ``` ### GPU Passthrough When `nemohermes onboard` detects an NVIDIA GPU on the host, it enables OpenShell GPU passthrough at both the gateway and sandbox level by default. The `nvidia-smi` probes require a successful result and reject placeholder `JMJWOA-Generic-*` GPU names unless NemoClaw can prove a supported NVIDIA platform or GPU execution. NemoClaw treats a recognized NVIDIA product model from `/sys/class/dmi/id/product_name` or `/sys/firmware/devicetree/base/model`, or a known Tegra device node, as authoritative platform identity. On eligible native or Docker Desktop-backed WSL ARM64 Linux hosts without that firmware evidence, one bounded Docker CUDA workload can prove GPU execution. On those hosts, a single plausible, non-placeholder NVIDIA GPU name also requires that proof when the NVIDIA kernel-driver interface (`/proc/driver/nvidia`) is absent. For Windows-on-Arm, this proof is a technical detection check and does not change the Unsupported product status or establish platform qualification. Refer to [Platform Support and Launch Claims](platform-support#out-of-scope-and-not-supported) for the current support boundary. For the proof command, timeout control, and failure recovery, refer to [GPU Setup Fails with a Placeholder GPU Name](troubleshooting#gpu-setup-fails-with-a-placeholder-gpu-name). The names-only unified-memory fallback does not run this workload and rejects denylisted names. Other non-firmware-vouched hosts also reject denylisted names. 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. Use `--sandbox-gpu --sandbox-gpu-device ` to pass a specific OpenShell GPU device selector to `openshell sandbox create`; device selectors require explicit sandbox GPU enablement. On ordinary native Linux Docker-driver hosts, NemoClaw uses native OpenShell GPU injection by default and never broadens confinement automatically. Set `NEMOCLAW_DOCKER_GPU_PATCH=fallback` to explicitly authorize one native attempt followed by one compatibility retry. NemoClaw permits the retry only after it confirms either a trusted host-side GPU routing failure or an explicit driver proof plus exact-container host configuration showing that no GPU was attached. It then saves redacted diagnostics and removes the incomplete sandbox before retrying. Sandbox-reported CUDA output alone never authorizes the broader compatibility envelope, even when the operator enabled fallback. That case fails closed and points to the explicit `NEMOCLAW_DOCKER_GPU_PATCH=1` compatibility-only control. NemoClaw retries only after it verifies that no OpenShell-managed Docker container labeled for that sandbox remains; if cleanup cannot be proven safe, onboarding stops and prints cleanup guidance instead. On Docker Desktop WSL and Jetson/Tegra, automatic GPU onboarding uses the compatibility path directly. On ordinary native Linux, the compatibility path uses an available NVIDIA CDI spec before falling back to Docker `--gpus all` or the NVIDIA runtime. On Docker Desktop WSL, the compatibility path skips CDI and tries Docker `--gpus all` before the NVIDIA runtime. On Jetson/Tegra hosts, the compatibility path uses the NVIDIA runtime and adds eligible host group IDs for the supported GPU device nodes. These include selected `/dev/nvmap`, `/dev/nvhost-*`, and `/dev/nvgpu/igpu0/*` nodes plus real `/dev/dri/renderD*` character devices. After compatibility recreation starts, onboarding keeps the pre-patch container as a rollback backup until the replacement passes the Ready, GPU, and applicable local-inference checks. If a later check fails, onboarding prints failure diagnostics and attempts to restore the pre-patch container. If rollback fails, onboarding reports that the pre-patch container was not restored and prints container-cleanup guidance. GPU-proof diagnostics are captured before rollback and can print that guidance before the final container state is known, so inspect the sandbox and its labeled Docker containers before running a deletion command. Prerequisites: * 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. If no other registered sandbox depends on that gateway, or if `--recreate-sandbox` is recreating the only registered sandbox with the same name, onboarding cleans up the stale gateway and continues. If other sandboxes depend on the gateway or Docker state is unclear, onboarding exits without cleanup and prints targeted destroy or gateway-removal guidance. To add GPU to an existing sandbox, rerun with `--recreate-sandbox`. Leave `NEMOCLAW_DOCKER_GPU_PATCH` unset or set it to `auto` for native-only GPU onboarding on ordinary native Linux. Set `NEMOCLAW_DOCKER_GPU_PATCH=fallback` to explicitly opt into one bounded native-to-compatibility retry on ordinary native Linux. Set `NEMOCLAW_DOCKER_GPU_PATCH=0` to require native OpenShell GPU injection on ordinary native Linux or Jetson/Tegra. Set `NEMOCLAW_DOCKER_GPU_PATCH=1` to use only the compatibility path on ordinary native Linux. Other legacy nonzero values keep that behavior through the `v0.0.x` release line and will be removed in `v0.1.0`. Use `NEMOCLAW_DOCKER_GPU_PATCH=0` on Jetson/Tegra only for troubleshooting because it bypasses Tegra device-group propagation and CUDA may not initialize. Docker Desktop WSL ignores `NEMOCLAW_DOCKER_GPU_PATCH=0` because GPU passthrough on that runtime requires the compatibility patch. Use `--no-sandbox-gpu`, `--no-gpu`, or `NEMOCLAW_SANDBOX_GPU=0` when you want to disable sandbox GPU passthrough on Docker Desktop WSL. ### `nemohermes list` List all registered sandboxes with their model, provider, and policy presets. Pass `--json` for machine-readable output that includes a `schemaVersion`, the default sandbox, recovery metadata, and the sandbox inventory. Each sandbox row reports `activeSessionCount` as a nonnegative integer when the SSH-session probe is available and `null` when it is unavailable. Each sandbox row reports `agent` as a string in both text and JSON output, never `null`. The row reports `openclaw` when the registry records no agent for the sandbox. The row reports `unknown` for a sandbox that `nemohermes list` recovers from the live OpenShell gateway. The gateway sandbox list does not expose the agent. The row does not include the former derived `connected` boolean. 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. The default sandbox in text and JSON output honors the same environment override order as host-level status and tunnel commands: `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default. ```bash nemohermes list [--json] nemohermes list --json ``` ### `nemohermes use ` Promote a registered sandbox to the default. This is the first-class replacement for hand-editing `~/.nemoclaw/sandboxes.json`; it updates the registry through the same atomic, lock-guarded path that `nemohermes onboard` uses for the initial default. Subsequent commands and the `NEMOCLAW_SANDBOX_NAME` resolution order then pick up the new default automatically. Pass `--json` to receive a machine-readable result indicating whether the registry was updated, the sandbox was already the default, or the name is unknown. `nemohermes use` is a thin selector and never mutates the sandbox itself. It fails with a non-zero exit and a known-sandbox list when the requested name is not registered, so scripts can branch safely on the outcome. ```bash nemohermes use nemohermes use --json ``` ### `nemohermes launch ` Connect to a sandbox and start its agent in one host-side command. Use it instead of running `nemohermes connect` and then typing the agent command inside the sandbox. `launch` runs the complete preflight from [`nemohermes connect`](#nemohermes-name-connect) when no launch-readiness lease is usable. That path includes the readiness wait, in-sandbox agent process recovery, and inference-route reconciliation. A successful complete preflight can publish a credential-free launch-readiness lease with a fixed 24-hour lifetime on Linux. Lease acceptance and publication are currently Linux-only and require a secure, independently writable OS per-user runtime authority under `/run/user/`. It never uses caller-provided environment variables to select this authority. On macOS, `launch` runs the complete preflight every time and does not publish a launch-readiness lease. During that lease, another `launch` still verifies these conditions: * The owning OpenShell gateway reports the exact sandbox identity in the `Ready` or `Running` state. * The sandbox registry, agent manifest, interactive command, policy intent, and effective parsed OpenShell network policy match the recorded identity. * The recorded inference selection matches the live route, and `inference.local` returns HTTP 2xx from its semantic probe when inference is configured. This is stricter than the HTTP 200–499 reachability diagnostic used by ordinary `connect`. * The agent runtime and its required host-side forwards pass their semantic health checks. Hermes and LangChain Deep Agents Code retain their existing session setup on the lease-accepted path. After these checks pass, `launch` can skip duplicate recovery, readiness polling, and inference-route repair. The lease does not replace a health check or authorize repair. For missing, expired, malformed, inaccessible, mismatched, or unhealthy evidence, NemoClaw fences any prior acceptable evidence before it runs the complete preflight. Ordinary launch continues only when NemoClaw proves that no old authority or evidence can exist, or durably rotates the runtime epoch. If an old epoch might exist and cannot be durably rotated, `launch` stops before complete preflight or recovery. Its redacted guidance asks you to repair the current user's secure OS runtime authority and NemoClaw state permissions, then retry. A failed live check never becomes a successful launch because a lease exists. Immediately before the first mutation in the complete preflight, the producer revalidates its sandbox-global runtime epoch while holding the sandbox lifecycle lock followed by the owning gateway lock. It holds both locks through all mutations in the complete preflight, final state capture, and publication. If another producer has replaced the epoch, the stale producer makes no changes and re-inspects the newer lease. The 24-hour lifetime does not extend when you launch repeatedly. Exiting the agent with `/exit` does not revoke the lease. If state changes before expiry, NemoClaw fences the old evidence and runs the complete preflight. A successful preflight in that interval keeps the original start and expiry time. After expiry, a successful complete preflight starts a new 24-hour lease only when publication succeeds. If unsafe or malformed authority history makes the prior lease timeline untrustworthy, NemoClaw durably invalidates the old epoch and starts one conservative 24-hour quarantine. Both wall time and monotonic uptime must span the full quarantine, and publication remains disabled during it. Repeated attempts do not extend the quarantine. After it elapses, the next successful complete preflight can publish a new fixed 24-hour lease. You do not create or refresh this lease manually, and `launch` has no lease-control flags. After lease validation or the automatic fallback that runs the complete preflight, `launch` starts the sandbox's agent in your terminal instead of opening a sandbox shell. The agent command comes from the sandbox's agent manifest. If the sandbox registry names a non-OpenClaw agent without a readable local agent manifest, `launch` exits before starting an in-sandbox command. | Agent | Command | | -------------------------- | -------------- | | OpenClaw | `openclaw tui` | | Hermes | `hermes` | | LangChain Deep Agents Code | `dcode` | ```bash nemohermes launch ``` The sandbox name is required, and the command takes no flags. The sandbox must already exist in the local NemoClaw state. If it is not registered locally, `launch` exits before it runs an OpenShell command or readiness recovery and reports that the sandbox is not registered in the local NemoClaw state. When the agent exits, you return to the host shell. `launch` returns the agent's exit code. When you want a shell inside the sandbox rather than an agent session, use `nemohermes connect`. ### `nemohermes deploy` The `nemohermes deploy` command is deprecated. Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `nemohermes onboard` on that host. Deploy NemoClaw to a remote GPU instance through [Brev](https://brev.nvidia.com). This command remains as a compatibility wrapper for the older Brev-specific bootstrap flow. 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. ```bash nemohermes deploy ``` ### `nemohermes connect` Connect to a sandbox by name. Bare `nemohermes connect` (no sandbox name) connects to the registry default. NemoClaw uses the stored default when it names a non-pending registered sandbox, then falls back to the first non-pending registration. If only pending registrations remain, the command exits non-zero and tells you to wait for onboarding or remove the incomplete sandbox. If the registry remains empty after recovery, it tells you to run `nemohermes onboard`. A registered sandbox literally named `connect` keeps the name-first reading. If the sandbox is not yet in the `Ready` phase, `connect` polls `openshell sandbox list` every few seconds and prints the current phase. This gives you progress output right after onboarding, when the 2.4 GB image is still pulling, instead of a silent hang. Control the wait budget with `NEMOCLAW_CONNECT_TIMEOUT` in integer seconds. An interactive connection defaults to `120` seconds, while `--probe-only` and [`nemohermes start`](#nemohermes-name-start) default to `300` seconds so a scripted health check can wait through a cold sandbox start. When the deadline expires, `connect` exits non-zero with the last-seen phase. On a TTY, a one-shot hint prints before dropping into the sandbox shell. The hint is agent-aware. It names the correct TUI command for the sandbox's agent and reminds you to use `/exit` to leave the chat before `exit` returns you to the host shell. 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 `nemohermes 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. Without `--probe-only`, `connect` does not pull a model itself, but it does inspect managed-vLLM install variables such as `NEMOCLAW_VLLM_MODEL` and `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` if you exported them in the same shell. An unknown model slug, malformed extra-args JSON, 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 managed-vLLM variable, or fix the value, before retrying a regular connection. `connect --probe-only` skips this install preflight so stale managed-vLLM variables cannot block recovery. Before reading or changing the live OpenShell gateway inference route, `connect` verifies the shared provider and sandbox metadata. When the live route differs and the metadata is compatible, `connect` warns and re-points the route to the target sandbox's recorded provider and model. Refer to [Use Shared Gateway Routes](../inference/manage-inference/use-shared-gateway-routes) for provider-global identity, route drift, and hard-error recovery. Use `nemohermes inference set --provider --model ` to make an intentional compatible route change outside the connect flow. Before it opens SSH, `connect` probes `https://inference.local/v1/models` from inside the sandbox with the selected agent's trusted CA and proxy context. HTTP `200` through `499` confirms that the route is reachable. When the probe returns a recognized broken result, `connect` attempts DNS or route repair and verifies the route again. When the initial probe cannot return a trusted result, `connect` fails closed before health-driven repair and before opening SSH. It prints a bounded, redacted last-probe detail and points you to `nemohermes doctor`. 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 `nemohermes onboard` after a reboot in this case. ```bash nemohermes my-assistant connect [--probe-only] nemohermes connect ``` On Linux, the `--probe-only` flag is the infrastructure producer for launch-readiness evidence. It validates a usable lease and exits without duplicate recovery. Otherwise, it fences prior evidence, waits for the sandbox, verifies or repairs its in-sandbox agent process and host-side forwards, and publishes evidence only after every probe succeeds. It rechecks the sandbox on its recorded OpenShell gateway after the readiness wait and never restarts the shared host gateway. If an old runtime epoch might exist and cannot be durably rotated, the command exits nonzero before complete preflight or recovery and gives redacted repair guidance. A securely absent runtime authority and receipt let ordinary `launch` run the complete preflight without optimization if new authority creation fails, but `connect --probe-only` still exits nonzero because it could not publish launch-readiness evidence. A runtime failure and a failure to publish evidence for an otherwise healthy runtime also exit nonzero with different diagnostics. Infrastructure must run the command as the same final numeric user that later runs `launch`. Run it only after the final durable home and state volume is mounted and after policy and network provisioning is complete. On Linux, that user also needs a secure, independently writable OS per-user runtime authority under `/run/user/`. Do not redirect this authority with caller environment variables. Do not use a graphical or login-session identifier as the deployment ordering boundary. On macOS, `connect --probe-only` runs the complete preflight, including recovery and probes, but exits nonzero because it cannot publish authoritative launch-readiness evidence. The publication-failure diagnostic is redacted and does not print filesystem paths or environment values. Run it for health checks and scripted readiness probes; users continue to run only `nemohermes launch `. Use [`nemohermes launch `](#nemohermes-launch-name) when you want launch-readiness validation, an automatic fallback that runs the complete preflight, and then the agent instead of a sandbox shell. ### `nemohermes 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 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. For a registered sandbox, NemoClaw selects its recorded owning OpenShell gateway before the workdir probe and command dispatch. If gateway selection fails, `exec` stops without running the sandbox command. 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. By default, NemoClaw inherits caller stdin only when it is a terminal. Non-terminal or unavailable stdin is closed so SSH, CI, and other one-shot commands cannot wait on an inherited pipe. Pass `--stdin` to forward an intentional pipe, or `--no-stdin` to close terminal stdin explicitly. ```bash printf 'hello\n' | nemohermes my-assistant exec --stdin -- cat ssh dgx-spark 'nemohermes my-assistant exec --no-stdin -- pwd' ``` OpenShell preserves line endings and quote characters inside each command argument, so inline scripts and heredocs can be passed as one argument after `--`. For example, a shell variable keeps the multi-line script in one argv element: ```bash script=$'cat <<\'EOF\'\nline one\nline two\nEOF' nemohermes exec -- bash -lc "$script" ``` NUL bytes are still rejected in command arguments. Line breaks are accepted only in command argv: `--workdir` remains single-line, and NemoClaw does not expose OpenShell request-environment injection on this command. | Flag | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--workdir ` | Working directory inside the sandbox. The directory is checked before the command runs; if it does not exist, NemoClaw reports `error: --workdir: does not exist inside the sandbox` and exits with status `1` without invoking the inner command. | | `--tty` / `--no-tty` | Allocate a pseudo-terminal; defaults to auto-detection (on when stdin and stdout are terminals) | | `--timeout ` | Timeout in seconds (`0` means no timeout) | | `--stdin` / `--no-stdin` | Force caller stdin forwarding or closure (default: inherit terminal stdin; close non-terminal or unavailable stdin). | ### `nemohermes agent` The `agent` wrapper rejects Hermes sandboxes with guidance for the Hermes HTTP API. Each Hermes sandbox exposes an OpenAI-compatible API inside the sandbox on its own port, which defaults to `8642`, so non-interactive use does not need a wrapper command. When another sandbox or a host listener already holds `8642`, the sandbox receives the next free port from `8642` through `8652`. The rejection message names that port and the `openshell forward start` command for it. Run `openshell forward list` to read the host bind for each of that sandbox's forwards. Forward the port and POST chat completions directly: ```bash openshell forward start --background 8642 my-hermes curl -sN http://127.0.0.1:8642/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model":"","messages":[{"role":"user","content":"What is 2+2?"}],"stream":true}' ``` ### Advanced Sandbox Maintenance Commands The following commands are available for targeted host-side maintenance, but they are not part of the top-level public command list. #### `nemohermes config get` Read the sanitized agent configuration from a sandbox. The output removes credential-bearing sections before printing. Use `--key` to read one dotpath and `--format` to choose JSON or YAML output. ```bash nemohermes my-assistant config get nemohermes my-assistant config get --key model --format yaml ``` | Flag | Description | | --------------------- | ----------------------------------------- | | `--key ` | Print one value from the sanitized config | | `--format json\|yaml` | Output format. Defaults to JSON | #### `nemohermes config set` Write one value into the agent configuration in a sandbox. The command validates every HTTP and HTTPS URL in the value, including URLs nested inside JSON objects or arrays. It pins an HTTP host to the validated IP address. Configuration changes are unavailable while shields are up, so lower shields with `nemohermes shields down` first. ```bash nemohermes my-assistant config set --key agents.defaults.model.primary --value nvidia/nemotron nemohermes my-assistant config set --key agents.defaults.timeoutSeconds --value 600 --restart ``` | Flag | Description | | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `--key ` | Dotpath to update in the config. Required | | `--value ` | Value to write. The command parses a JSON value when it can, and otherwise writes the text as a string. Required | | `--restart` | Restart a supported OpenClaw or Hermes gateway after writing | | `--config-accept-new-path` | Write a dotpath that does not already exist in the config | The command treats a dotpath that does not already exist in the config as a possible typo. An interactive run asks for confirmation before writing the new dotpath. A run without a TTY, or a run with `NEMOCLAW_NON_INTERACTIVE=1`, refuses the write. Pass `--config-accept-new-path`, or set `NEMOCLAW_CONFIG_ACCEPT_NEW_PATH=1`, to write the new dotpath without the confirmation. If the confirmation reaches the end of input, for example when you press `Ctrl-D` or run the command from a harness that closes stdin, the command exits non-zero without writing and repeats the same guidance. The command refuses to write `gateway` or any dotpath under `gateway.`, which holds credentials. For Hermes, the command validates the complete candidate configuration with the bundled Hermes schema before it writes configuration or integrity metadata. An incomplete structural object is rejected without changing the configuration or hashes. Private URLs remain rejected unless the existing Hermes configuration explicitly sets `security.allow_private_urls: true`. That opt-in allows private URLs for any Hermes configuration value. Public hostnames still receive DNS validation and pinning. Hermes can restart its gateway when it applies a configuration change. Use `--restart` when the command must request and verify that restart. `config set` changes `config.yaml` only. Hermes startup and rebuild can update managed `.env` keys and their integrity hashes without printing their values. #### `nemohermes shields` Manage the sandbox config lockdown posture from the host. Use `shields status` to inspect the current state, `shields up` to lock the sandbox config and restore the captured restrictive policy, and `shields down` to temporarily unlock the config for maintenance. For the full mutability matrix, refer to [Understand Runtime Changes](../manage-sandboxes/configure-sandboxes/understand-runtime-changes). ```bash nemohermes my-assistant shields status nemohermes my-assistant shields up nemohermes my-assistant shields down --timeout 5m --reason "maintenance" ``` | Subcommand | Description | | ---------------- | --------------------------------------------------------------------------------------- | | `shields status` | Show whether lockdown is configured, active, temporarily unlocked, or in error | | `shields up` | Lock the sandbox config and restore the saved restrictive policy | | `shields down` | Temporarily unlock the sandbox config. Supports `--timeout`, `--reason`, and `--policy` | If OpenShell rejects the permissive policy before it is applied, `shields down` returns an error and keeps the sandbox in the Shields up state. The command clears the provisional Shields down record and timer, and `shields status` remains `UP`. If that record cannot be cleared and NemoClaw writes the rejection marker, `shields status` derives `UP` from that marker. The auto-restore timer and transition remain the recovery authority. If the rejection marker also cannot be written, `shields status` reports the incomplete transition as an error. If a config path is unsafe, for example a symlink at the Hermes `config.yaml` path, `shields down` refuses that path before it weakens policy, writes a provisional Shields down record, or starts a timer. The command returns an error and `shields status` remains `UP`. If an unsafe path appears after the preflight and a provisional Shields down record already exists, the command restores the restrictive policy when it can but keeps the Shields down record until config protection is positively re-verified. This fail-closed behavior also applies when unlock fails after a partial mutation, and requires manual intervention if re-lock cannot be confirmed. If `shields up` reports that the config remains unlocked or drifted, confirm that the sandbox is running and ready, then retry `nemohermes shields up`. If the retry still fails, rebuild a known-good baseline with `nemohermes rebuild --yes`. Host-side config and inference writes, snapshot mutation, sandbox destruction, and shields transitions serialize per sandbox. Host-side gateway recovery uses the same per-sandbox serialization. For a current NemoClaw-managed Hermes image on the Docker driver, `shields status` is a recovery and reconciliation command, not only a display command. It first recovers any retained exact runtime provider state mutation, then applies and verifies the declared recursive posture. A result exits with status `0` only after the command verifies that posture. A status check can therefore complete work retained by an interrupted host process. If provider recovery restores lockdown while the persisted Shields posture still says mutable, status prints `ERROR (runtime-provider recovery restored lockdown)`, exits with status `2`, and tells you to retry the intended Shields transition. If live verification of a mutable default or timed Shields down posture fails, status prints `NOT CONFIGURED (DRIFTED...)` or `DOWN (DRIFTED...)`, exits with status `2`, and directs you to run `nemohermes shields up` to reconcile and verify lockdown. Status does not report `UP`, `DOWN`, or mutable-default with exit status `0` when the provider cannot verify the exact recursive posture. While an exact provider fence is active, ordinary direct-container, SSH, and OpenShell command transports are refused before a sandbox process starts. They report `Runtime provider state mutation owns direct-container execution for sandbox ''; retry after the provider fence is released.` Recover and retry as follows: 1. Let the active Shields or recovery command finish. 2. Run `nemohermes shields status`. 3. Retry the original command only after provider verification completes and the command exits with status `0`. Older managed Hermes images use the sealed-plan transition only when the current provider capability is proved absent. Custom images and legacy Dockerfile workflows remain on their existing transition contract and do not use `provider-state-mutation-v2`. Before `shields down` opens a new window, NemoClaw must revoke any stale auto-restore timer authority. If marker cleanup fails, the command reports `Cannot revoke stale auto-restore timer authority` and stops before policy capture, state writes, config unlock, replacement-timer startup, or audit writes. The sandbox retains its existing configuration and policy posture, and the stale timer authority remains. Resolve the reported timer-marker error on the trusted host, then retry `shields down`. When a timed shields-down window reaches its deadline, auto-restore closes the per-sandbox lifecycle deadline gate. The gate blocks new mutations and waits for the recorded live owner to release its exact lock generation before auto-restore restores lockdown. NemoClaw does not signal that process because portable process inspection cannot prove that all descendants stopped. An interactive command can take over an expired timer. Interactive recovery has separate transition-takeover and restoration phases. Each phase makes up to 7 attempts and waits 5 seconds between failures, for up to 30 seconds of retry delay per phase. Detached recovery uses one 7-attempt budget across deadline setup, main-generation publication, and restoration. The deadline gate remains closed during those attempts. If restoration cannot commit, NemoClaw attempts to record durable containment. If that containment commit also fails, NemoClaw retains any exact lifecycle and deadline gates it already owns. A state-directory failure that prevented gate publication also prevents normal mutation-lock acquisition. Correct the reported state-directory write failure, then run `nemohermes shields status` to resume recovery or receive exact-generation recovery guidance. When recovery cannot complete, an interactive command returns an error, or the detached timer exits with a failure status. NemoClaw also records durable containment when an owner exits before it can prove that the owner's descendants stopped, or when ownership becomes ambiguous. Durable containment, retained exact gates, or the fail-closed state-directory error blocks new mutations until you complete exact-generation operator recovery. Stop all NemoClaw processes for the sandbox, then follow the paths, identities, tokens, and removal order in the reported error. Verify each recorded generation is unchanged, remove only the exact stale generations first, and remove the exact containment generation last. Before a manual Shields transition replaces a policy, NemoClaw requires exact agreement among the sandbox registry, generated-policy record, and live gateway policy. `shields down` carries the proven managed MCP policy entries into the relaxed policy. Restoration removes snapshot-time managed MCP entries before it overlays current exact entries. If exact agreement is absent, a manual Shields transition refuses the replacement policy. At an expired deadline, auto-restore omits unproven managed MCP policy entries, restores lockdown, and records the omission count in its audit entry. An MCP server removed during the shields-down window stays removed. A surviving server keeps its recorded endpoint and address pins while its policy ownership remains exact. ### `nemohermes recover` Repair a stopped in-sandbox gateway and re-establish host-side forwards without opening an SSH session. Use this after a sandbox crash or whenever `nemohermes status` reports that the sandbox container or agent gateway is not running. For a stopped, non-paused Docker-driver container, `recover` starts the existing container before it waits for OpenShell readiness. It leaves a running or paused container unchanged. If Docker cannot start the container, `recover` continues to the readiness check and reports the resulting failure. `recover` waits up to 30 seconds to acquire the per-sandbox lifecycle lock. After acquisition, it holds the lock until gateway recovery and forward repair finish. For built-in OpenClaw and Hermes sandboxes, `recover` sends an authenticated lifecycle request through registry-scoped privileged direct-container control. The host selects the controller from the live container topology. In a direct root-entrypoint container, the request reaches the root PID 1 supervisor. In an OpenShell-managed container, the request enters the root-owned mode `0500` managed controller through a sanitized root exec while OpenShell remains PID 1. It does not use ordinary `openshell sandbox exec` or an in-sandbox manual relaunch as a fallback. When the root-owned managed controller attests two unchanged zero-supervisor process scans with a stable PID 1 and reports `SUPERVISOR_NOT_RUNNING`, a local Docker-driver sandbox with the legacy keepalive startup can enter a transactional container recreation. The recreation uses a credential-free managed startup command, pins the registered container identity, and retains the previous container for rollback. Before recreation, NemoClaw backs up the state directories and files declared by the agent manifest. NemoClaw waits for the exact replacement to pass managed gateway health and OpenShell re-registration before it restores state. After state restoration, it restarts the gateway in the exact replacement container and requires an authenticated `ok` result. It then runs the managed settle check. It commits only after the replacement identity, state restoration, gateway restart, and settle check pass. If OpenShell re-registration, state restoration, or a later gateway check fails, NemoClaw attempts to roll back the replacement. The primary dashboard or API host forward stays stopped. NemoClaw removes the temporary state backup after a successful restore or rollback. If state restoration and rollback both fail, it retains the backup and prints host recovery guidance. Mounted state remains available, but a committed swap does not retain other writable-layer changes. It is idempotent. When `recover` repairs a stopped built-in OpenClaw or Hermes gateway, it repeats the recovery action only for these exact transient results: * Status `1` with blank stdout and exactly one stderr line, `SUPERVISOR_BUSY`. * Status `137` with blank stdout and stderr. * Status `1` with blank stdout and exactly one stderr line, `Error response from daemon: Container is restarting, wait until the container is running`. For the Docker result, `` must be a 64-character lowercase hexadecimal ID that matches the selected registry-owned container. Recovery makes at most 11 controller attempts in total. It stops after 3 of those attempts return `SUPERVISOR_BUSY`. Managed settle confirmation treats exact `SUPERVISOR_BUSY` as inconclusive within its configured window. Status `137` and the Docker restart result remain terminal during that confirmation. The managed supervisor startup waiter accepts the two container-transition results within its separate 11-attempt bound. Unbound container IDs, reformatted Docker errors, status `137` with nonblank output, and other diagnostic results are terminal. NemoClaw treats `SUPERVISOR_UNAVAILABLE` as terminal because the managed controller uses it for integrity refusals, ambiguous discovery, and process-identity changes. It does not repeat the recovery action or treat the settle probe as inconclusive, and instead prints host-side restart and rebuild guidance. Other controller failures also stop immediately. If the gateway is already running, the command exits zero without force-restarting it; it can still re-evaluate supported safety checks and check or recover host-side forwards. Use [`nemohermes gateway restart`](#nemohermes-name-gateway-restart) when you deliberately need a running gateway to reload runtime configuration or plugins. ```bash nemohermes my-assistant recover ``` `recover` re-evaluates the documented Hermes secret boundary against `/sandbox/.hermes/.env` and the supervisor runtime environment on every run, including when the gateway is already healthy. If the file contains raw secret-shaped values (for example a pasted Telegram, Discord, or Slack bot token in place of the expected `openshell:resolve:env:` placeholder), the command exits non-zero and prints the offending key. The direct root-entrypoint supervisor stops a running gateway after this refusal, while the managed controller refuses before signaling the observed child. Replace each flagged value with the `openshell:resolve:env:` placeholder and re-run. The direct root-entrypoint supervisor verifies the strict root-owned config hash. The managed controller verifies that strict hash when both Hermes config inputs are root-owned and locked. Mutable config under the managed topology has no durable root-owned hash anchor and retains the same trust and time-of-check/time-of-use limits as managed cold start. If the boundary validator or supervisor helper is missing, recovery fails closed, names the sandbox, explains that `/sandbox/.hermes/.env` could not be re-evaluated, and leaves an otherwise healthy gateway untouched. Rebuild an older sandbox image with `nemohermes rebuild --yes` before retrying. While a NemoClaw cron restore gate exists, Hermes `recover` keeps the same lifecycle lock through restore validation and gate release. That controller call has a 130-second host timeout; the earlier 30-second limit applies only to lifecycle-lock acquisition. After gateway and forward recovery, Hermes `recover` also checks for a NemoClaw cron restore gate retained by an interrupted rebuild. It validates the restored cron jobs and scripts before it clears that gate, and it leaves an independent Hermes operator drain active. A validation failure leaves the NemoClaw gate in place so new Hermes turns and cron dispatch remain blocked. The privileged control path requires a running direct sandbox container that belongs to the named registry entry. Supported built-in images use either a direct root entrypoint or the OpenShell-managed process shape with OpenShell as PID 1 and exactly one nonroot `nemoclaw-start` supervisor. An arbitrary nonroot entrypoint that does not match the supported OpenShell-managed process shape fails with the `privileged control unavailable` failure layer. Kubernetes and other deployments without a matching direct container also fail with that layer. ### `nemohermes gateway restart` Force-restart the supported in-sandbox gateway process through the controller for the live container topology. Use this after runtime configuration or plugin changes that the agent reads only at gateway startup, such as Hermes Langfuse plugin settings. Unlike `recover`, this command restarts a healthy gateway instead of exiting after the health probe. ```bash nemohermes my-assistant gateway restart [--quiet|-q] ``` On success, the command reports that the gateway was restarted, health passed, and forwards were checked or recovered. It also checks the dashboard forward, messaging forward, and manifest-declared agent forwards. `--quiet` suppresses progress lines but still prints refusal diagnostics. In the direct root-entrypoint topology, PID 1 stops only the gateway child whose process ID and process start identity match the tracked child, applies the restart seal, and launches the replacement under the separate `gateway` UID. In the OpenShell-managed topology, the installed root controller verifies a stable OpenShell to `nemoclaw-start` to gateway process shape, holds a root-only lifecycle lock, publishes one root-owned exit authorization bound to the exact gateway process ID, kernel start identity, and live controller identity, pidfd-targets the observed child, waits for the nonroot entrypoint supervisor to respawn it under the sandbox UID, and proves the replacement listener and HTTP health. That managed process proof prevents PID reuse from redirecting the signal but cannot establish provenance against a malicious same-UID process or create gateway and agent UID isolation. For Hermes, the entrypoint supervisor also owns the dashboard process, internal API relay, dashboard relay, and gateway log stream. The managed nonroot supervisor continuously repairs those processes, stops an alive but deaf gateway after four consecutive failed health checks, and quarantines relaunch after five unexpected exits or failed replacement candidates within 60 seconds until sandbox recreation. That authorization keeps an authenticated host-requested exit out of the crash budget while its exact root controller remains live; it records host intent for the exit but does not claim that the host signal was the only possible cause in the shared-UID topology. The host repairs only the host-side OpenShell forwards after the supervisor reports a healthy gateway. For Hermes, both controllers validate `/sandbox/.hermes/.env` against the secret-boundary guard and validate the supervisor runtime environment before restart. The direct root-entrypoint supervisor verifies `/sandbox/.hermes/config.yaml` and `.env` against the root-owned strict hash and relaunches the process as the `gateway` user. The managed controller verifies the strict hash when both config inputs are root-owned and locked, but mutable managed config retains cold-start-equivalent trust and time-of-check/time-of-use limits. Neither controller recomputes a trusted strict hash to adopt direct in-sandbox edits. Use supported host commands such as `nemohermes config set` and `nemohermes inference set` for intended runtime configuration changes because those commands update the managed config metadata together. When a strict hash is available and does not match, the command reports the `config hash mismatch` failure layer. Hermes host config writes, shields transitions, and lifecycle seals share one root-only mutation lock. Config writes are bound to the digest of the matching read and atomically refresh the strict and compatibility hashes before the prior ownership and mode posture is restored. The shields transition keeps that lock through recursive filesystem updates, verification, and content-seal capture, and replaces sensitive inodes before lockdown. If a concurrent lifecycle request reports `SUPERVISOR_BUSY`, or a config or shields command reports `Hermes config mutation is already in progress`, wait for the active operation to finish and retry. Run `nemohermes shields down` before a Hermes config or inference change; these commands refuse to mutate a shields-up sandbox. The command can fail at these layers: unsupported agent, privileged control unavailable, supervisor not running, secret-boundary refusal, unsafe config path, config hash mismatch when a strict hash is available, MCP reconciliation refusal, relaunch quarantined, launch failure, health timeout, or forward recovery failure. `relaunch quarantined` means the in-sandbox supervisor stopped attempting relaunch after a startup refusal or repeated gateway exits, so restart and recovery report the supported repair, `nemohermes rebuild --yes`, instead of a retry. An older direct-container image without the matching supervisor or managed controller helper reports `privileged control unavailable` and requires `nemohermes rebuild --yes`. Ordinary OpenShell exec and manual in-sandbox relaunch are not fallback paths. Terminal agents do not have a gateway runtime and fail as unsupported. ### `nemohermes stop` Stop the sandbox's Docker container while preserving all of its state. Workspace files, credentials, network policies, the registry entry, and the OpenShell sandbox record stay in place. Use this to free CPU, memory, and GPU resources without destroying the sandbox; use [`nemohermes destroy`](#nemohermes-name-destroy) when you want to delete it instead. ```bash nemohermes my-assistant stop ``` For OpenClaw-managed gateways, the command first asks the in-sandbox gateway to shut down its channels gracefully; agent-managed gateways (for example Hermes) are supervised inside the sandbox and shut down with the container's stop signal. Then the container stops; a container stuck in a crash loop is stopped the same way, which also disarms its restart policy. After the container stops, NemoClaw attempts to stop that sandbox's host dashboard forward. If the container does not stop, NemoClaw leaves the dashboard forward running. The shared host gateway, tunnel services, and any local NIM inference container serve other sandboxes and keep running. Stopping an already-stopped sandbox succeeds and attempts to remove any leftover dashboard forward for that sandbox. The command controls the local container directly, so it is available for local-container drivers (the default Docker driver and the vm driver) and unavailable for remote drivers such as kubernetes; if the Docker daemon itself is unreachable, the command reports the outage instead of guessing at container state. ### `nemohermes start` Restart a sandbox container that was stopped with [`nemohermes stop`](#nemohermes-name-stop) or by a host reboot, then repair the in-sandbox gateway and host-side forwards the same way [`nemohermes recover`](#nemohermes-name-recover) does. ```bash nemohermes my-assistant start ``` Starting an already-running sandbox skips the container start and still runs the gateway and forward health checks. A paused container is unpaused. If the container was removed entirely, `start` fails and points you to `nemohermes rebuild`. Before it repairs the gateway and host forwards, `start` waits for OpenShell to report the sandbox in the `Ready` or `Running` state, using the same `300`-second budget and `NEMOCLAW_CONNECT_TIMEOUT` override as `connect --probe-only`. When that deadline expires, `start` keeps the existing container, exits non-zero, and prints the `NEMOCLAW_CONNECT_TIMEOUT` value to use on the next run. After the gateway and forward checks pass, `start` sends one inference request through `https://inference.local` using the sandbox's recorded provider and model. A gateway that answers the `/v1/models` probe can still reject an inference request or return an invalid result, so the command exits non-zero in either case. It prints the probe result, including the HTTP status when the route returned one, and points you to the sandbox doctor command. Each run sends one 16-token request through the stored provider credential, so `start` waits up to 30 seconds for it and consumes provider tokens on a hosted route. When the sandbox records no provider or no model, `start` skips the request and exits `0`. `doctor` still classifies an HTTP `401` or `403` route response as reachable, so correct the provider credential when `start` reports one of those statuses. ### `nemohermes status` Show sandbox-scoped status, health, and inference configuration for one registered sandbox. Use this form when you care about a specific sandbox's live OpenShell state, agent runtime, inference health, GPU proof, permissions, and recovery hints. Do not pass a sandbox name to `nemohermes status`; that command is the global all-sandbox/service overview. NemoClaw resolves the sandbox's recorded owning OpenShell gateway before querying live state. If another gateway is active, it selects the owner and queries again instead of trusting a result from the sibling gateway. For a `compatible-endpoint` route that uses `openai-completions`, the text output prints `Reasoning effort` as `low`, `medium`, `high`, or `endpoint-default`. The line is omitted for another provider or API family. Pass `--json` to emit a structured per-sandbox report instead of the text renderer. The JSON output includes at least `schemaVersion`, `name`, `found`, `agent`, `agentDisplayName`, `agentRuntime`, `dcodeAutoApprovalMode`, `model`, `provider`, `recordedRoute`, `liveRoute`, `routeDrift`, `phase`, `gatewayState`, `inferenceHealth`, `rpcIssue`, `hostGpuDetected`, `sandboxGpuEnabled`, `sandboxGpuMode`, `sandboxGpuDevice`, `openshellDriver`, `openshellVersion`, `policies`, `baselineExclusions`, `baselineExclusionStates`, `baselineExclusionTransition`, `failureLayer`, `terminalRuntimeHealth`, `servingProcessHealth`, and `dockerPaused`. `baselineExclusions` is an array of exact baseline keys recorded for durable replay and is empty when the sandbox has none. `baselineExclusionStates` reports each recorded key with its current verification state. The `excluded` state means the reviewed entry still matches the active agent baseline and the key is absent from the live OpenShell policy. Other states identify agent drift, changed or removed baseline content, an unreadable baseline or live policy, or a live policy that contains the excluded key. `baselineExclusionTransition` is `null` when policy state is settled; otherwise it identifies the interrupted `exclude` or `restore` key that must be reconciled before sandbox creation or recreation, rebuild, or cross-sandbox snapshot cloning. The schema-version `1` `model` and `provider` fields keep their established live-route meaning when the gateway route is readable. Use `recordedRoute` for the sandbox's durable provider and model and `liveRoute` for the gateway-global route. When the live shared route differs, text output prints both routes and JSON output sets `routeDrift.live`, `routeDrift.recorded`, and `routeDrift.canConnect`. When `routeDrift.canConnect` is `false`, `connect` cannot safely restore the recorded route because provider-global identity differs or required route or gateway metadata is incomplete. Refer to [Use Shared Gateway Routes](../inference/manage-inference/use-shared-gateway-routes) for the route-sharing workflow. `openshellDriver` and `openshellVersion` are always strings (falling back to `"unknown"` when the registry has no value), so consumers can rely on `typeof` checks. `agent` is always a string and reports `openclaw` when the registry records no agent for the sandbox. `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. `inferenceHealth.ok` reports whether the inference route returned a structurally valid result for one request sent from inside the sandbox. The result must match Chat Completions, Responses, or Anthropic Messages for the selected route. An empty body, malformed JSON, provider-error envelope, or wrong response shape reports `unhealthy`, even with a 2xx status. The probe captures at most 64 KiB and does not include the response body in diagnostics. The route probe treats any final HTTP status from `200` through `499` as reachable, so a route with an invalidated provider credential answers HTTP `401` while the route is up. The request uses the live gateway route's provider and model, and falls back to the recorded values when the live route is unreadable. When the live provider and model match the recorded route, the request also uses the sandbox's recorded API family, including `openai-responses`. During route drift, NemoClaw does not carry the sandbox's recorded API family to the live provider and model. Each run sends one 16-token request through the stored provider credential, so `status` waits up to 30 seconds for it and consumes provider tokens on a hosted route. When NemoClaw sends an inference request, `inferenceHealth.subprobes` reports the route probe result as the `route reachability` hop, so a failing verdict still shows that the route itself answered. `inferenceHealth.failureLabel` reports why the inference request failed: * `unauthorized` when the route rejected it with HTTP `401` or `403`. * `unhealthy` when the route returned another failing HTTP status or an invalid 2xx response body. * `unreachable` when the request returned no HTTP status, including a probe that could not run. A host-side upstream probe under `inferenceHealth.subprobes` stays a diagnostic and does not change `inferenceHealth.ok`, because the sandbox route is the one the agent uses. When the route probe failed, or the sandbox records no provider or no model, NemoClaw skips the inference request and `inferenceHealth` reports the route probe result alone. `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. For terminal runtime sandboxes, the command also checks cgroup OOM kill counters. If the counter records an OOM kill, text output prints `Runtime health: degraded (... OOM kill recorded)` and points you to `nemohermes rebuild`; JSON output reports `terminalRuntimeHealth.kind: "degraded"` with the OOM kill count and source counter path. For a present gateway runtime, text output prints `Serving process ( gateway): not checked`, and JSON output reports `servingProcessHealth: { "checked": false }`. The existing inference probes run in a fresh sandbox command, so they do not attest that the long-running gateway process has equivalent inference access. NemoClaw does not probe the serving process yet. For terminal runtimes, `servingProcessHealth` is `null` and the text output omits this line because there is no long-running gateway process. 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`), `failureLayer` is non-null, the authoritative in-sandbox inference route fails or cannot be probed, or a terminal runtime sandbox reports a recorded OOM kill. The alias form `nemohermes status --json` requires the sandbox to be registered locally; the canonical form `nemohermes 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. For a sandbox that owns managed llama.cpp, text output also reports the recipe ID, model digest, image reference, `https://inference.local/v1` endpoint, and lifecycle state. It does not print the managed API key or its fingerprint. The lifecycle state is one of these values: | State | Meaning | | ----------- | --------------------------------------------------------------------------------- | | `preparing` | The gateway-scoped owner exists, but `receipt.json` is absent. | | `running` | The exact receipt-owned container is running under the recorded Docker authority. | | `stopped` | The exact receipt-owned container exists but is stopped. | | `absent` | The finalized receipt exists, but its exact container is absent. | | `conflict` | The Docker authority or runtime identity differs from the receipt. | | `unknown` | NemoClaw cannot read or prove the state. | The managed llama.cpp check forces a nonzero exit for `absent`, `conflict`, or `unknown`. Other sandbox and inference checks can also make the command fail. Rerun the same `NEMOCLAW_PROVIDER=install-llama-cpp` and `NEMOCLAW_LLAMACPP_RECIPE` onboarding selection to recover a stopped or interrupted runtime. Inspect and correct an identity conflict before retrying. ```bash nemohermes my-assistant status nemohermes my-assistant status --json nemohermes sandbox status my-assistant --json ``` The command probes `https://inference.local/v1/models` from inside the sandbox, and when that probe reports the route reachable it sends one inference request over the same route. That inference request is the authoritative inference health check, and both checks exercise the route that agent traffic uses. The main `Inference` line reports one of these states: | State | Meaning | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `healthy` | The route returned a structurally valid result for the inference request. | | `unauthorized` | The route rejected the inference request with HTTP `401` or `403`. | | `reachable` | The route returned an HTTP status from `200` through `499` and NemoClaw did not send an inference request. | | `unhealthy` | The route returned HTTP `500` through `599`, another failing status, or an invalid 2xx response body. | | `unreachable` | The route had a transport failure, returned no final HTTP status (`000` or an interim `100` through `199`), returned an invalid status outside `100` through `599`, or the inference request returned no HTTP status. | | `not probed` | NemoClaw could not run the authoritative route probe from a reachable sandbox. | | `not verified` | NemoClaw could not verify the sandbox or gateway state, so it skips inference probing. | An authentication response on the route probe alone confirms that the route is reachable, not that provider credentials are valid. `nemohermes doctor` sends no inference request, so it reports an HTTP `401` or `403` route response as reachable and exits `0` where `status` reports `unauthorized`. The command can also print direct host-side provider checks such as `Inference (upstream)` and provider-specific subprobes. For supported remote providers, this diagnostic sends an authenticated request to the configured model and accepts only a recognized Chat Completions, streaming Chat Completions, or Anthropic Messages response. It uses a 3-second connection timeout, a 5-second total timeout, and an 8-token output limit. If the request reaches the time limit, NemoClaw reports the provider as `not probed` and leaves model health unverified instead of reporting it as unhealthy. These checks are diagnostic only and do not override the authoritative `inference.local` result or determine the command exit status. Local providers add host-side backend diagnostics. For Local Ollama, the command can also print an `Inference (auth proxy)` diagnostic when a proxy token is available. Use these diagnostics to identify a failing auxiliary hop after checking the main `Inference` line. 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 the `docker_unreachable` failure layer with the message `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 initial preflight records the `sandbox_container_stopped` failure layer and suppresses the host-side `Inference` probe. If the owning OpenShell gateway is healthy but no longer lists the registered Docker-driver sandbox, status attempts post-reboot recovery from the labeled container. It waits for Docker readiness, restores the in-sandbox gateway and host forwards, and refreshes preflight before probing inference. A successful recovery clears the stale stopped-container failure. When status finds the sandbox but cannot prove its agent delivery chain, it exits non-zero and reports the `sandbox_recovery_failed` state. Address the reported recovery layer, then run the displayed `nemohermes recover` command. If the sandbox's recorded dashboard port is also held by a foreign listener, the header escalates to the `sandbox_dashboard_port_conflict` failure layer with the message `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: