--- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "NemoClaw CLI Commands Reference" sidebar-title: "Commands" description: "Full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands." description-agent: "Includes the full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands. Use when looking up a specific `$$nemoclaw`, `nemohermes`, `nemo-deepagents`, `dcode`, or `/nemoclaw` subcommand, flag, argument, or exit code." keywords: [ "nemoclaw cli commands", "nemoclaw command reference", "nemo-deepagents commands", "dcode commands", ] content: type: "reference" --- The installer and supported CLI operations attempt anonymous completion telemetry to NVIDIA's fixed TEST receiver by default. Run `export NEMOCLAW_DISABLE_TELEMETRY=1` in this shell before installing or rerunning it to suppress collection and delivery. Repeat it in any new shell used for NemoClaw CLI commands. Refer to [Operation Telemetry](/user-guide/openclaw/security/best-practices#operation-telemetry) for details. The `$$nemoclaw` CLI is the primary interface for managing NemoClaw sandboxes. It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`). For guidance on when to use `$$nemoclaw` versus the underlying `openshell` CLI, refer to [CLI Selection Guide](cli-selection-guide). 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). The `nemo-deepagents` alias is the primary interface for managing Deep Agents sandboxes through NemoClaw. It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=langchain-deepagents-code bash`). Most commands in this reference use the same arguments and subcommands across agent variants. Use `nemo-deepagents` when you want Deep Agents 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 `$$nemoclaw` for the OpenClaw variant. OpenClaw is the default agent for `$$nemoclaw onboard` unless you select another installed agent with `--agent ` or set `NEMOCLAW_AGENT=`. Run `$$nemoclaw agents list` to see the installed agent names; for example, use `hermes` for Hermes or `langchain-deepagents-code` for LangChain Deep Agents Code. OpenClaw-specific sections below describe the `/nemoclaw` slash command, the OpenClaw dashboard URL, the OpenClaw gateway token, and OpenClaw config paths under `/sandbox/.openclaw`. Use `nemohermes` for the Hermes variant. It selects Hermes by default during onboarding and for other commands. Use `--agent hermes` during onboarding or set `NEMOCLAW_AGENT=hermes` when you need the same selection through another entry point. Hermes-specific sections below describe the 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 ``` Use `nemo-deepagents` for the Deep Agents variant. It selects `langchain-deepagents-code` by default during onboarding and for other commands. Use `--agent langchain-deepagents-code`, `--agent dcode`, or `NEMOCLAW_AGENT=langchain-deepagents-code` when you need the same selection through another entry point. Deep Agents-specific sections below describe the `dcode` terminal runtime, managed `/sandbox/.deepagents` config, and commands that launch the interactive TUI or headless runner. ```bash nemo-deepagents onboard # selects Deep Agents by default nemo-deepagents my-sandbox connect # connects to a Deep Agents sandbox ``` ## In-Sandbox Commands The `/nemoclaw` slash command is available inside the OpenClaw chat interface for quick actions: | Subcommand | Description | | ------------------- | ----------------------------------------------------------------- | | `/nemoclaw` | Show slash-command help and host CLI pointers | | `/nemoclaw status` | Show sandbox and inference state | | `/nemoclaw onboard` | Show onboarding status and reconfiguration guidance | | `/nemoclaw eject` | Show rollback instructions for returning to the host installation | Hermes does not use the OpenClaw chat slash command. Use the host-side `nemohermes` commands for lifecycle, status, policy, and inference operations. The in-sandbox Hermes integration installs the NemoClaw Hermes plugin, which exposes tools for status and environment information, plus an `on_session_start` hook. Deep Agents does not use the OpenClaw chat slash command. Use the host-side `nemo-deepagents` commands for lifecycle, status, policy, and inference operations. Inside the sandbox, use `dcode` for the interactive TUI and `dcode -n` for explicit headless automation. Add `--json` when automation needs the managed, versioned result envelope. ```bash dcode dcode -n "Summarize this repository" dcode -n "Summarize this repository" --json dcode status printf '%s\n' '{"worker":"worker-17"}' | dcode tools call-read-only worker_task_context --json ``` `dcode tools call-read-only TOOL --json` invokes one exact, coherently read-only managed MCP tool without model participation. It requires one JSON object on standard input and writes one bounded JSON result envelope. For the JSON schema, status and exit behavior, output limit, and read-only MCP call requirements, refer to [Run Deep Agents Code](/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code). ## Sandbox Command Scope Put the sandbox name before a sandbox action, for example `$$nemoclaw policy list`. If you omit the name for an action that requires one, NemoClaw prints the required form and exits before registry recovery. It lists registered sandboxes when available. For pending setup, wait for onboarding to finish or use `$$nemoclaw onboard --resume` after an interruption. A registered sandbox can share an action name; `$$nemoclaw doctor status` addresses a sandbox named `doctor`. The global `$$nemoclaw doctor` command remains available without a sandbox name. ## Hosted Installer Options The hosted installer accepts options after `bash -s --`. These options control installation and the onboarding run that follows it. ### `--defer-onboarding` Use this option only with `NEMOCLAW_AGENT=hermes` or `NEMOCLAW_AGENT=langchain-deepagents-code`. Leave `NEMOCLAW_PROVIDER` unset, or select the `build`, `cloud`, or `routed` NVIDIA hosted provider. Do not combine this option with a local model profile. If NVIDIA inference credentials are absent and no sandbox is registered, the installer installs NemoClaw and skips onboarding. It does not create an OpenShell provider or sandbox, and it does not report onboarding as complete. If a supported credential or registered sandbox exists, the installer follows the normal onboarding or recovery path. An invalid credential fails validation and does not select deferred onboarding. After the runtime process supplies one of these credentials, run the onboarding command for the selected agent: - Non-empty `NVIDIA_INFERENCE_API_KEY` - Non-empty `NVIDIA_API_KEY` - `NEMOCLAW_PROVIDER_KEY` containing a credential value, rather than a provider selector such as `build` or `routed` Credential presence selects normal onboarding; that path still validates the value. For the selected agent, run: - Hermes: `nemohermes onboard` - LangChain Deep Agents Code: `nemo-deepagents onboard` Set `NEMOCLAW_DEFER_ONBOARDING=1` to select the same installer behavior without the command-line option. ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | \ NEMOCLAW_AGENT=hermes \ bash -s -- --defer-onboarding ``` ### `--force-fresh-install` On Apple silicon macOS, remove every NemoClaw- and OpenShell-managed sandbox, gateway, credential, configuration file, and recovery record before reinstalling and starting fresh onboarding. This destructive reset keeps downloaded model caches, but the removed state cannot be recovered without an external backup. Unlike `--fresh`, it removes the existing managed installation instead of only requesting fresh onboarding state. Use the hosted installer so the selected candidate is staged outside the state it removes: ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | \ bash -s -- --force-fresh-install ``` The equivalent environment variable is `NEMOCLAW_FORCE_FRESH_INSTALL=1`. The installer rejects this option outside Apple silicon macOS and stops without deleting remaining state if the authoritative whole-host uninstall cannot complete. ### `--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=openclaw \ NEMOCLAW_AGENT=hermes \ NEMOCLAW_AGENT=langchain-deepagents-code \ 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` and `NEMOCLAW_MODEL` before onboarding. The dedicated vLLM onboarder accepts `NEMOCLAW_VLLM_MODEL` only when the catalog resolves it to the matching fixed recipe. It rejects a model that does not resolve to that recipe and all `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` values before it installs vLLM. Set `NEMOCLAW_VLLM_PORT` before installation to publish the fixed serving recipe on another host port. 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 `$$nemoclaw 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. ### `$$nemoclaw help`, `$$nemoclaw --help`, `$$nemoclaw -h` Show the top-level usage summary and command groups. Running `$$nemoclaw` with no arguments shows the same help output. ```bash $$nemoclaw help ``` ### `$$nemoclaw --version`, `$$nemoclaw -v` Print the installed NemoClaw CLI version. ```bash $$nemoclaw --version ``` ### `nemoclaw-acp` Connect an external Agent Client Protocol (ACP) client to a managed Hermes sandbox. The adapter sends ACP traffic through standard input and standard output, and writes diagnostics to standard error. ```bash nemoclaw-acp --sandbox [--gateway ] [--timeout ] ``` `--sandbox` is required. When the sandbox name is registered on more than one gateway, pass `--gateway ` to select its owning NemoClaw gateway. `--timeout` ends the ACP session after the specified positive number of seconds, up to `86,400`. Before the adapter starts the session, it revalidates the registered sandbox and its ready state under the sandbox lifecycle lock. It also revalidates the sandbox lifecycle generation, identity, and OpenShell gateway. It can select and, when required, start only that exact gateway when it is missing, unhealthy, or unreachable, or when a different gateway is connected. A conflicting or ambiguous gateway identity, authentication, schema, timeout, or other observation failure stops the adapter before gateway startup or session creation. The adapter preserves the remote `hermes-acp` exit status, including `255`. It reports an SSH transport failure separately when the remote session does not report an exit status. If NemoClaw cannot remove its temporary SSH configuration, it reports the retained directory and directs you to remove it before you run `nemoclaw-acp` again. That cleanup failure makes an otherwise successful session exit `1`; it does not replace a remote nonzero exit status. ### `$$nemoclaw 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 `$$nemoclaw ...` grammar, flags, shell choices, and locally registered sandbox names. If you omit the shell name, `$$nemoclaw 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 <($$nemoclaw completion bash) ``` For Zsh, source the generated script and add the same line to `~/.zshrc` for future sessions. ```zsh source <($$nemoclaw completion zsh) ``` For Fish, write the generated script to Fish's completions directory. ```fish mkdir -p ~/.config/fish/completions $$nemoclaw completion fish > ~/.config/fish/completions/$$nemoclaw.fish ``` Start a new shell session to refresh the cached sandbox names after creating or removing a sandbox. ### `$$nemoclaw config export ` Export a supported registered OpenClaw, Hermes, or LangChain Deep Agents Code sandbox as a credential-value-free `nemoclaw.nvidia.com/v1alpha1` `NemoClawConfig` document. Version 1 accepts valid empty messaging plans, including plans left after removing the last channel. It rejects plans that retain channels or messaging effects and writes no YAML or output file. The command reads the registry and current OpenShell state without changing the sandbox. It stops without writing output when required identity, policy, inference, or workload evidence is missing or inconsistent. If the source changes during observation, the command retries the complete observation once and stops without output if the retry also changes. Gemini config export stops with an unsupported-provider error because V1 cannot consume the Gemini document. The command writes no YAML and does not create or replace an output file, including with `--force`. Continue using the existing Gemini sandbox until V1 support is available. The command reads the provider endpoint from the sandbox's OpenShell gateway and compares it with the registered endpoint. For NVIDIA Endpoints, it verifies that the recorded NemoClaw-owned provider attachment matches the live provider, least-privilege profile, and fixed native endpoint. A custom NVIDIA provider profile or endpoint override cannot be included in an export. If OpenShell cannot supply the required evidence, the command stops without writing output. Write a file on Linux: ```bash $$nemoclaw config export my-assistant --output nemoclaw.yaml ``` Use `--output -` to write YAML to standard output on any supported host or in a pipeline: ```bash $$nemoclaw config export my-assistant --output - ``` | Option | Description | | ------------------------------ | -------------------------------------------------------------------------------------------------- | | `--output `, `-o ` | Required. Write YAML to a Linux file path, or use `-` for standard output. | | `--name ` | Set `metadata.name`. Use at most 40 lowercase letters, digits, or hyphens, starting with a letter. | | `--force` | Replace an existing regular file. The command refuses symbolic links and other file types. | | `--json` | Return a machine-readable result when writing a file. It cannot be combined with `--output -`. | Exports never contain credential values. They include credential environment-variable references only when the target configuration requires one. File output uses mode `0600`. Without `--force`, an existing destination is preserved and the command fails. With `--force`, publication checks that the existing destination is a regular file before ordinary atomic replacement. With `--json` and file output, the version 1 result includes `sourceSandbox`, `outputPath`, `documentDigest`, and `specDigest`. Export validates retained corporate certificate authority (CA) state but omits the CA bundle and digest from YAML. When retained CA state is present, a successful export reports that omission on standard error. Export does not change the source sandbox's trust. Before deploying the YAML, prepare the destination: - Supply values for `credential.env` references through the destination command's environment. Keep credential values out of YAML. Unset exported credentials after the destination command finishes. - If `network.proxy` is present, ensure its host and port are reachable from the destination sandbox. Export does not install the proxy. - Review destination CA trust requirements before deployment. The exporter refuses sources that require host proxy credential replay. Experimental runtime identity is not supported by this export command. For its separate OpenClaw workflow, refer to [Configure Experimental Runtime Identity](/user-guide/openclaw/reference/configure-runtime-identity). The v0 command projects verified source state into the pre-release v1alpha1 YAML shape. Managed OpenClaw and Hermes exports omit `image` so v1 applies its managed image default. If staging cleanup fails, the diagnostic identifies the temporary file and its original directory by device and inode when that evidence is available. The directory can have moved from the requested output location. Before manual removal, use `stat` to verify both identities and confirm that the temporary entry is a regular file. If either identity cannot be verified, do not remove files by name alone. Do not remove the requested output file to clean up a temporary link. Version 1 exports Docker-managed OpenClaw sandboxes and canonical managed Hermes or LangChain Deep Agents Code sandboxes in the default workspace. Supported sandboxes use hosted external inference or the native NVIDIA hosted provider with its default endpoint, an immutable managed image, a NemoClaw-owned gateway, and an explicit representable policy. OpenClaw exports for attached Ollama with a managed proxy and the fixed managed vLLM profile include a named service with `image: null`. Replace only that value with an official, immutable, compatible v1 runtime image before v1 parsing or planning. Other local inference and Podman exports remain deferred. Deep Agents export requires hosted OpenAI Completions inference and explicitly disabled automatic approval, observability, and web search. It emits the immutable image as `image.ref`, the `deepagents` harness, and one `agent`. The command rejects other Deep Agents settings instead of omitting them. When a managed OpenClaw sandbox uses Brave Search, the export includes its `webSearch` integration and the `BRAVE_API_KEY` environment-variable reference, never the key. Managed OpenClaw and Hermes sources can also export Tavily with a `tavily-search` integration, the `TAVILY_API_KEY` reference, and a grant for the primary agent. Export verifies the source's provider and profile binding, including the Hermes-specific `tavily-hermes-v1` profile. Missing or mismatched search evidence prevents publication. Disabled search remains ungranted. Hermes with Brave and search-enabled Deep Agents sources remain unsupported. When retained managed proxy settings differ from the default, the export includes the validated host and port under `network.proxy`. For hosted OpenClaw inference, the export preserves context-window, maximum-token, reasoning, and reasoning-effort settings when omitting them would change the target's effective behavior. It preserves nondefault agent timeout and heartbeat settings under `execution`. The command rejects a managed OpenClaw sandbox with secondary agents and produces no document. Secondary-agent export remains deferred until the v1 schema defines that representation. For OpenClaw, it retains the managed dashboard marker because omitting it disables the target dashboard; the default marker includes port `18789` while the loopback bind remains implicit. When managed OpenClaw uses direct tool disclosure, the export includes `tools.disclosure: direct`. It omits the default progressive disclosure setting. When OpenClaw conversation diagnostics are enabled, the export includes the fixed local OTLP endpoint, service name, and sample rate under agent observability. It never includes collector credentials. Before applying the export, run an OTLP/HTTP collector on port `4318` of the destination host. The sandbox must reach it as `host.openshell.internal:4318`. The export does not install or configure that collector. Verify trace delivery after applying the configuration. It omits settings only when the v1 target has the same effective behavior without them. Hermes export fails when Hermes tool gateways are enabled. It preserves Hermes dashboard and in-browser TUI behavior, including explicit disabled values when omission would enable them, plus nondefault API and enabled-dashboard ports. For a disabled Hermes dashboard, export writes `interfaces.dashboard.enabled: false` and omits the recorded dashboard port because v1 rejects a port on a disabled dashboard. The retained dashboard URL must be `http://127.0.0.1:` with a port from `1024` through `65535`; a retained `browserUrl` must match it. The registry `dashboardPort` must match the URL port, except that it may be absent for port `18789`. Export rejects other URL forms, invalid ports, and mismatches. The default API port is omitted. It exports Hermes API-key authentication only when the retained authentication proof matches the managed Hermes provider, OpenAI-compatible API, endpoint, and `NOUS_API_KEY` credential reference. The exporter validates that source binding, then emits API-key authentication without a provider reference because v1 derives the association from the provider configuration. OAuth authentication and other unsupported profiles fail with a diagnostic instead of producing an incomplete document. ### `$$nemoclaw 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 $$nemoclaw resources [--json] ``` If the gateway is not running, Kubernetes allocatable fields are omitted and host CPU/RAM totals are still shown. ### `$$nemoclaw 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 $$nemoclaw host probe [--json] ``` For capability IDs, evidence bounds, and compatibility guidance, refer to [System Readiness](system-readiness). ### `$$nemoclaw agents list` List the installed agent runtimes that can be selected with `$$nemoclaw 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 $$nemoclaw 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 ``` ### `$$nemoclaw 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 $$nemoclaw profiles list ``` Use `--json` for machine-readable output with the same profile fields. ```bash $$nemoclaw profiles list --json ``` Use the stable `id` value with `$$nemoclaw onboard --profile `. Display names are accepted when they identify exactly one profile, but stable IDs are suitable for scripts and automation. ### `$$nemoclaw onboard` Run the interactive setup wizard (recommended for new installs). The wizard creates an OpenShell gateway, registers inference providers, selects the exact managed image (or builds an explicit custom Dockerfile), and creates the sandbox. Use this command for new installs and for recreating a sandbox after changes to policy or configuration. ```bash $$nemoclaw onboard [--profile ] [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--apf-interceptor] [--gpu | --no-gpu] [--from | --from-image @sha256:] [--name ] [--host-mount ] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device ] [--vllm-gpu-device ] [--agent ] [--agents ] [--tool-disclosure ] [--dcode-auto-approval ] [--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] ``` For Deep Agents, use the alias or pass the agent explicitly: ```bash nemo-deepagents onboard [options] nemoclaw onboard --agent langchain-deepagents-code [options] ``` `--agent` accepts the canonical manifest names from `$$nemoclaw agents list` plus common aliases. For example, `nemohermes` resolves to `hermes`, while `dcode`, `deepagents`, `deepagents-code`, and `langchain` resolve to `langchain-deepagents-code`. #### External Component Onboarding On Linux, OpenClaw and Hermes can register one experimental external host component during fresh onboarding with a NemoClaw-managed Docker-driver gateway. Create the declaration before onboarding and use a new explicit sandbox name. NemoClaw rejects resume, recreation, reuse, repair, and externally supervised gateways. For the declaration, fixed interceptor settings, activation protocol, incomplete-state handling, and credential boundary, refer to [Register an External Component During Onboarding](../deployment/register-external-component). #### `--profile ` Select one serving profile from `$$nemoclaw 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 $$nemoclaw 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_LLAMACPP_RECIPE`, `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 `$$nemoclaw profiles list` to inspect an incompatibility reason before onboarding. The flag selects managed vLLM and managed llama.cpp profiles. A managed llama.cpp profile installs the recipe that the profile declares, including an explicit-only profile that the interactive provider menu does not list: ```bash $$nemoclaw onboard --profile llama-cpp.dgx-spark-gb10.single.muse-glimmer-30b ``` 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, declared model, served model alias, runtime image, support state, and download estimates before confirmation. A managed vLLM or managed llama.cpp profile installs during provider selection, before that screen. Its installer declares the selected profile ID, recipe, runtime image, model, and pinned model download size before acquisition. Managed vLLM also declares the pinned image download size when the image is not cached on the host. The managed vLLM confirmation prompt follows that declaration. When onboarding reuses a running vLLM server, its `/v1/models` response must match the requested profile's served alias or declared model root. Otherwise, onboarding stops before it records a route that the profile does not declare. Reusing a running vLLM server does not record the requested profile's provenance. For a sandbox created with a managed vLLM or llama.cpp installation, 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. If policy application stops or OpenShell refuses the write, `--resume` reuses the selected presets for the same sandbox. NemoClaw checks the sandbox identity and preset availability before it reapplies the selection. It clears the saved selection only after live policy readback confirms the presets. If a saved preset is unavailable, policy recovery stops without silently removing it; use `--fresh` to discard that selection and choose a new policy. If the sandbox identity changed, preserve the reported state and inspect the sandbox before starting a new onboarding attempt. OpenClaw onboarding does not enter the `complete` state until NemoClaw proves that the local CLI operator pairing is settled. Onboarding first observes the canonical local CLI device. If the verified device has pairing-only or pairing/read permissions and needs write access, the host runs one bounded request producer on the owning gateway. This includes a matching CLI device whose connection metadata was refreshed by a probe. The in-sandbox watcher is the only component that approves the onboarding upgrade. The host observes through any same-device pending state and verifies the final settled state without sending an approval. Before the configuration review, NemoClaw records the sandbox name and the selected provider and model as an incomplete choice. For a custom endpoint, the choice also includes the endpoint URL, the API family, and the name of the credential environment variable, but not the credential value. If onboarding stops at the review prompt, an interactive `--resume` run shows the prompt again. A custom-endpoint choice recorded by an earlier NemoClaw release has no endpoint URL or API family. An interactive `--resume` run asks you to choose the provider and model again. A non-interactive `--resume` run stops with an incomplete custom-route error. In that case, run `$$nemoclaw onboard --fresh` and make the selection again. No sandbox exists yet at this point, so you do not need to remove one. 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 `$$nemoclaw 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 `$$nemoclaw onboard --resume`. During finalization, NemoClaw stops onboarding when it cannot complete the process check or a required secret-boundary check refuses. It does not report the sandbox as ready. Run `$$nemoclaw doctor`, correct the reported condition, then run `$$nemoclaw onboard --resume`. During finalization, NemoClaw stops onboarding when it cannot complete the process check or a required secret-boundary check refuses. It does not report the sandbox as ready. For a Portable Hermes receipt and registry authority mismatch, preserve both records and follow [Portable Hermes receipt and registry authority do not match](troubleshooting#portable-hermes-receipt-and-registry-authority-do-not-match). Do not resume onboarding for that authority failure. For another resumable finalization failure, run `$$nemoclaw doctor`, correct the reported condition, then run `$$nemoclaw onboard --resume`. #### Inspect retained sandbox recovery If onboarding cannot complete after sandbox creation, NemoClaw preserves the sandbox. When available, NemoClaw records and prints the create-attempt label as the exact `ai.nvidia.nemoclaw.create-attempt=` selector. When available, NemoClaw also records a durable identity fingerprint for recovery. Automatic and explicit resume, reuse, recreation, and fresh onboarding with that sandbox name remain blocked. Save any files you need from the retained sandbox before running `destroy`. The command can clear the agent's native home before its final identity check, even if a later check blocks deletion. A successful delete permanently removes the sandbox and its workspace files. OpenShell deletes by mutable sandbox name. A matching identity check cannot prevent another gateway client from replacing the sandbox between the final check and deletion. Use live retained cleanup only when no independent OpenShell client can replace this sandbox name during cleanup. Run `$$nemoclaw destroy` to attempt retained cleanup and reconcile verified residual state. Use the result from `destroy` to choose the next action: - If OpenShell reports the sandbox present and its durable identity matches the recovery record, `destroy` checks that identity during cleanup and immediately before deletion. It can delete the retained sandbox. A failed check or deletion preserves the recovery record. If you cannot prevent another gateway client from replacing the sandbox name during cleanup, use a different explicit name instead. - If OpenShell cannot determine whether the sandbox is present, `destroy` reports unknown presence, removes no resources, and preserves the recovery record. Correct the OpenShell gateway or list failure, then rerun `destroy`. - For the existing residual-cleanup path, `destroy` selects one retained record from its registry generation, gateway, create-attempt evidence, and available identity fingerprint. Cleanup requires the owning OpenShell gateway to confirm sandbox absence. Before pending identity publication, it can instead select one record with a durable identity fingerprint when the pending reservation belongs to the recorded onboarding session, the saved session recovery evidence matches the record, and the registry has no lifecycle identity evidence. Provider and Docker cleanup then apply their own immutable identity checks. `destroy` removes only qualified residual resources and clears the matching recovery record only after verified cleanup. - If the recovery record is ambiguous or immutable runtime-identity verification fails, cleanup stops and the record remains. For Docker-backed sandboxes, a foreign container, changed Docker identity, or failed Docker probe has the same fail-closed result. If `destroy` reports identity drift after provider cleanup, inspect the reported detached provider attachments. Before restoring them, stop other OpenShell clients from replacing this sandbox name. Verify the retained sandbox's durable identity and confirm that the detached attachments belonged to it. Only then rerun the owning provider setup workflow to restore those attachments. If you cannot prevent replacement or verify attachment ownership, leave the attachments untouched and use a different sandbox name. Keep the recovery record and retry `destroy` only after resolving the identity drift. If OpenShell did not return a durable identity fingerprint, `destroy` cannot authorize deletion of a live sandbox. For normal recovery, `destroy` can clear local recovery metadata on native Linux with default Docker when no lifecycle identity was published. It requires exactly one matching retained record, a recorded Docker ownership marker, and sandbox absence confirmed by the owning gateway. Docker must report no matching containers or managed state volumes. When the record includes ownership captured before creation, recovery rechecks the original Docker daemon, gateway binding, and any remaining reservation owner. Otherwise, it requires a Docker ownership marker predating the recovery record and, while a reservation remains, its matching recovery-only session. Sandbox-scoped providers or additional resource ownership block recovery. Use the failed onboarding attempt's gateway port to select its state root, for example: ```bash NEMOCLAW_GATEWAY_PORT=19260 $$nemoclaw destroy --yes ``` Success clears the matching recovery metadata and releases the sandbox name without removing runtime resources. If a local metadata write fails, resolve the reported write error. Then rerun the same command with that port, even if the reservation was removed. If NemoClaw could not save recovery evidence, preserve the registry entry and terminal output. This fail-closed record keeps only the affected sandbox name unavailable. This command does not accept externally supplied identity authority. To onboard another sandbox while the record remains unresolved, supply a different explicit name: ```bash $$nemoclaw onboard --name ``` `--fresh` alone does not clear the recovery record or permit reuse of the retained sandbox name. OpenClaw sessions also record the web search selection, messaging selection and non-secret settings, and resource profile. When the saved session includes prompt checkpoints, resume skips each completed group and continues at the first incomplete choice. Resume reuses a valid saved resource profile unless `NEMOCLAW_RESOURCE_PROFILE`, `NEMOCLAW_CPU`, or `NEMOCLAW_RAM` is set. If the saved resource profile contains an invalid percentage, resume discards it and selects a resource profile again. `NEMOCLAW_RESOURCE_PROFILE`, `NEMOCLAW_CPU`, or `NEMOCLAW_RAM` supplies the replacement when set. Otherwise, interactive resume shows the resource profile menu when the blueprint defines named resource profiles, and uses OpenShell default resources in non-interactive mode or when no named profile exists. Legacy sessions without those checkpoints may repeat choices whose completion cannot be proven. Raw web search and messaging credentials are never written to the onboarding session. Resume skips their secret prompts when the same session recorded a successful OpenShell provider registration and OpenShell still reports the exact expected name, type, and credential keys. If the session lacks that registration receipt, the provider is missing, or its binding does not match, interactive resume requests the credential again; non-interactive resume preserves the completed choice, reports the required environment variable, and exits so you can export it before retrying. 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 `$$nemoclaw 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 startup setting. Use `$$nemoclaw rebuild` when you want NemoClaw to recreate the sandbox from its recorded registry metadata without changing those selections. Before reserving an inference route, onboarding can release a foreign-session route-only reservation while it holds the onboarding lock. For an already published sandbox on the gateway selected in the current session's checkpoint, it can transfer a foreign pending reservation to the new session while retaining the sandbox data. The row remains pending until normal onboarding finalization, so reclaiming it does not publish an unverified inference route. It preserves the current session's reservation and any row that has gained verified sandbox-create authority. A published row remains unchanged when its gateway differs from the selected authority or that authority is unavailable. Without the lock, it preserves the foreign reservation. #### `--apf-interceptor` Use this option to request sandbox creation without a NemoClaw-supplied policy. This option supports providerless onboarding only; NemoClaw does not configure an inference provider, model, or credential provider in this mode. If NemoClaw's prepared plan contains any provider, it exits before it: - Creates the sandbox. - Registers or changes credentials. - Creates, updates, or deletes providers. The option requires these conditions: - Start a new onboarding session. Use `--fresh` when a saved onboarding session exists. - Select a sandbox name that has no registry entry or live OpenShell sandbox. - Keep the active global policy absent. - Do not combine the option with `--resume` or `--recreate-sandbox`. NemoClaw omits a caller policy from every sandbox creation attempt. After creation, NemoClaw binds the returned durable sandbox identity and verifies its effective policy. The policy must be sandbox-scoped and contain every policy entry required by the prepared configuration. NemoClaw stores no policy owner, receipt, or desired state; later policy commands read OpenShell directly. This verification does not establish that APF injected the policy. With one [registered external component](../deployment/register-external-component#select-interceptor-supplied-policy), the component supplies policy through the existing OpenShell interceptor contract. Required providers must resolve through existing OpenShell mechanisms before activation. NemoClaw activates the component only after verifying immutable sandbox identity and effective policy, then verifies them again after the response. Missing or invalid policy does not trigger a fallback to NemoClaw policy or ordinary onboarding. Registration alone does not select this option. ```bash $$nemoclaw onboard --fresh --apf-interceptor --name my-apf-sandbox ``` If post-create verification or native GPU fallback fails after OpenShell may have created the sandbox, NemoClaw preserves the incomplete sandbox because automatic deletion would use its mutable name. Follow the [retained-sandbox recovery procedure](#inspect-retained-sandbox-recovery); its OpenShell-absence and immutable runtime-identity requirements also apply to APF creation. For Docker-backed APF creation, its Docker container-identity requirement also applies. This onboarding mode does not support `--resume` or `--recreate-sandbox`, regardless of whether sandbox creation began. After destroy completes, repeat the original command with `--fresh`. #### `--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` 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`. New sandboxes default 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. A fresh managed OpenClaw sandbox using local Ollama or vLLM defaults to `direct` instead. The accepted Deferred N1x managed-vLLM preview for `nvidia/Qwen3.6-35B-A3B-NVFP4` defaults to `progressive`. These exceptions apply only to the first creation for that session. Existing sandbox state and explicit `--tool-disclosure` or `NEMOCLAW_TOOL_DISCLOSURE` selections take precedence. To change an existing sandbox, recreate it explicitly: ```bash $$nemoclaw onboard --name my-assistant --recreate-sandbox --tool-disclosure direct ``` Recreation without an explicit flag or environment value 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. #### `--dcode-auto-approval ` Choose the managed Deep Agents Code auto-approval capability during onboarding. A new sandbox defaults to `disabled`. Omitting the flag preserves the sandbox registry’s recorded capability, including a previously disabled capability, during resume or recreation. `thread-opt-in` permits explicit activation inside Deep Agents Code; onboarding does not activate an approval mode or run `dcode -y`. `thread-opt-in` is rejected for other agents and custom images. Pass `--dcode-auto-approval disabled` to clear a recorded capability when switching agents. Before sandbox registration, resume preserves the explicit choice saved in the onboarding session. An explicit capability change for an existing sandbox requires recreation through the existing onboarding lifecycle. See [Configure Thread Auto-Approval](../manage-sandboxes/operate-sandboxes/run-deep-agents-code#configure-thread-auto-approval) for activation, status, and revocation. #### `--observability` and `--no-observability` Enable backend-neutral trace export for a LangChain Deep Agents Code sandbox. During initial onboarding, pass `--observability` with the Deep Agents alias. When you use the generic `nemoclaw` entry point, combine it with `--agent langchain-deepagents-code`. NemoClaw rejects the positive flag for OpenClaw and Hermes sandboxes. Use `--no-observability` when you need to clear a recorded Deep Agents Code choice before switching the resumed session to another agent. ```bash $$nemoclaw onboard --observability nemoclaw onboard --agent langchain-deepagents-code --observability ``` The flag is off by default. When enabled, NemoClaw records the choice with the onboarding session and sandbox, adds the `observability-otlp-local` policy preset on supported policy tiers, and preserves the choice across resume and rebuild operations. An explicit `--observability` or `--no-observability` choice updates a resumed onboarding session. The Restricted tier suppresses automatic application of the preset. An operator can add it manually after reviewing the additional egress, but the next Restricted onboarding or rebuild reconciliation removes it. The explicit opt-in can export bounded prompts, responses, tool arguments, tool results, and operational metadata. Treat trace payloads as sensitive application data. The managed capture applies size, depth, item-count, recognized-key, and exception-text safeguards, but it does not detect secrets embedded in ordinary content values. Deep Agents Code sends OTLP/HTTP protobuf traces to the fixed local endpoint `http://host.openshell.internal:4318/v1/traces`. The OTLP library adds standard transport headers, but the sandbox cannot configure operator-supplied custom or authentication headers, a remote endpoint, backend credentials, or a backend. Changing this setting on an existing sandbox requires a new sandbox process so the startup environment matches the recorded choice. Use the transactional rebuild flags so NemoClaw transfers the complete native home and workspace, preserves managed MCP providers and adapter state, recreates the sandbox, and restores the transfer. ```bash $$nemoclaw my-dcode rebuild --observability --yes $$nemoclaw my-dcode rebuild --no-observability --yes ``` Removing the `observability-otlp-local` policy stops delivery immediately but does not clear the recorded opt-in. A later rebuild restores the preset on Balanced and Open tiers, while Restricted continues to suppress it. For policy recovery and the host-side LangSmith exporter example, refer to [Set Up Deep Agents Trace Export](/user-guide/deepagents/monitoring/set-up-deepagents-trace-export). Review [Understand Deep Agents Trace Export](/user-guide/deepagents/monitoring/understand-deepagents-trace-export) for the privacy boundary, [Verify Deep Agents Trace Export](/user-guide/deepagents/monitoring/verify-deepagents-trace-export) for delivery checks, and [Manage Deep Agents Trace Export](/user-guide/deepagents/monitoring/manage-deepagents-trace-export) for lifecycle operations. 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 $$nemoclaw onboard --recreate-sandbox NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1 $$nemoclaw 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. For legacy Dockerfile workloads, 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. Managed-image workloads do not consult base-image overrides and reject the operation when the applicable override variable is set. 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 `$$nemoclaw 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 `$$nemoclaw onboard`. Use `--fresh` to ignore any saved onboarding session and restart the wizard from scratch. This is useful after an interrupted `$$nemoclaw onboard` run when you want to discard saved state instead of continuing it with `--resume`. The installer detects existing sandbox sessions before onboarding and prints a warning if any are found. To make the installer abort instead of continuing, set `NEMOCLAW_SINGLE_SESSION=1`: ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_SINGLE_SESSION=1 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 and macOS, if installed OpenShell lifecycle commands cannot retire the gateway, the installer uses verified NemoClaw-managed service or PID-file evidence for the supported recovery path. For the default gateway on port `8080`, Linux recovery first checks a verified active `nemoclaw-openshell-gateway.service`, while macOS recovery first checks a verified active Homebrew gateway service. Both paths then check a verified NemoClaw-managed gateway PID file for any configured gateway port. When a macOS PID file names a process that is no longer running, the installer removes the stale PID file only after `lsof` reports no listener and no diagnostic output. If `lsof` is unavailable, reports permission or other diagnostics, or produces inconsistent listener results, the installer stops before retiring the gateway and preserves the PID file, OpenShell registration, and sandbox backups. 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`. On macOS, if the verified Homebrew installation does not resolve executable OpenShell CLI and gateway binaries, the installer also stops before recovery and preserves the backups and prepared recovery state. It does not fall back to a stale user-local OpenShell binary. 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 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 confirmed recovery, the installer skips generic onboarding unless DGX Station reconciliation remains necessary. Required DGX Station reconciliation still passes host admission before onboarding. For any registered-sandbox upgrade that you prepare manually, use the current release CLI. If the installer has not already reported that it prepared the current CLI, start the supported automatic flow first: ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1 bash ``` That flow prepares the current CLI before it replaces OpenShell. If it completes, do not run the manual steps below. Continue manually only when the automatic flow stops after preparing the CLI or a support workflow directs you to this recovery path. Use the prepared current CLI to require strict backup and retire all applicable registered legacy forwards before you retire the old gateway. Strict backup can report a confirmed stranded registry sandbox without creating a backup for it because both the selected gateway and the container provider prove that no sandbox runtime remains. That record requires the cleanup or recreation action printed by `$$nemoclaw backup-all`, but it does not block a prepared upgrade after the strict command succeeds: ```bash selected_port=8080 gateway_name=nemoclaw retire_legacy_forwards_flag=--retire-legacy-forwards NEMOCLAW_GATEWAY_PORT="$selected_port" NEMOCLAW_REQUIRE_ALL_SANDBOX_BACKUPS=1 $$nemoclaw backup-all "$retire_legacy_forwards_flag" && \ openshell gateway destroy -g "$gateway_name" ``` For a non-default gateway, replace `8080` with its port and set `gateway_name` to `nemoclaw-`. If an older OpenShell release rejects the named destroy command for the default `nemoclaw` gateway, run `openshell gateway destroy` instead. Do not substitute `openshell gateway remove`: removal can unregister a gateway without stopping its process. Set `NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1` only after the command pipeline exits successfully. Confirm that the strict backup summary reports `0 failed, 0 skipped` and that the `Legacy dashboard forwards:` summary appears before gateway destruction. A confirmed stranded record has no backup to reuse; complete the reported cleanup or recreation action during recovery. If backup, forward retirement, or gateway retirement fails, resolve the failure while the completed backups remain intact. This environment variable asserts that strict backup, legacy-forward retirement, and gateway retirement are complete, so the installer skips that repeated preparation 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="$selected_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`. 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 `$$nemoclaw setup` command is deprecated; use `$$nemoclaw onboard` instead. On a qualified DGX Spark, the provider menu lists compatible experimental managed llama.cpp profiles with automatic selection in descending YAML priority order. During interactive onboarding without an explicit provider request, the menu ignores `NEMOCLAW_LLAMACPP_RECIPE` and `NEMOCLAW_SERVING_PRESET` and marks the unique highest-priority compatible profile as `(recommended)`. The recommended profile appears as **Managed llama.cpp: NVIDIA Nemotron 3 Nano 30B-A3B on one DGX Spark (recommended)**. The explicit-only Meta Muse Glimmer profile does not appear in the menu; select it with `--profile llama-cpp.dgx-spark-gb10.single.muse-glimmer-30b` or with the recipe variable below. The selected menu entry determines the exact recipe even when `NEMOCLAW_LLAMACPP_RECIPE` names another recipe. 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 \ $$nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` Use `llama-cpp.muse-glimmer-30b.spark-single.v1` to select the Meta Muse Glimmer recipe explicitly. On a qualifying Windows WSL N1x or Station GB300 host, Windows Express leaves provider selection to onboarding. During Windows Express, onboarding accepts one proof-backed N1x GPU identity or a bounded Station GB300 Windows product observation whose reconciled proof includes an `NVIDIA GB300` device, verifies the remaining readiness requirements, and automatically selects the Experimental managed Qwen 3.6 recipe. The managed Station recipe requires exactly one proved GB300 GPU UUID. The Windows chassis product name does not participate in N1x selection. Before onboarding, unset `DOCKER_HOST` and select Docker's `default` context. Onboarding also requires local Docker Desktop, Arm64, at least 48,000 MiB of Docker and GPU memory, driver version `580.65.06` or later, NVIDIA integration, and successful Docker Desktop GPU passthrough. No provider or recipe variable is required for the automatic path. If `NEMOCLAW_PROVIDER` remains unset, a compatible `NEMOCLAW_LLAMACPP_RECIPE` value still selects managed llama.cpp and makes its recipe explicit. For automation that must make the selection explicit, use these values: ```bash NEMOCLAW_PROVIDER=install-llama-cpp \ NEMOCLAW_LLAMACPP_RECIPE=llama-cpp.qwen3-6-35b-a3b.n1x-wsl.v1 \ NEMOCLAW_SANDBOX_NAME=my-assistant \ $$nemoclaw 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 [Set Up llama.cpp](../inference/local-inference/set-up-llama-cpp). 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. For a hosted custom endpoint, the wizard asks for the **policy tier** before it registers inference. It reuses that selection when it later applies the sandbox policy. For other inference providers, 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. For other inference providers, it then prompts for optional web search, 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 | Requires one broad web authority that lets every sandbox binary open TCP connections to public and private address ranges on destination ports 80 and 443. It replaces overlapping web endpoints while preserving non-web policy. Unspecified, loopback, and link-local ranges remain blocked. 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. When Personal is selected during the current onboarding run, `personal-open-internet` is mandatory for every agent and every onboarding entry point. The picker and policy modes control only additional presets; they cannot deselect, skip, or replace Personal's required web authority. For details on tiers and the presets each includes, refer to [Network Policies](network-policies#policy-tiers). When onboarding creates a sandbox with presets, NemoClaw prints the exact finalized create-time policy scope before registering providers or creating the sandbox. NemoClaw does not persist that selection as desired policy state; later lifecycle operations read the current OpenShell policy, including host edits. In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `balanced`): ```bash NEMOCLAW_POLICY_TIER=restricted $$nemoclaw 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 [`$$nemoclaw policy add`](#$$nemoclaw-name-policy-add) across re-onboards. Use `custom` with `NEMOCLAW_POLICY_PRESETS` when you want the explicit list to be authoritative for optional presets. Onboarding removes any optional preset that is not in the list. `skip` does not add optional tier defaults and retains eligible optional presets already applied. It still applies the required preset for each messaging channel enabled during the same onboarding run so the configured channel can reach its service. For Personal, all modes still apply or retain the mandatory `personal-open-internet` preset. 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 instead uses `personal-open-internet` for web transport and does not select Brave Search or Tavily Search merely to enable ordinary web fetches. This makes keyless fetches available to any sandbox binary, but it does not add a provider-free `web_search` implementation. For Hermes, this includes replacing stale `nous-web` when Tavily is selected. An explicit `custom` preset list or interactive manual selection remains operator-controlled for additional presets. 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 the optional presets in `NEMOCLAW_POLICY_PRESETS`. Previously-applied optional presets not in the list are removed. Personal still requires `personal-open-internet`. Alias: `list`. | | `skip` | Do not add optional tier defaults; retain eligible optional presets already applied. Personal still applies or retains `personal-open-internet`. Aliases: `none`, `no`. | OpenClaw onboarding supports Brave Search and Tavily Search. NemoClaw registers a sandbox-scoped OpenShell provider and keeps `openclaw.json` on an OpenShell credential placeholder. At egress, OpenShell rewrites Brave's `X-Subscription-Token` header with `BRAVE_API_KEY` or Tavily's `Authorization` header with `TAVILY_API_KEY`. Treat web search as an explicit opt-in and use a dedicated low-privilege key. Deep Agents onboarding supports the maintained Tavily Search path. NemoClaw registers the Tavily credential with the OpenShell gateway, applies the `tavily` policy preset when you opt in, and rebuilds the sandbox so the provider attaches to the managed Python runtime. Do not place `TAVILY_API_KEY` in `/sandbox/.deepagents/.env`, `.state/auth.json`, or other Deep Agents Code state. For non-interactive onboarding, export the Tavily key only in the host shell that runs onboarding: ```bash export TAVILY_API_KEY=tvly-... NEMOCLAW_AGENT=langchain-deepagents-code NEMOCLAW_WEB_SEARCH_PROVIDER=tavily $$nemoclaw onboard --non-interactive --yes-i-accept-third-party-software unset TAVILY_API_KEY ``` For non-interactive onboarding, you must explicitly accept the third-party software notice: ```bash $$nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` or: ```bash NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 $$nemoclaw onboard --non-interactive ``` For scripted installer runs, pass explicit acceptance to the `bash` side of the installer pipe: ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash ``` If the installer cannot prompt for the notice in a terminal and no explicit acceptance is set, it exits before installing Node.js or the NemoClaw CLI. To enable Tavily Search in non-interactive mode, set the provider and matching key. ```bash NEMOCLAW_WEB_SEARCH_PROVIDER=tavily \ TAVILY_API_KEY=... \ $$nemoclaw onboard --non-interactive ``` Use `NEMOCLAW_WEB_SEARCH_PROVIDER=brave` with `BRAVE_API_KEY` for Brave Search, or set the provider to `none` to disable web search explicitly. When the provider selector is unset, NemoClaw chooses Brave Search when `BRAVE_API_KEY` is available, then Tavily Search when only `TAVILY_API_KEY` is available. Brave Search wins when both keys are available to preserve the historical non-interactive behavior. An explicit provider with no matching key exits before sandbox creation. A provider key that fails validation prints a warning, disables web search for that run, and lets the rest of onboarding continue. After fixing the key, rerun onboarding so NemoClaw can validate it, register the selected provider, and apply the matching policy preset. Changing or disabling the selected provider recreates the sandbox because the plugin configuration and credential attachment are part of the image. Accept the recreate prompt or pass `--recreate-sandbox`. 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=... \ $$nemoclaw 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 `$$nemoclaw onboard --help` output lists installed runtime names inline, and `$$nemoclaw agents list` shows the same runtimes with manifest descriptions. Use `--agents ` to declare secondary OpenClaw agents, `agents.defaults`, and main-agent overrides in a checked-in manifest that NemoClaw includes in the generated sandbox configuration. Refer to [Declarative Multi-Agent Manifest](../configure-agents/declarative-agents-manifest) for the schema and OpenClaw-native sub-agent field semantics. 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 is created. 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 includes those values in the generated Discord guild workspace configuration 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. Closing stdin during onboarding cancels the run: NemoClaw prints `Installation cancelled`, exits non-zero, and keeps the resumable onboarding session so `nemoclaw onboard --resume` can continue. This holds whether you press `Ctrl-D` while a question is on screen or while the wizard is working between questions, and whether stdin is a terminal or a harness pipe that closes. On a terminal, `Ctrl-D` cancels while the answer is still empty, including at a masked prompt such as an API key; after you type characters it is ignored until you clear them, the same rule a shell applies. If you cancel a brand-new onboarding run at the policy-tier selector or either policy-preset selector after sandbox creation, NemoClaw preserves the incomplete sandbox, registry entry, and onboarding session for retained recovery. NemoClaw reports the durable sandbox identity fingerprint when it is available. It does not run OpenShell's mutable-name deletion command because the name may now identify a replacement sandbox. Follow the [retained-sandbox recovery procedure](#inspect-retained-sandbox-recovery) to reconcile this cancellation. A fresh run with a different explicit name can continue while the cancelled sandbox name remains blocked. 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 transfers the complete OpenShell native home/workspace into the replacement. The transfer includes unknown files, agent configuration, history, hooks, plugins, packages, cron data, and child-agent state without consulting an agent-specific file inventory. OpenShell credential storage remains outside the transferred workspace. NemoClaw aborts recreation if the complete transfer cannot be captured or restored. If pre-delete backup fails and the source identity remains unchanged, the existing sandbox remains registered and available. If the error identifies credential-bearing content, connect to that sandbox, remove or relocate the content, then retry onboarding. The behaviour matches `$$nemoclaw rebuild --force`. Set `NEMOCLAW_RECREATE_WITHOUT_BACKUP=1` to skip the transfer and start the destination 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, rerun the original onboarding command with the same target settings. The rerun continues the active replacement without requiring `--resume`. It accepts a same-name replacement only after its live identity and sandbox registry generation match the journal and it completes or verifies the recorded final handoff. A matching replacement can report not-ready after that handoff. It fails closed if the gateway, source, target, durable source registry fields, or replacement settings changed. Before creating the gateway, the wizard runs preflight checks. Docker is the default runtime provider. It verifies that the selected provider is reachable and prints host remediation guidance when prerequisites are missing. On Linux, set `NEMOCLAW_GATEWAY_RUNTIME=podman` to select the qualified native rootless Podman provider for standard onboarding. Native Podman must pass its provider-owned socket, rootless service, cgroups v2, bridge-container, DNS, architecture, managed-image, and `lsof` listener-enumeration checks; an auto-detected Podman compatibility socket is not enough to opt in. NemoClaw does not install `lsof`; install it through the host's package-management policy before retrying onboarding. 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 `$$nemoclaw 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`. This holds when the onboarding output is redirected or captured (for example `$$nemoclaw onboard 2> onboard.log`, or a CI job driving the CLI on a pseudo-terminal): prompts read `Ctrl+C` from the terminal attached to `stdin`, not from where the question is printed. 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. #### `--from ` Without `--from`, onboarding through the default Docker provider or the explicitly selected native Podman provider for OpenClaw, Hermes, and LangChain Deep Agents Code selects an immutable managed image for the installed release and host architecture. NemoClaw validates the complete three-agent publication cohort before selecting any member. If registry or catalog availability prevents resolution, stock onboarding stops before sandbox creation and does not build a shipped Dockerfile. Catalog evidence that is incomplete, mixed, mutable, wrong-platform, or identity-inconsistent also fails closed before sandbox creation. 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. Its credential, key, and certificate rules exclude matching files and directories at every depth, including nested `.env` files, `secrets/` directories, and `*.pem` files. 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. With a local Docker gateway, NemoClaw builds the staged custom context with BuildKit in the gateway's Docker engine. It checks that the image is available, then passes its image reference to OpenShell. A build failure stops before sandbox creation. A remote gateway without image distribution cannot use `--from`. The native Podman provider does not admit custom Dockerfiles. ```bash $$nemoclaw 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. If deployment verification cannot reach the gateway for a custom OpenClaw image, NemoClaw checks for `/tmp/gateway.log`, `/usr/local/bin/nemoclaw-start`, and `/sandbox/.openclaw/openclaw.json`. When all three paths are absent, onboarding reports that the custom image lacks the managed runtime instead of treating repeated port-forward retries as the recovery path. For the version-matched full-runtime plugin workflow, refer to [Install OpenClaw Plugins](../manage-sandboxes/install-openclaw-plugins). 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 $$nemoclaw onboard ``` If a `--resume` is attempted with a different `--from` path than the original session, onboarding exits with a conflict error rather than silently building from the wrong image. #### `--from-image @` Onboard a published OpenClaw or Hermes image with the default Docker runtime or the qualified rootless Podman runtime without building a Dockerfile. Supply an immutable SHA-256 digest with `--from-image`. In non-interactive mode, you can instead set `NEMOCLAW_FROM_IMAGE`. In non-interactive mode, supply a sandbox name with `--name` or `NEMOCLAW_SANDBOX_NAME`. The image publisher owns its content and compatibility with your NemoClaw release. ```bash $$nemoclaw onboard --name my-agent --from-image @sha256: ``` The image must match the runtime platform and declare a non-root user, `/sandbox` working directory, and usable entrypoint or command. It must contain `NEMOCLAW_TOOL_DISCLOSURE=progressive` or `NEMOCLAW_TOOL_DISCLOSURE=direct`. Onboarding adopts that mode when you have not selected one; an explicit conflicting mode fails before creation. Configure registry credentials through the selected runtime before onboarding a private image. Docker uses its normal credential configuration. Podman uses its normal rootless credential sources, including `REGISTRY_AUTH_FILE` when set. NemoClaw does not prompt for, accept, or store a registry token. Do not combine `--from-image` with `--from` or the Portable profile. Resume retains the recorded digest and requires the same `--from-image` value, or the same `NEMOCLAW_FROM_IMAGE` value in non-interactive mode, on the recovery command. To use another digest, start fresh. If a ready same-name sandbox has a different workload, explicitly authorize its replacement with `--recreate-sandbox`. Rebuild consumes the same digest without building an image. Cleanup retains the published image, and upgrades leave it pinned and publisher-managed. #### `--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 $$nemoclaw 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. ### `$$nemoclaw onboard --from` Use a custom Dockerfile for the sandbox image. This variant of `$$nemoclaw onboard` accepts a `--from ` argument to build the sandbox from a user-supplied Dockerfile instead of the default NemoClaw image. NemoClaw builds the staged context in the selected local Docker engine and checks the image before sandbox creation. ```bash $$nemoclaw onboard --from ./Dockerfile.custom ``` ### GPU Passthrough When `$$nemoclaw 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 WSL ARM64 Linux hosts without that firmware evidence, the selected Docker Desktop or qualification-backed rootless Podman provider runs a bounded CUDA workload on every reported GPU and verifies each device's identity and capacity. Docker uses `--gpus all`; Podman uses the NVIDIA CDI device. On those hosts, plausible, non-placeholder NVIDIA GPU names also require that proof when the NVIDIA kernel-driver interface (`/proc/driver/nvidia`) is absent. On Windows-on-Arm, only the documented N1x and Station GB300 WSL paths can use a matching selected-provider proof for platform qualification; other GPU routes remain unsupported. 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 select an NVIDIA GPU by index (`0`), GPU UUID (`GPU-...`), or full CDI device name (`nvidia.com/gpu=0`). NemoClaw preserves the selection on resume. Use `--vllm-gpu-device ` to select the host GPU for the vLLM container that NemoClaw installs and manages. This selection is separate from sandbox GPU access, and NemoClaw also preserves it on resume. The selected GPU must satisfy the model's memory and compute-capability requirements. For native Docker and Podman creation, NemoClaw passes the normalized CDI name through OpenShell driver config; compatibility routes use the equivalent container-runtime selector. Device selection requires 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 saves redacted diagnostics before the retry. If OpenShell rejects the native `--gpu` flag before creation progress, NemoClaw proves that the sandbox and its labeled containers are absent without deleting by name. For another eligible failure, the retry requires verified cleanup. When the managed runtime requires cleanup tied to its recorded resource identities, NemoClaw stops before the compatibility retry. 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 reaches the OpenShell Ready or Running phase and passes the GPU and applicable local-inference checks. If one of those checks fails before backup removal, onboarding prints failure diagnostics and attempts to restore the pre-patch container. To commit the replacement, NemoClaw first asks OpenShell to stop the sandbox so its durable lifecycle row reaches `Stopped` before any irreversible Docker mutation. It then stops the exact transaction-owned replacement, removes the rollback backup, and asks OpenShell to start the sandbox so OpenShell owns the `Starting` lifecycle fence. NemoClaw verifies an OpenShell `Ready` or `Running` row, a working sandbox exec, and that the exact replacement is the sole running labeled container within the final handoff deadline. If that final handoff cannot be confirmed, onboarding exits with the container diagnostics and cleanup guidance instead of reporting success. 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. ### `$$nemoclaw list` List sandboxes in the registry for the gateway port that `NEMOCLAW_GATEWAY_PORT` selects and any sandbox entries recovered from that live gateway, with their model, provider, and policy presets. The command reads that port's registry and live gateway; it does not scan registries for other gateway ports. Pass `--json` for machine-readable output that includes a `schemaVersion`, the default sandbox, recovery metadata, and the sandbox inventory. NemoClaw redacts recognized credential values, including credentials in URLs, from text and JSON inventory fields before it writes them. When the latest resumable onboarding session owns the matching inference-route reservation but has not created a sandbox, text output shows it under `Incomplete onboarding` with the recorded step and resume command. JSON output reports the same state in `incompleteOnboarding`; it remains separate from `sandboxes` and never affects the default sandbox. When present, `incompleteOnboarding` contains `name`, `status` (`failed` or `in_progress`), `step` (a string or `null`), `interrupted` (a boolean), and `resumable: true`; otherwise it is `null`. NemoClaw does not expose stale reservations that belong to another onboarding session. 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 `$$nemoclaw 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 onboarding records a browser-facing dashboard URL from `CHAT_UI_URL`, text output shows that URL. Otherwise, a recorded dashboard port produces the loopback URL `http://127.0.0.1:/`. The default sandbox in text and JSON output honors the same environment override order as host-level status: `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default. An explicitly set `NEMOCLAW_GATEWAY_PORT` selects gateway-scoped tunnel state. Otherwise, tunnel commands use the selected or default sandbox's owning gateway, falling back to the process-default gateway when no sandbox resolves. If the sandbox name belongs to more than one gateway registry, tunnel-state selection fails closed. ```bash $$nemoclaw list [--json] $$nemoclaw list --json ``` ### `$$nemoclaw 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 `$$nemoclaw 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. `$$nemoclaw 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 $$nemoclaw use $$nemoclaw use --json ``` ### `$$nemoclaw launch ` Connect to a sandbox and start its agent in one host-side command. Use it instead of running `$$nemoclaw connect` and then typing the agent command inside the sandbox. `launch` runs the complete preflight from [`$$nemoclaw connect`](#$$nemoclaw-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, and interactive command match the recorded identity, and the current OpenShell policy is readable and valid. The lease stores no policy hash, so trusted host-side policy changes do not invalidate launch readiness. - The recorded inference selection matches its provider path, and every configured route serves a valid response to a bounded request for the recorded model. NVIDIA Endpoints, supported fixed hosted selections, new hosted compatible selections outside the Personal tier, and qualified new local selections verify their recorded sandbox-attached provider and request the model at its native endpoint without a shared-route models probe. Local NVIDIA NIM, fresh Personal-tier hosted compatible selections, custom endpoints without an attachment, and retained shared selections use `inference.local`. Their models probe must return HTTP 2xx, except that a retained legacy `openrouter-api` shared route can return HTTP 404 for `GET /v1/models` when the bounded model request succeeds. A failed model request rejects readiness before the agent starts. This check is stricter than the HTTP 200–499 reachability diagnostic used by ordinary `connect`. - The recorded inference selection matches its provider path, and every configured route serves a valid response to a bounded request for the recorded model. NVIDIA Endpoints, supported fixed hosted selections, new hosted compatible selections outside the Personal tier, and qualifying new local selections verify their recorded sandbox-attached provider and request the model at its native endpoint without a shared-route models probe. Owned Local NVIDIA NIM, retained legacy routes, and other custom routes without an attachment use `inference.local`. Their models probe must return HTTP 2xx, except that a retained legacy `openrouter-api` shared route can return HTTP 404 for `GET /v1/models` when the bounded model request succeeds. A failed model request rejects readiness before the agent starts. - The agent runtime and its required host-side forwards pass their semantic health checks. For OpenClaw, `connect --probe-only` also settles the existing allowlisted pairing flow before it publishes the lease. The readiness evidence binds the OpenClaw version and trusted registry and agent manifest configuration. Its credential-free pairing qualification binds the canonical CLI client, exact paired device identity, required operator role and scopes, owning OpenShell gateway, sandbox lifecycle identity, and fixed lease epoch. Before accepting that evidence, `launch` makes a bounded, read-only observation of the current OpenClaw-owned pairing state through the owning OpenShell gateway. It skips the complete pairing approval pass only when the evidence still matches exactly and no relevant allowlisted request is pending. Missing, unreadable, malformed, ambiguous, or changed pairing evidence runs the complete pairing approval pass. A relevant allowlisted pending request also runs that complete path, so late scope requests remain eligible for approval. 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. After it dispatches the agent, `launch` releases lifecycle locks before it waits for the interactive session to exit. Other lifecycle commands can proceed while the session remains open. 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 $$nemoclaw 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. For an older OpenClaw registration without recorded lifecycle identity, `launch` requires a ready live sandbox with an observable identity before it starts the agent. If this identity check fails, `launch` stops before starting the agent. Run `$$nemoclaw doctor`, resolve the reported issue, and retry `$$nemoclaw launch `. `launch` returns the agent's exit code when the post-command OpenClaw permission cleanup succeeds. If that cleanup cannot inspect, restore, or verify the mutable config permission contract, `launch` fails closed with exit `1` and prints `OpenClaw permission cleanup failed (...)` to `stderr`. `launch` returns the agent's exit code. When you want a shell inside the sandbox rather than an agent session, use `$$nemoclaw connect`. ### `$$nemoclaw connect` Connect to a sandbox by name. Bare `$$nemoclaw 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 `$$nemoclaw 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 [`$$nemoclaw start`](#$$nemoclaw-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 `$$nemoclaw rebuild` hint. If another terminal is already connected to the sandbox, `connect` prints a note with the number of existing sessions before proceeding. Multiple concurrent sessions are allowed. 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. For a shared-route provider, before reading or changing the live OpenShell gateway inference route, `connect` verifies the shared provider and sandbox metadata. When the live shared 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 `$$nemoclaw inference set --provider --model ` to make an intentional compatible route change outside the connect flow. Before it opens SSH for a shared-route provider, `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 shared route is reachable. A recognized broken shared-route result lets `connect` attempt DNS or route repair and verify the route again. When the initial shared-route 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 `$$nemoclaw doctor`. For NVIDIA Endpoints, supported fixed hosted selections, new hosted compatible selections outside the Personal tier, and qualified new local selections with an attachment, `connect` does not inspect or change the unrelated shared route. It verifies the recorded sandbox-attached provider and sends a native inference request for the selected model. For a verified native NVIDIA attachment, HTTP `429`, `500`, `502`, `503`, or `504`, or a confirmed request timeout, lets interactive `connect` open a diagnostic shell with a degraded warning after gateway checks pass. The failed request leaves model availability unverified; retry after the upstream service recovers. `connect --probe-only` still requires a successful inference request before it can publish launch-readiness evidence. Other providers and terminal credential, route, policy, and malformed-response failures stop `connect` before SSH opens. After route discovery succeeds, every configured Deep Agents Code route must also serve a valid response to a bounded request for the recorded model. A failed model request or missing provider or model metadata stops `connect` before SSH opens. Run `$$nemoclaw doctor` to diagnose a failed model request. 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. When `connect` or `start` reaches `Error` or `Failed` for a Docker-driver sandbox and cannot match its managed container, it lists containers that carry the sandbox-name label. NemoClaw matches only a managed container that OpenShell named for the sandbox in the default workspace. Resolve every listed container through its owning workflow, then rerun the printed command. If Docker discovery fails, no labeled containers exist, or a managed container matches, the command instead prints the normal logs and status guidance. After a host reboot, the OpenShell gateway rotates its SSH host keys. `connect` detects the resulting identity drift, prunes stale `openshell-*` entries from `~/.ssh/known_hosts`, and retries automatically. You no longer need to re-run `$$nemoclaw onboard` after a reboot in this case. ```bash $$nemoclaw my-assistant connect [--probe-only] $$nemoclaw 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. When it finds a stopped registered sandbox, it starts that sandbox through its recorded OpenShell gateway before recovery. 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 on Linux `connect --probe-only` still exits nonzero because it could not publish launch-readiness evidence. A runtime failure and, on Linux, 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. After a successful probe and recovery, it prints a note that launch-readiness evidence is unavailable on this platform and exits zero. The next `launch` runs the complete preflight. On Linux, unsafe launch-readiness diagnostics can report the affected path, owner UID, permissions, a bounded error code, and repair guidance. They exclude receipt contents, environment values, and raw OS error messages. Every `connect --probe-only` completion prints at most one credential-free `Probe timing:` line. The line always reports these stages in this order, with cumulative whole-millisecond durations: - `readiness` waits for the sandbox state. - `authority` validates launch-readiness authority and evidence. - `lifecycle` verifies or recovers the selected runtime lifecycle. - `gateway` verifies the owning gateway path. - `processes` verifies or repairs managed in-sandbox processes. - `forward` verifies or restores required host forwards. - `inference` verifies the selected inference route. - `pairing` settles OpenClaw operator pairing when applicable. - `publication` publishes launch-readiness evidence on Linux. The line reports cumulative durations and attempt counts for `sandbox-identity`, `policy-get`, `inference-get`, `gateway-health`, `forward-health`, and `inference-route` observations. Each observation uses `readiness.=ms` and `readiness..attempts=`. `readiness.firstFailedObservation` names the first failed observation, or reports `none`. `readiness.firstDecision` records the first readiness decision. `readiness.firstFallbackDecision` records the first decision that did not accept existing evidence. Both decision fields report `none` when no corresponding decision occurred. The line also reports `total`, `lifecycleAction=skipped|reused|recovered|failed`, `forwardAction=skipped|verified|restored|failed`, and `result=ready|failed`. A failed probe adds `failedStage=` or `failedStage=unknown`. Stages and observations that do not run report `0ms`; unattempted observations report zero attempts. Clock or writer failures do not change readiness work, command diagnostics, or exit status. Use the command exit status to decide whether the probe passed. Run it for health checks and scripted readiness probes; users continue to run only `$$nemoclaw launch `. Use [`$$nemoclaw launch `](#$$nemoclaw-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. ### `$$nemoclaw exec` Run a single command non-interactively in a running sandbox via the OpenShell exec endpoint. The command runs as the sandbox user with `HOME=/sandbox`, so in-sandbox tooling resolves NemoClaw-provisioned config 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. OpenClaw config resolves under `/sandbox/.openclaw`. Run one OpenClaw turn with `$$nemoclaw my-assistant exec -- openclaw agent --agent main -m "What is 2+2?"`. List the default OpenClaw workspace with `$$nemoclaw my-assistant exec --workdir /sandbox/.openclaw/workspace -- ls -la`. Hermes config resolves under `/sandbox/.hermes`. ```bash nemohermes my-assistant exec -- hermes --version nemohermes my-assistant exec --workdir /sandbox/workspace -- ls -la ``` Everything after `--` is forwarded verbatim to the sandbox command, including flags the inner command needs. After an OpenClaw one-shot command exits, NemoClaw verifies and, when needed, restores the mutable config permission contract. When cleanup succeeds, `exec` returns the remote command's exit code. If cleanup cannot inspect, restore, or verify that contract, it fails closed and prints `OpenClaw permission cleanup failed (...)` to `stderr`. In that case, `exec` returns the cleanup failure instead of the remote command's status. For a registered OpenClaw sandbox with a selected owning managed gateway, a successful direct `openclaw pairing approve googlechat ` command also restarts that gateway after cleanup so the new sender allowlist applies to the next message. If cleanup or restart fails after the approval commits, `exec` exits with status `1` and reports that the approval was not rolled back. When an owning gateway was selected, correct any reported cleanup problem, then run `$$nemoclaw gateway restart` before testing the next message. Without an owning managed gateway, NemoClaw does not attempt activation or print a managed restart command; unregistered and non-OpenClaw sandboxes also do not receive the automatic restart. 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' | $$nemoclaw my-assistant exec --stdin -- cat ssh dgx-spark '$$nemoclaw 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' $$nemoclaw 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. The command runs without one unless you pass `--tty`, so stdout and stderr stay separate streams and width-formatted output keeps its non-terminal layout | | `--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). | ### `$$nemoclaw agent` Run one agent turn non-interactively in a running sandbox. For OpenClaw sandboxes, this command forwards arguments to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. For terminal-runtime sandboxes, NemoClaw forwards arguments to the manifest-declared interactive command; LangChain Deep Agents Code sandboxes run `dcode ...`. Use this when driving the sandbox programmatically from another process (CI job, multi-agent platform, evaluation harness) rather than from an interactive terminal. All flags accepted by the selected in-sandbox agent CLI are forwarded verbatim, so the upstream surface stays the single source of truth. OpenClaw invocations must include at least one target selector: `--agent`, `--session-id`, `--session-key`, or `--to`. This keeps the wrapper from falling back to the unspecified default-session behaviour. Conflict resolution between multiple selectors is delegated to the in-sandbox `openclaw agent` argv contract; the host-side guard only checks presence. ```bash $$nemoclaw my-assistant agent --agent main -m "Summarise README.md" $$nemoclaw my-assistant agent --agent main -m "Status update?" $$nemoclaw my-assistant agent --session-id review-42 -m "Any new findings?" $$nemoclaw my-assistant agent --session-key intake-42 --json -m 'ping' $$nemoclaw dcode-sandbox agent --help $$nemoclaw dcode-sandbox agent -n "Summarize this repository" $$nemoclaw dcode-sandbox agent -n "Summarize this repository" --json ``` For non-JSON OpenClaw turns, the wrapper captures `stdout` and `stderr` and replays them only after the in-sandbox command exits. The combined capture limit is `64 MiB`; exceeding it reports an OpenShell invocation error and exits with status `1`. If the captured output contains an embedded-fallback marker, the wrapper suppresses both streams, prints `recover`, `rebuild --yes`, and `onboard --resume` guidance to `stderr`, and exits with status `1`. Otherwise, it writes the captured output to the corresponding host streams and returns the OpenShell command's exit status. The in-sandbox NemoClaw plugin writes its registration banner to `stderr`, so the banner does not prefix the agent reply on `stdout` in non-JSON mode. Because a delivered turn always writes to one of the two streams, the wrapper reports a dispatch with status `0` and no output as a failure. The wrapper prints recovery guidance to `stderr` and exits with status `1`. Pressing `Ctrl+C` interrupts the OpenShell child, and sending `SIGTERM` to the host wrapper forwards `SIGTERM` to that child. NemoClaw waits for OpenShell to stop the in-sandbox turn, replays captured output, and returns status `130` for `SIGINT` or `143` for `SIGTERM`. When the forwarded argv sets a positive whole-number `openclaw agent --timeout `, NemoClaw starts that deadline before its best-effort Ollama recovery. Recovery can use only the remaining time minus a reserved one second for the turn. Before dispatch, NemoClaw rewrites the forwarded timeout to the remaining time rounded up to a whole second, with a one-second minimum. Both captured paths then bound the OpenShell command at that forwarded remainder plus 30 seconds. The extra seconds let the in-sandbox turn report its own timeout first, so the host bound catches only a turn that stops answering. These leave the OpenShell wait unbounded: - `--timeout 0`. - A value NemoClaw cannot read as a positive whole number of seconds. - An argv without `--timeout`. - An unrecognized option before `--timeout`, because NemoClaw does not infer a host deadline outside the documented OpenClaw option grammar. - A `--timeout` after the `--` argv terminator, which OpenClaw reads as payload rather than as its own flag. When the captured output reports that the turn's deadline fired, the wrapper replays the partial output and writes deadline guidance to `stderr`. It exits with status `1` instead of the upstream status `0`. The diagnostic shell-quotes the sandbox name and forwarded arguments, then redacts detected credential values before writing the recovery command to `stderr`. If redaction changes the recovery command, the diagnostic tells you not to replay it; otherwise, it labels the command as runnable inside the sandbox. For a registered sandbox, both captured paths pin the sandbox's recorded gateway with an explicit `-g`. Neither path forwards an interactive terminal on `stdin`. When NemoClaw recognizes `-m` or `--message`, it closes the OpenShell child's `stdin` before dispatch. This prevents an unused pipe from delaying execution while OpenShell waits for EOF. Nonempty `--message-file` arguments and calls without a recognized inline message preserve a pipe or redirect. The sandbox resolves message-file paths, including symlinks to stdin. For example, the wrapper preserves redirected input for `printf 'ping' | $$nemoclaw my-assistant agent --agent main`. The producer must close standard input after writing the message. OpenShell starts the sandbox command only after standard input ends, so without an inline message NemoClaw reads piped input on the host first. It waits up to 30 seconds for the input to end, including for `--message-file /dev/stdin` and symlinks to stdin. A `--timeout ` that bounds the OpenShell wait above also sets this input wait. Each case in the preceding list instead keeps the 30-second input wait, including a `--timeout` after an unrecognized option or after `--`. If the input deadline expires, the input exceeds 4 MiB, or standard input cannot be read, the command exits nonzero without starting the turn and prints guidance to close the producer or provide an inline message. When the top-level OpenClaw `--json` output flag is present, the wrapper uses a captured no-TTY path with a `64 MiB` buffer so `stdout` stays parseable JSON. Raw `stderr`, including structured JSON diagnostics, is forwarded unchanged. NemoClaw appends failed-tool or untrusted-child provenance only from the `stdout` JSON. The wrapper reads completion markers only from the final matching OpenClaw response envelope: a local `{ payloads, meta }` response or a gateway `{ status, result: { payloads, meta } }` response. It ignores earlier JSON progress or log records. It exits with status `1` when that metadata contains `error.kind: "incomplete_turn"`, `livenessState: "abandoned"`, or a `timeoutPhase` value, even when the envelope reports success. `replayInvalid: true` means replaying the turn may repeat side effects. The wrapper accepts it only with evidence of a completed run, a successful tool summary, and final assistant text matching the reply payload. Otherwise it exits with status `1` and the existing inspect-before-retry guidance. Marker-shaped values inside tool results, tool-call arguments, or other descendants do not change the exit status. A turn can run every tool successfully and still become abandoned before it produces a reply. The wrapper writes the unchanged JSON trace to `stdout` before it reports the incomplete turn, so the partial tool trace remains available. The wrapper writes the verdict, the detected markers, and verify-before-retry guidance to `stderr`. A `timeoutPhase` value names the phase the deadline fired in, so the wrapper writes deadline guidance in place of the generic incomplete-turn text. Tool calls in a partial trace may have already applied side effects, so verify what the turn changed before you retry it. The wrapper passes through an upstream non-zero exit status unchanged. Literal `--json` values consumed by flags such as `-m` or `--reply-channel`, or arguments after `--`, stay on the normal passthrough path. Documented value flags written as `--flag=value`, such as `--session-id=s1`, are recognized the same way as separated value flags. If an unrecognized OpenClaw option appears before `--json`, NemoClaw also keeps the command on the normal passthrough path so OpenClaw remains the argv source of truth. Common OpenClaw flags include `-m `, `--session-id `, `--agent `, `--model `, `--thinking `, `--json`, `--deliver`, `--reply-channel `, and `--timeout `. For OpenClaw sandboxes and registry fallbacks, `$$nemoclaw agent --help` prints the wrapper-level summary locally. Invoke `$$nemoclaw exec -- openclaw agent --help` to view the upstream OpenClaw help text directly. For registered terminal-runtime sandboxes, bare invocations and `--help` are forwarded to the terminal command, so a LangChain Deep Agents Code sandbox receives `dcode` for `$$nemoclaw agent` and `dcode --help` for `$$nemoclaw agent --help`. Host-side validation runs before the sandbox dispatch: - OpenClaw sandboxes and registry fallbacks must include at least one target selector flag: `--agent`, `--session-id`, `--session-key`, or `--to` in either `--flag value` or `--flag=value` form. OpenClaw invocations without a selector exit `2` and print `No target session selected` locally, without paying the in-sandbox dispatch cost. Registered terminal-runtime sandboxes delegate bare invocations and help flags to the manifest command instead. - If the sandbox is registered but not in a `Ready` or `Running` phase, the wrapper exits `1` and prints the documented recovery commands (`$$nemoclaw recover`, `$$nemoclaw rebuild --yes`, `$$nemoclaw onboard --resume`) rather than deferring the readiness rejection to `openshell sandbox exec`. 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 NemoClaw recovery command for its managed forward. Use the allocated API port shown by `nemohermes status` below. Recover the managed forward, then POST chat completions directly: ```bash nemohermes my-hermes recover API_TOKEN=$(nemohermes my-hermes gateway-token --quiet) curl -sN http://127.0.0.1:/v1/chat/completions \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_TOKEN" \ -d '{"model":"","messages":[{"role":"user","content":"What is 2+2?"}],"stream":true}' ``` For Deep Agents sandboxes, `agent` forwards to the manifest-declared terminal command. Bare invocations run `dcode`, and `--help` runs `dcode --help`. Use `dcode -n` for explicit headless automation when you are already connected to the sandbox, or use `$$nemoclaw agent -n ""` from the host. Add `--json` to either form for one managed, versioned JSON envelope on stdout. The host wrapper forwards the flag to `dcode`. For the schema, status and exit behavior, and 1 MiB output limit, refer to [Run Deep Agents Code](/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code). The host wrapper keeps `HOME=/sandbox`, the managed proxy environment, and the manifest-declared Deep Agents config path aligned with `connect`. Interactive `$$nemoclaw agent` launches the same terminal TUI as `dcode`. Headless `$$nemoclaw agent -n ""` uses the managed headless boundary, where non-shell tools can auto-run without the interactive approval UI. ### 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. #### `$$nemoclaw 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 $$nemoclaw my-assistant config get $$nemoclaw my-assistant config get --key agents.defaults.model.primary --format yaml ``` ```bash $$nemoclaw my-assistant config get $$nemoclaw my-assistant config get --key model.default --format yaml ``` ```bash $$nemoclaw my-assistant config get $$nemoclaw my-assistant config get --key models.default --format yaml ``` | Flag | Description | | --------------------- | ----------------------------------------- | | `--key ` | Print one value from the sanitized config | | `--format json\|yaml` | Output format. Defaults to JSON | #### `$$nemoclaw config set` This host command is not available for OpenClaw because OpenClaw owns `openclaw.json` after first launch. Connect to the sandbox and use `openclaw configure`, `openclaw config set`, or `openclaw config unset`. Use `$$nemoclaw inference set`, credential commands, and policy commands when the change also requires host-side OpenShell state. 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. ```bash $$nemoclaw my-assistant config set --key model.default --value openai:nvidia/nemotron $$nemoclaw my-assistant config set --key agent.max_turns --value 100 --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 the 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. For Deep Agents sandboxes, `config set` is unavailable because managed startup (or an explicit custom image build) materializes the `dcode` configuration as image-owned state. Run `$$nemoclaw onboard --agent dcode --name --fresh` when you need to change it. Use `$$nemoclaw config get` to read the current values. Host-side config, inference, gateway recovery, backup, policy, channel, and sandbox destruction mutations serialize per sandbox. ### `$$nemoclaw recover` Restore sandbox readiness and re-establish host-side forwards without opening an SSH session. Use this after a sandbox crash or when `$$nemoclaw status` reports a stopped sandbox or an unhealthy forward. Restore sandbox readiness without opening an SSH session. Use this after a sandbox crash or when `$$nemoclaw status` reports a stopped sandbox. For a stopped standard sandbox, `recover` asks OpenShell to start that exact sandbox before it waits for readiness. If provider state appears active while OpenShell reports `Stopped`, recovery still submits the start through OpenShell so one lifecycle owner repairs the phase. If OpenShell cannot start the sandbox, recovery reports the failure and does not fall back to a direct provider-container mutation. `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. After the sandbox is available, `recover` sends authenticated requests only to verify supported in-sandbox agent processes and repair supported state for a running gateway and host forwards. Standard sandbox start and stop remain OpenShell-owned. 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`, manual in-sandbox relaunch, or container replacement as a fallback. When `recover` finds a stopped built-in OpenClaw or Hermes agent gateway, it reports the stopped gateway and does not relaunch it. If the gateway is healthy, `recover` checks or repairs host-side forwards. It exits zero only when the required forward checks succeed. When the dashboard port is held by a listener that NemoClaw cannot attribute to the sandbox's own OpenShell forward, the command reports the port, leaves that listener running, does not restore a forward onto it, and exits nonzero. Legacy SSH forward records do not establish ownership. Stop the owning OpenShell gateway or service to release the listener, then run `recover` again. Use [`$$nemoclaw gateway restart`](#$$nemoclaw-name-gateway-restart) when you deliberately need a running gateway to reload runtime configuration or plugins. `recover` waits up to 30 seconds to acquire the per-sandbox lifecycle lock. Deep Agents Code has no in-sandbox agent gateway or host-side forward. After the sandbox is ready, `recover` verifies the sandbox inference route and runs the terminal smoke checks. The inference check uses the sandbox's native provider attachment when it has one, and the managed `inference.local` route otherwise. It exits zero only when both checks pass. If the inference check fails, run `$$nemoclaw doctor` to find the failing hop. If a terminal smoke check fails, the terminal runtime is degraded. `recover` does not repair it, so rebuild the sandbox. ```bash $$nemoclaw my-assistant recover ``` ### `$$nemoclaw gateway restart` Request a native restart of the supported in-sandbox gateway. Use this after runtime configuration or plugin changes that the agent reads only at gateway startup. Unlike `recover`, this command restarts a healthy gateway instead of exiting after the health probe. ```bash $$nemoclaw my-assistant gateway restart [--quiet|-q] ``` On success, the command reports that the gateway was restarted, health passed, and forwards were checked or recovered. For OpenClaw, NemoClaw waits for `/readyz` to return HTTP `200` with JSON `{"ready":true}` before it repairs host-side forwards. It also checks the dashboard forward, messaging forward, and manifest-declared agent forwards. `--quiet` suppresses progress lines but still prints refusal diagnostics. NemoClaw invokes the agent's native lifecycle command through the selected OpenShell sandbox. OpenShell owns sandbox containment, and the agent runtime owns the gateway and its child processes. NemoClaw does not signal, authorize, or respawn an agent-owned process. 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 and stops an alive but deaf gateway after four consecutive failed health checks. If the gateway requests a fifth service-managed restart with status 75 within 60 seconds, the supervisor waits until the rolling window permits a relaunch. The sandbox remains active during this cooldown. Clean exits and status 79 wait for authenticated recovery, while other exit statuses fail immediately. If the Hermes restart closes the OpenShell exec relay before it returns status, NemoClaw waits for the selected sandbox control plane to become ready again. For OpenClaw, NemoClaw verifies the readiness endpoint before it repairs only the host-side OpenShell forwards. For Hermes, NemoClaw verifies the agent health endpoint before it repairs only the host-side OpenShell forwards. For Hermes, the native restart path validates `/sandbox/.hermes/.env` against the secret-boundary guard and validates the supervisor runtime environment. The native `mcp_servers` content remains authoritative, including direct edits. The supervisor does not reconcile it against host-side MCP state. Use supported host commands such as `$$nemoclaw config set` and `$$nemoclaw inference set` for settings that must match host registry state. The command reports `secret-boundary refusal` when the environment does not pass that guard. The command reports the failure layer returned by the native agent command. Host-side failures include unsupported agent, native agent command, health timeout, and forward recovery failure. Inspect the native diagnostic before choosing a repair. For ordinary process or health failures, correct the cause, then run `$$nemoclaw stop` and `$$nemoclaw start` to reset the native supervisor. Rebuild only if the sandbox still cannot start. Hermes can also report secret-boundary refusal when the native command reports an unsafe runtime directory. For Hermes, `HERMES_RUNTIME_PREPARATION_FAILED stage=` identifies a supported input that still failed after five bounded preparation attempts. Correct the named input through its supported host-side configuration or credential flow, then run `$$nemoclaw stop` followed by `$$nemoclaw start`. If startup layout repair reports the maximum log-entry count or repair depth, archive or remove old retained logs from a trusted host-side recovery environment, then stop and start the sandbox. For symbolic links, hard links, unsafe entry types, or paths that changed during repair, restore reviewed files from an independent trusted backup into a recreated sandbox or recreate from host-side onboarding configuration. Rebuild for an integrity mismatch or when the input or sandbox state cannot be repaired safely. An older image without the current native lifecycle command requires `$$nemoclaw rebuild --yes`. For gateway restart, NemoClaw does not fall back to direct provider-container mutation or manual process signaling. Terminal agents do not have a gateway runtime and fail as unsupported. ### `$$nemoclaw stop` Ask OpenShell to stop the exact registered sandbox 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 [`$$nemoclaw destroy`](#$$nemoclaw-name-destroy) when you want to delete it instead. ```bash $$nemoclaw my-assistant stop ``` For OpenClaw-managed gateways, the command first asks the in-sandbox gateway to shut down its channels gracefully. It then submits the stop through the owning OpenShell gateway and confirms that the same immutable sandbox identity reached `Stopped` before it records stop intent or releases host-side resources. OpenShell owns the provider container and driver-specific stop behavior. After OpenShell confirms the sandbox stopped, NemoClaw attempts to stop that sandbox's host dashboard forward. If the sandbox 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. NemoClaw also attempts to remove any leftover dashboard forward for that sandbox. Stopping an already-stopped sandbox succeeds without changes. The standard Docker and native Podman paths require a registered immutable sandbox identity and a reachable owning OpenShell gateway. NemoClaw does not fall back to direct provider-container mutation. Portable remains a separate receipt-bound lifecycle path. ### `$$nemoclaw start` Ask OpenShell to start a sandbox stopped with [`$$nemoclaw stop`](#$$nemoclaw-name-stop) or by a host reboot. `start` then repairs the in-sandbox gateway and host-side forwards the same way [`$$nemoclaw recover`](#$$nemoclaw-name-recover) does. `start` then waits for launch readiness and runs one inference request from inside the sandbox. If inference is not usable, `start` exits nonzero. Run `$$nemoclaw doctor` to find the failing hop. ```bash $$nemoclaw my-assistant start ``` `start` submits the lifecycle mutation through the owning OpenShell gateway, validates the returned immutable sandbox identity, and waits for that same sandbox to become ready. If the registered identity is missing or changed, or OpenShell no longer has the sandbox, the command fails without direct Docker or Podman fallback and points you to the appropriate recovery or rebuild action. 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`. Before it verifies the managed terminal runtime, `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 the sandbox's selected provider path using its recorded provider and model. NVIDIA Endpoints, supported fixed hosted providers, new hosted compatible selections outside the Personal tier, and qualified new local selections use native endpoints through sandbox-attached OpenShell providers. Owned Local NVIDIA NIM, fresh Personal-tier hosted compatible selections, custom endpoints without an attachment, and retained shared routes use `inference.local`. After an OpenClaw sandbox and gateway become Ready, a verified native NVIDIA attachment can start with degraded inference when the request returns HTTP `429`, `500`, `502`, `503`, or `504`, or a confirmed timeout. The command clears the stop record and exits `0`, but the failed request leaves model availability unverified. A terminal credential, route, policy, or malformed-response failure still exits non-zero. Other providers also exit non-zero when the inference request fails. For terminal failures, the command prints the probe result, including any HTTP status, and points you to the sandbox doctor command. Ordinary providers request 16 reply tokens; Gemini requests 256 reply tokens so reasoning has room before visible content. The request allows up to 90 seconds, and the host wrapper allows 95 seconds for bounded process startup and cleanup. Each run consumes provider tokens on a hosted path. When the sandbox records no provider or no model, `start` skips the request and exits `0`. For a shared gateway route, `doctor` still classifies an HTTP `401` or `403` response as reachable. The native NVIDIA doctor probe instead requires a 2xx response from the sandbox-attached provider. Correct the provider credential when `start` reports either status. ### `$$nemoclaw 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 `$$nemoclaw 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 sandbox, status reports a clean `phase: "Stopped"` only when the persisted intentional-stop record agrees with a provider-confirmed `sandbox_container_stopped` result. In that case it keeps `failureLayer` null, suppresses inference probes, and exits `0`; other preflight failures remain visible. A separate gateway or status error can still make the command exit nonzero. A stopped runtime without recorded stop intent remains a `sandbox_container_stopped` failure. 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`, `policiesAvailable`, `llamaCpp`, `failureLayer`, `terminalRuntimeHealth`, `servingProcessHealth`, and `dockerPaused`. `policies` is derived from the current OpenShell policy; NemoClaw does not persist a second preset list or baseline-exclusion ledger. `policiesAvailable` is `false` when that live policy cannot be read or parsed, distinguishing an unavailable result from a verified empty `policies` array; text status prints `Policies: unavailable` for the same state. When the live gateway route matches the sandbox's recorded llama.cpp route, `llamaCpp.kind` is `attached`, `managed`, or `unavailable`. An attached route also includes its fixed loopback `llamaCpp.endpointUrl`. An unavailable result means NemoClaw could not safely verify the managed ownership receipt; it does not include an endpoint and provides a secret-free diagnostic and recovery action. During route drift, `status` omits the `llamaCpp` route attribution; inspect `routeDrift` before acting on endpoint information. Text status can still show managed-runtime details from the sandbox-owned receipt. The schema-version `1` `model` and `provider` fields keep their established live-route meaning when the gateway route is readable, except that sandboxes with native NVIDIA, fixed hosted, or Deep Agents Code, Hermes, or OpenClaw native local provider attachments report their recorded sandbox-scoped route because the shared route is unrelated. Use `recordedRoute` for the sandbox's durable provider and model and `liveRoute` for the gateway-global route. When the live shared route differs for a shared-route provider, text output prints both routes and JSON output sets `routeDrift.live`, `routeDrift.recorded`, and `routeDrift.canConnect`. Native NVIDIA, fixed hosted, and Deep Agents Code, Hermes, or OpenClaw native local provider attachments do not report shared-route drift; `status` does not read the shared gateway route for those sandboxes, so `liveRoute` and `routeDrift` are always `null` even while the attached provider serves requests. Use `recordedRoute` and `inferenceHealth` to check a native provider attachment. 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` can mean a valid model response, a reachable route without a request, or a degraded native NVIDIA result. Inspect `degraded` and `probed` before treating it as verified model health. 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 path 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 path is up. Shared-route requests use the live gateway route's provider and model, then fall back to the recorded values when the live route is unreadable. Native NVIDIA, hosted, and Deep Agents Code, Hermes, or OpenClaw native local requests always use the sandbox's recorded provider and model. When the live shared provider matches the recorded provider, the request uses the sandbox's recorded API family, even when only the model differs. This includes `openai-responses`. When the live shared provider differs, NemoClaw does not carry the recorded API family to that provider. Each attempt requests 16 reply tokens for ordinary providers or 256 for Gemini. The request allows up to 90 seconds, and the host wrapper allows 95 seconds for bounded process startup and cleanup. Hosted requests consume provider tokens on every attempt. When the inference request returns HTTP `429`, `500`, `502`, `503`, or `504`, `status` retries the selected provider path and request up to three total attempts, with a two-second delay between failed attempts, because those statuses are transient gateway and availability answers rather than evidence that the path is broken. Before each retry, it writes the failed probe boundary, an HTTP status when one is available, the next attempt, total attempts, and delay to stderr; `--json` keeps stdout machine-readable. On an ordinary run, terminal HTTP `401`, `403`, or `404`, an invalid 2xx response body, an unconfirmed statusless failure, and a failing provider-path probe are final on the first attempt. When the same run recovers a managed gateway, `status` retries any failed route or inference probe on that schedule instead, while the restarted delivery chain settles. Each route probe has a 10-second timeout. Three complete route probes plus their 95-second inference wrappers and two delays can take about 319 seconds. When NemoClaw sends an inference request, `inferenceHealth.subprobes` reports the provider-path result as the `route reachability` hop, so a failing verdict still shows that the path 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. For a Hermes native NVIDIA route, `status` also verifies the agent's managed credential reference independently of the provider-path request. If the verifier confirms an invalid or stale reference, `inferenceHealth` reports `ok: false`, `probed: false`, and `failureLabel: "unauthorized"`, even when the provider-path request succeeded. The text output reports `not probed` for the agent credential check. For a confirmed rejection, it directs you to `$$nemoclaw rebuild` to refresh the managed credential. After rebuilding, rerun `$$nemoclaw status`; healthy inference requires both a successful provider-path request and a verified managed credential reference. If verification is unavailable because the credential check times out, sandbox access fails, or the installed image lacks the verifier, the agent credential result reports `failureLabel: "unreachable"`, `ok: false`, and `probed: false`. If the provider-path result already failed, `inferenceHealth` keeps that result and adds the unavailable credential result to `subprobes`. Otherwise, the unavailable credential result becomes the main inference result. When a credential failure becomes the main result, the provider-path result and its existing diagnostics remain in `subprobes`. The command exits nonzero in each failure case. If status reports that the installed image lacks the verifier, rebuild the sandbox to install it, then rerun status. For other unavailable-verification results, retry status. If verification remains unavailable, check sandbox health and recover access before retrying. Retained shared NVIDIA routes do not use this additional check. 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 `$$nemoclaw 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 neither `present` nor `missing` with confirmed `phase: "Stopped"`, 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 outside a degraded native NVIDIA transient result, managed llama.cpp ownership is unavailable, or a terminal runtime sandbox reports a recorded OOM kill. When the canonical text command targets an unregistered name, it reports that the sandbox is not registered and tells you to run `$$nemoclaw list`. The alias form `$$nemoclaw status --json` requires the sandbox to be registered locally; the canonical form `$$nemoclaw sandbox status --json` is the one to use from automation that may run against an unknown sandbox name, since it still emits a JSON document with `found: false` instead of a text error. 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. An existing Windows WSL Qwen runtime with the former pinned image cannot start or resume. After a qualified native image is pinned, save any sandbox files you need, run `$$nemoclaw destroy` to remove the owning sandbox and its managed runtime, and onboard again. The shared model cache is preserved. See [Upgrade or Roll Back](../inference/local-inference/set-up-llama-cpp#upgrade-or-roll-back). For a Deep Agents sandbox, text output includes `DCode auto-approval capability: disabled` or `DCode auto-approval capability: thread-opt-in`. JSON output reports the same configured value in `dcodeAutoApprovalMode`. This value does not attest that auto-approval is active in any live TUI thread. ```bash $$nemoclaw my-assistant status $$nemoclaw my-assistant status --json $$nemoclaw sandbox status my-assistant --json ``` On a normal status read, the command probes the selected provider path from inside the sandbox, and when that probe reports the path reachable it sends an inference request over the same path. NVIDIA Endpoints, supported fixed hosted providers, new hosted compatible selections outside the Personal tier, and qualified new local selections use native endpoints through sandbox-attached OpenShell providers. Owned Local NVIDIA NIM, fresh Personal-tier hosted compatible selections, custom endpoints without an attachment, and retained shared routes use `inference.local`. The inference request verifies the selected provider path, and both checks exercise the path that agent traffic uses. For provider-path results, the main `Inference` line uses these states: | State | Meaning | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `healthy` | The route returned a structurally valid result for the inference request. | | `degraded` | A verified native NVIDIA route had a transient request failure after bounded retries. The model response remains unverified, but `status` exits `0`. | | `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 a failing HTTP status or invalid 2xx response body outside a degraded native NVIDIA result. | | `unreachable` | The route had a transport failure, no final HTTP status, or an invalid status, or the request returned no HTTP status without a confirmed native NVIDIA timeout. | | `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. | When another lifecycle operation is in progress and NemoClaw confirms that no Portable authority exists, status returns a best-effort, read-only snapshot that can show transitional state. It does not run inference health checks or send an inference request. It does not repair the gateway, host forward, stop-intent record, or Hermes tool gateway broker. JSON output sets `inferenceProbeSuppressed` to `true`. If NemoClaw finds or cannot rule out Portable authority, status fails fast. If Portable authority appears during the snapshot, status reports a lifecycle conflict after it finishes the snapshot. An authentication response on a shared gateway route probe confirms that the route is reachable, not that provider credentials are valid. For those shared routes, `$$nemoclaw doctor` sends no inference request, so it reports an HTTP `401` or `403` route response as reachable and exits `0` where `status` reports `unauthorized`. Native hosted and Deep Agents Code, Hermes, and OpenClaw native local doctor checks verify the recorded provider identity and sandbox attachment, then require a successful inference request through the selected native endpoint. The native NVIDIA doctor probe verifies the sandbox-attached provider directly and requires a 2xx response. 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 that host-side request reaches the time limit, `Inference (upstream)` reports `not probed` and leaves model health unverified. A confirmed timeout of the authoritative native NVIDIA request instead reports `degraded` after bounded retries. Host-side checks are diagnostic only and do not override the authoritative selected-provider result or determine the command exit status. The `Inference (upstream)` check authenticates with the host credential that NemoClaw resolves for the provider, such as `NVIDIA_INFERENCE_API_KEY`. OpenShell stores the credential that the sandbox's selected provider path uses. The CLI cannot read the stored value back, so the two credentials can hold different secrets. When the managed sandbox path has already served the inference request, an `unauthorized` result on `Inference (upstream)` describes the host credential. NemoClaw then reports that check as `not probed` and names both credential sources. An `Inference (upstream)` check that fails for another reason, such as `unreachable`, still reports its own state. Local backend and auth proxy checks, such as `Inference (auth proxy)`, always report their own state and their own repair step. For a shared route, `$$nemoclaw doctor` sends no inference request, so it reports the `Inference (upstream)` state that it measured. 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 without a matching intentional-stop record, the initial preflight records the `sandbox_container_stopped` failure layer and suppresses the host-side `Inference` probe. A matching intentional-stop record instead produces the clean `Stopped` result described above. If the owning OpenShell gateway is healthy but no longer lists the registered sandbox, status preserves the local registration and reports the missing OpenShell state without directly starting, unpausing, renaming, or replacing a container. When lifecycle locks are available and OpenShell reports the registered Docker-driver sandbox as present and `Ready`, status verifies the OpenClaw gateway and host forward. It recovers either component when the verification reports it absent. When status finds a running sandbox but cannot clear its stale intentional-stop record, it exits non-zero and reports the `stop_intent_update_failed` state. Repair write access to NemoClaw's local state, then retry `$$nemoclaw status` before running another lifecycle command. 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 `$$nemoclaw 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 for inspection and directs the operator to remove that stale entry with `$$nemoclaw destroy --yes` before clean onboarding. Rebuild cannot recreate a missing sandbox because no authoritative OpenShell policy remains. 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: