> 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. ## 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 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 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 [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from ] [--name ] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device ] [--agent ] [--agents ] [--tool-disclosure ] [--observability | --no-observability] [--control-ui-port ] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software] ``` For Hermes, use the alias or pass the agent explicitly: ```bash nemohermes onboard [options] nemoclaw onboard --agent hermes [options] ``` `--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`. #### `--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, and custom Dockerfile path recorded by the original run. 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. 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 unversioned development checkouts, NemoClaw tries the image tagged with the newest reachable release version from `origin` before source-commit images, 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`, `openshell gateway start --recreate`, 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 new automatic gateway upgrade path. For scripted installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1` to allow the installer 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. If an out-of-range gateway cannot be retired through a supported lifecycle command or the verified NemoClaw-owned gateway PID, the installer stops after backup with the sandbox backups preserved. If any registered sandbox cannot be backed up, the installer aborts before it changes the gateway. 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 a manually prepared upgrade, set `NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1` only after preserving every registered sandbox and retiring the old gateway. #### 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. After provider selection, the wizard reviews the provider, model, credential state, and sandbox name before registering inference. It then prompts for optional web search and messaging channels, builds and starts the sandbox, and asks for a **policy tier** that controls the default set of network policy presets applied to the sandbox. Three tiers are available: | Tier | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | 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`, or `open`; 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. 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 be 1 to 63 characters, lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number. 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. For Hermes sandboxes, do not use port `8642`; NemoClaw reserves it for the Hermes OpenAI-compatible API and rejects it 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. For Hermes, the backed-up paths come from `agents/hermes/manifest.yaml`, including `/sandbox/.hermes` state such as memories, sessions, skills, plugins, cron, logs, plans, workspace, messaging platform state, `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, warns on untested runtimes such as Podman, and prints host remediation guidance when prerequisites are missing. The preflight also enforces the OpenShell version range declared in the blueprint (`min_openshell_version` and `max_openshell_version`). 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. 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. Tune the wait via `NEMOCLAW_REUSE_HEALTH_POLL_COUNT` (default `6`) and `NEMOCLAW_REUSE_HEALTH_POLL_INTERVAL` (default `5` seconds). The poll count is clamped to a minimum of `1` so the probe always runs at least once, and the interval is clamped to a minimum of `0` (no sleep between attempts). #### `--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. If that directory contains a `.dockerignore`, onboarding applies those rules 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` keep working through v0.0.90. 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` before legacy support is removed in v0.0.91. 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 be 1 to 63 characters, lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number. Names that match a NemoClaw CLI command (`status`, `list`, `debug`, etc.) are rejected up front. ```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. Detection proceeds along two paths. The `nvidia-smi`-based paths (the primary `--query-gpu=name,memory.total,memory.free` probe and the unified-memory `--query-gpu=name` fallback) require `nvidia-smi` to succeed and, on hosts whose firmware does not classify as a known NVIDIA platform (DGX Spark, DGX Station, Jetson, or Tegra), additionally require that the GPU name does not match the placeholder family observed on the Windows-on-ARM WSL2 nvidia-smi shim (`JMJWOA-Generic-*`) and that either the host is not ARM64 Linux (the observed shim is Windows-on-ARM only) or the NVIDIA kernel driver is bound (`/proc/driver/nvidia/` present), so that placeholder shims on non-NVIDIA hardware are not mistaken for real GPUs. Jetson/Tegra hosts that ship without `nvidia-smi` continue to be detected via the devicetree firmware fallback (`/sys/firmware/devicetree/base/model`) or the Tegra device-node fallback (`/dev/nvhost-gpu`, `/dev/nvhost-ctrl-gpu`, `/dev/nvhost-ctrl`, or `/dev/nvmap`); both bypass the trust-tier gate above. Use `--no-gpu` to opt out when you want host-side inference providers only and do not need direct GPU access inside the sandbox. Use `--gpu` to require GPU passthrough and fail fast if an NVIDIA GPU is not detected. Use `--sandbox-gpu` or `--no-sandbox-gpu` to control only direct NVIDIA GPU access inside the sandbox. 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 the host group IDs that own `/dev/nvmap` and `/dev/nvhost-*` so the sandbox user can initialize CUDA. If the compatibility attempt fails, onboarding keeps its diagnostics and the failed sandbox in place and prints a manual cleanup 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. 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 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` defaults 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. `connect` does not pull or serve 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. 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 ``` The `--probe-only` flag waits for the sandbox to become ready, verifies or repairs its in-sandbox agent process and host-side forward, and exits without opening a shell. It rechecks the sandbox on its recorded OpenShell gateway after the readiness wait and never restarts the shared host gateway. Use it for health checks and scripted readiness probes. ### `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. Hermes sandboxes expose an OpenAI-compatible API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. 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 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 `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. When a timed shields-down window reaches its deadline, auto-restore can interrupt the exact process tree holding that transition and restore lockdown. Retry an interrupted command in a new shields-down window. ### `nemohermes recover` Repair a stopped in-sandbox gateway and re-establish host-side forwards without opening an SSH session. Use this after a direct sandbox container restart, a sandbox crash, or whenever `nemohermes status` reports the gateway is not running but the sandbox is alive. 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, retains the previous container for rollback, and commits only after managed gateway health and the settle check pass. The recreation preserves mounted sandbox state, but a committed swap does not retain changes stored only in the previous container's writable layer. It is idempotent. When `recover` repairs a stopped built-in OpenClaw or Hermes gateway, it repeats the recovery action only for an exit status of `1` with blank stdout and a sole nonblank stderr line equal to `SUPERVISOR_BUSY`, with at most three controller attempts. The same result is inconclusive during managed settle confirmation and can be probed again only within the configured settle window. 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. 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, launch failure, health timeout, or forward recovery failure. 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; only the container stops running. 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. The shared host gateway, tunnel services, and any local NIM inference container serve other sandboxes and keep running. Stopping an already-stopped sandbox succeeds without changes. 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`. ### `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. 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`, `failureLayer`, `terminalRuntimeHealth`, `servingProcessHealth`, and `dockerPaused`. 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. `failureLayer` is `null` when no preflight failure was detected and otherwise one of `docker_unreachable`, `sandbox_container_stopped`, or `sandbox_dashboard_port_conflict`; when set, `inferenceHealth` is suppressed to `null` so automation does not see a stale remote-provider healthy status during a local outage. `dockerPaused` is `true` when NemoClaw detects that the Docker-driver sandbox container is paused. In that case, text output keeps OpenShell's authoritative phase but prints a `docker unpause ` recovery hint instead of sending you directly to rebuild. 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. ```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 as the authoritative inference health check. This check exercises the same route that agent traffic uses. The main `Inference` line reports one of these states: | State | Meaning | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reachable` | The route returned an HTTP status from `200` through `499`. Authentication responses such as `401` and `403` confirm route reachability. | | `unhealthy` | The route returned an HTTP status from `500` through `599`. | | `unreachable` | The route had a transport failure, returned no final HTTP status (`000` or an interim `100` through `199`), or returned an invalid status outside `100` through `599`. | | `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 confirms that the route is reachable, not that provider credentials are valid. 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 command prints the `sandbox_container_stopped` failure layer with the message `sandbox container exists but is not running.` as the first line of stdout, suppresses the host-side `Inference` probe, and exits with a non-zero status. If the sandbox's recorded dashboard port is also held by a foreign listener, the header escalates to 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: