NemoHermes CLI Commands Reference
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.
Agent Selection
Use nemohermes for the Hermes variant. It selects Hermes by default during onboarding and for other commands. Use --agent hermes during onboarding or set NEMOCLAW_AGENT=hermes when you need the same selection through another entry point. Hermes-specific sections below describe the built-in Hermes dashboard, the separate OpenAI-compatible API endpoint, Hermes config under /sandbox/.hermes, and provider updates that patch config.yaml.
In-Sandbox Commands
Hermes does not use the OpenClaw chat slash command. Use the host-side nemohermes commands for lifecycle, status, policy, and inference operations. The in-sandbox Hermes integration installs the NemoClaw Hermes plugin, which exposes tools for status and environment information, plus an on_session_start hook.
Sandbox Command Scope
Put the sandbox name before a sandbox action, for example nemohermes <name> 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 nemohermes onboard --resume after an interruption.
A registered sandbox can share an action name; nemohermes doctor status addresses a sandbox named doctor.
The global nemohermes 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_KEYcontaining a credential value, rather than a provider selector such asbuildorrouted
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.
--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:
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.
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.
Hosted Installer Exit Statuses
The hosted installer reports how a run stopped through its exit status. When you interrupt it at a prompt, it exits 130, the same status that nemohermes onboard reports for that interrupt. An interrupted onboarding run still prints [ERROR] Onboarding did not complete successfully. before it exits, so read the exit status rather than that line. The installer preserves no other signal status, and a progress step stopped by SIGTERM also exits 130, so a script that stops the installer itself cannot read 130 as a deliberate interrupt. DGX Station host preparation exits 10 when it requires a reboot and 11 when it requires a new login session, and prints the command that resumes the install. Treat every other non-zero status as a failure.
Standalone Host Commands
The CLI handles host-side operations that run outside the selected agent runtime.
nemohermes help, nemohermes --help, nemohermes -h
Show the top-level usage summary and command groups. Running nemohermes with no arguments shows the same help output.
nemohermes --version, nemohermes -v
Print the installed NemoClaw CLI 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.
--sandbox is required.
When the sandbox name is registered on more than one gateway, pass --gateway <name> 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.
nemohermes completion
Generate a tab-completion script for Bash, Zsh, or Fish from the commands and flags available in the installed CLI. The script completes public global commands, the sandbox-first nemohermes <name> ... grammar, flags, shell choices, and locally registered sandbox names. If you omit the shell name, nemohermes completion detects the target from $SHELL and defaults to Bash when it cannot identify Zsh or Fish. The generated script is bound to the CLI name that created it, so install a separate script for each CLI alias you use. It loads sandbox names from the local registry the first time completion runs and caches them for the rest of that shell session.
For Bash, source the generated script and add the same line to ~/.bashrc for future sessions.
For Zsh, source the generated script and add the same line to ~/.zshrc for future sessions.
For Fish, write the generated script to Fish’s completions directory.
Start a new shell session to refresh the cached sandbox names after creating or removing a sandbox.
nemohermes config export <sandbox>
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.
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:
Use --output - to write YAML to standard output on any supported host or in a pipeline:
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.envreferences through the destination command’s environment. Keep credential values out of YAML. Unset exported credentials after the destination command finishes. - If
network.proxyis 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.
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 browser terminal UI behavior, including explicit disabled values when omission would enable them, plus nondefault interface ports.
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.
nemohermes resources
Display host hardware inventory and configured sandbox resource profiles. Use --json for machine-readable CPU, memory, GPU, Kubernetes allocatable-capacity, and profile data.
If the gateway is not running, Kubernetes allocatable fields are omitted and host CPU/RAM totals are still shown.
nemohermes host probe
Inspect host capabilities and gateway authority before onboarding without changing host, Docker, gateway, credential, policy, or sandbox state. Use --json for the schema-versioned report. The command exits with 0 for supported, 2 for incompatible, and 3 for inconclusive.
For capability IDs, evidence bounds, and compatibility guidance, refer to System Readiness.
nemohermes agents list
List the installed agent runtimes that can be selected with nemohermes onboard --agent <name>. 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.
Expected output:
nemohermes profiles list
List the serving profiles installed with NemoClaw and evaluate them against the current host. The command reports each profile’s stable ID, display name, inference backend, model, topology, selection mode, support state, estimated downloads, and incompatibility reason. It reads the serving catalog and host readiness state without downloading a model or changing host, gateway, inference, or sandbox resources.
Use --json for machine-readable output with the same profile fields.
Use the stable id value with nemohermes onboard --profile <name>. Display names are accepted when they identify exactly one profile, but stable IDs are suitable for scripts and automation.
nemohermes onboard
Run the interactive setup wizard (recommended for new installs). The wizard creates an OpenShell gateway, registers inference providers, 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.
For Hermes, use the alias or pass the agent explicitly:
--agent accepts the canonical manifest names from nemohermes agents list plus common aliases. For example, nemohermes resolves to hermes, while dcode, deepagents, deepagents-code, and langchain resolve to langchain-deepagents-code.
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.
--profile <name>
Select one serving profile from nemohermes profiles list for interactive or non-interactive onboarding. The flag is generic and does not add a model-specific command or flag. NemoClaw maps a unique display name to its stable catalog ID and passes that ID to the managed inference path.
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 nemohermes 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:
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 <absolute-host-directory:/sandbox/directory> 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 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:
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.
Before the configuration review, NemoClaw records the sandbox name and the selected provider and model as an incomplete choice. If onboarding stops at the review prompt, an interactive --resume run shows the prompt again. A non-interactive --resume run reuses the recorded choice and continues to inference setup. After you choose Apply configuration, NemoClaw records the choice before inference setup starts. If inference setup fails, --resume reuses the accepted provider, model, and sandbox name. If you choose Exit onboarding, onboarding exits with a nonzero status and clears those recorded choices. Run nemohermes onboard to make new choices after exit. During a resume without terminal input, --yes or NEMOCLAW_YES=1 also selects non-interactive resume behavior. For a new or fresh session, --yes and NEMOCLAW_YES=1 accept supported confirmations but do not replace --non-interactive. If onboarding returns without reaching the final complete state, the command exits with status 1. When that result is resumable, NemoClaw keeps the session in_progress at its last checkpoint instead of marking it failed, so correct the reported condition and run nemohermes onboard --resume.
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 nemohermes <sandbox-name> doctor, correct the reported condition, then run nemohermes 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=<value> 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 nemohermes <sandbox-name> 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,
destroychecks 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,
destroyreports unknown presence, removes no resources, and preserves the recovery record. Correct the OpenShell gateway or list failure, then rerundestroy. - For the existing residual-cleanup path,
destroyselects 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.destroyremoves 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:
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:
--fresh alone does not clear the recovery record or permit reuse of the retained sandbox name.
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 for the identity checks and failure conditions.
Use --fresh to discard the saved onboarding session and start the wizard from the beginning. This clears stale or failed session state before NemoClaw creates a new session record. It also bypasses locally recorded sandbox base-image resolution metadata and reruns normal candidate resolution. --fresh takes precedence over a base-image hint carried from a rebuild, so NemoClaw does not use that recorded hint. The installer also accepts --fresh and forwards it to nemohermes onboard, which skips automatic resume detection. --resume and --fresh are mutually exclusive. For an existing completed sandbox, use --fresh --name <sandbox-name> --recreate-sandbox when you intentionally want onboarding to replace that sandbox with a new provider, model, agent, or startup setting. Use nemohermes <sandbox-name> 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
--freshwhen 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
--resumeor--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, 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.
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; 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 <progressive|direct>
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.
To change an existing sandbox, recreate it explicitly:
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.
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:
Base-image selection follows this precedence:
--freshorNEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1bypasses recorded metadata and reruns normal candidate resolution. These controls are equivalent for base-image selection.- Without a bypass, NemoClaw validates and reuses the recorded hint when possible.
- 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 nemohermes onboard when you need to create or recreate
the OpenShell gateway or sandbox. Avoid openshell self-update, npm update -g openshell, or
openshell sandbox create directly unless you intend to manage OpenShell separately and then
rerun nemohermes onboard.
Use --fresh to ignore any saved onboarding session and restart the wizard from scratch. This is useful after an interrupted nemohermes onboard run when you want to discard saved state instead of continuing it with --resume.
The installer detects existing sandbox sessions before onboarding and prints a warning if any are found. To make the installer abort instead of continuing, set NEMOCLAW_SINGLE_SESSION=1:
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:
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 nemohermes backup-all, but it does not block a prepared upgrade after the strict command succeeds:
For a non-default gateway, replace 8080 with its port and set gateway_name to nemoclaw-<selected-port>.
If an older OpenShell release rejects the named destroy command for the default nemohermes 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.
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 for details on inspection, rotation, and migration from earlier releases. The legacy nemohermes setup command is deprecated; use nemohermes onboard instead.
On a qualified DGX Spark, the provider menu 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:
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:
Do not set NEMOCLAW_MODEL for the managed llama.cpp path. For prerequisites, external traffic, verification, and recovery, refer to 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.
It then prompts for optional web search and messaging channels, builds and starts the sandbox, and asks for a policy tier that controls the default set of network policy presets applied to the sandbox. Four tiers are available:
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. 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):
Unset, blank, or whitespace-only NEMOCLAW_POLICY_TIER values use the balanced default. In non-interactive mode, any non-blank value must be one of restricted, balanced, open, or personal; otherwise onboarding exits before preflight, gateway, or inference side effects with an error listing the valid options. Interactive onboarding ignores an invalid environment value and shows the normal tier prompt.
NEMOCLAW_POLICY_MODE controls how non-interactive onboarding reconciles the tier-derived suggestions against the sandbox’s currently-applied presets. The default is suggested, which is additive. Onboarding applies tier defaults and preserves any presets you previously added with nemohermes <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.
For non-interactive onboarding, you must explicitly accept the third-party software notice:
or:
For scripted installer runs, pass explicit acceptance to the bash side of the installer pipe:
If the installer cannot prompt for the notice in a terminal and no explicit acceptance is set, it exits before installing Node.js or the NemoClaw CLI.
Hermes supports Tavily Search through NemoClaw onboarding and does not support Brave Search. To enable Tavily in non-interactive mode, set the provider and matching key.
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: <suggested-slug> 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 <name> to target a specific installed agent profile during onboarding. The nemohermes onboard --help output lists installed runtime names inline, and nemohermes agents list shows the same runtimes with manifest descriptions.
Use --control-ui-port <N> 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.
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 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 nemohermes <name> 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 nemohermes onboard is safe to run just to check preflight output. An interrupted run prints the resume command and exits with status 130 for Ctrl+C or 143 for SIGTERM. For Linux Docker-driver gateways, onboarding also checks that a helper container on the OpenShell Docker network can reach host.openshell.internal:<gateway-port>. If a host firewall blocks that sandbox path, onboarding exits with a sudo ufw allow from <subnet> to <gateway-ip> port <gateway-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 <Dockerfile>
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. 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.
The Dockerfile path must exist. Missing paths fail during command parsing before preflight, gateway setup, inference setup, or sandbox creation starts.
The file can have any name; if it is not already named Dockerfile, onboard copies it to Dockerfile inside the staged build context automatically. To create an isolated build context, create a dedicated directory that contains only the Dockerfile and the files it needs:
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. 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:
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 <sandbox> or NEMOCLAW_SANDBOX_NAME so a --from build cannot silently clobber the default my-assistant sandbox.
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 <repository>@<digest>
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.
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 <sandbox>
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.
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 <Dockerfile> with non-interactive onboarding requires one of --name or NEMOCLAW_SANDBOX_NAME; otherwise onboarding exits rather than silently defaulting to my-assistant and clobbering the default sandbox.
nemohermes onboard --from
Use a custom Dockerfile for the sandbox image. This variant of nemohermes onboard accepts a --from <Dockerfile> 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.
GPU Passthrough
When nemohermes onboard detects an NVIDIA GPU on the host, it enables OpenShell GPU passthrough at both the gateway and sandbox level by default. The nvidia-smi probes require a successful result and reject placeholder JMJWOA-Generic-* GPU names unless NemoClaw can prove a supported NVIDIA platform or GPU execution. NemoClaw treats a recognized NVIDIA product model from /sys/class/dmi/id/product_name or /sys/firmware/devicetree/base/model, or a known Tegra device node, as authoritative platform identity. On eligible native or 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 for the current support boundary. For the proof command, timeout control, and failure recovery, refer to 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 <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 <index-or-uuid> 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-smimust succeed. - On Jetson/Tegra hosts shipping without
nvidia-smi, the devicetree firmware fallback substitutes.
- On generic NVIDIA hosts,
- NVIDIA Container Toolkit configured for Docker.
When GPU passthrough is enabled and a gateway already exists without it, onboarding first checks whether replacing the CPU-only gateway is safe. If no other registered sandbox depends on that gateway, or if --recreate-sandbox is recreating the only registered sandbox with the same name, onboarding cleans up the stale gateway and continues. If other sandboxes depend on the gateway or Docker state is unclear, onboarding exits without cleanup and prints targeted destroy or gateway-removal guidance. To add GPU to an existing sandbox, rerun with --recreate-sandbox. Leave NEMOCLAW_DOCKER_GPU_PATCH unset or set it to auto for native-only GPU onboarding on ordinary native Linux. Set NEMOCLAW_DOCKER_GPU_PATCH=fallback to explicitly opt into one bounded native-to-compatibility retry on ordinary native Linux. Set NEMOCLAW_DOCKER_GPU_PATCH=0 to require native OpenShell GPU injection on ordinary native Linux or Jetson/Tegra. Set NEMOCLAW_DOCKER_GPU_PATCH=1 to use only the compatibility path on ordinary native Linux. Other legacy nonzero values keep that behavior through the v0.0.x release line and will be removed in v0.1.0. Use NEMOCLAW_DOCKER_GPU_PATCH=0 on Jetson/Tegra only for troubleshooting because it bypasses Tegra device-group propagation and CUDA may not initialize. Docker Desktop WSL ignores NEMOCLAW_DOCKER_GPU_PATCH=0 because GPU passthrough on that runtime requires the compatibility patch. Use --no-sandbox-gpu, --no-gpu, or NEMOCLAW_SANDBOX_GPU=0 when you want to disable sandbox GPU passthrough on Docker Desktop WSL.
nemohermes list
List 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 nemohermes list recovers from the live OpenShell gateway.
The gateway sandbox list does not expose the agent.
The row does not include the former derived connected boolean.
Sandboxes with an active SSH session are marked with a ● indicator so you can tell at a glance which sandbox you are already connected to in another terminal.
When 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:<port>/.
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.
nemohermes use <name>
Promote a registered sandbox to the default. This is the first-class replacement for hand-editing ~/.nemoclaw/sandboxes.json; it updates the registry through the same atomic, lock-guarded path that nemohermes onboard uses for the initial default. Subsequent commands and the NEMOCLAW_SANDBOX_NAME resolution order then pick up the new default automatically. Pass --json to receive a machine-readable result indicating whether the registry was updated, the sandbox was already the default, or the name is unknown.
nemohermes use is a thin selector and never mutates the sandbox itself. It fails with a non-zero exit and a known-sandbox list when the requested name is not registered, so scripts can branch safely on the outcome.
nemohermes launch <name>
Connect to a sandbox and start its agent in one host-side command. Use it instead of running nemohermes <name> connect and then typing the agent command inside the sandbox.
launch runs the complete preflight from nemohermes <name> connect when no launch-readiness lease is usable. That path includes the readiness wait, in-sandbox agent process recovery, and inference-route reconciliation. A successful complete preflight can publish a credential-free launch-readiness lease with a fixed 24-hour lifetime on Linux. Lease acceptance and publication are currently Linux-only and require a secure, independently writable OS per-user runtime authority under /run/user/<numeric-uid>. 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
ReadyorRunningstate. -
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 and supported fixed hosted selections verify their recorded sandbox-attached provider and request the model at its native endpoint without a shared-route models probe. Retained legacy, custom, and local shared routes use
inference.local. Their models probe must return HTTP 2xx, except that a retained legacyopenrouter-apishared route can return HTTP 404 forGET /v1/modelswhen 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 ordinaryconnect. -
The agent runtime and its required host-side forwards pass their semantic health checks.
Hermes and LangChain Deep Agents Code retain their existing session setup on the lease-accepted path.
After these checks pass, launch can skip duplicate recovery, readiness polling, and inference-route repair. The lease does not replace a health check or authorize repair. For missing, expired, malformed, inaccessible, mismatched, or unhealthy evidence, NemoClaw fences any prior acceptable evidence before it runs the complete preflight. Ordinary launch continues only when NemoClaw proves that no old authority or evidence can exist, or durably rotates the runtime epoch. If an old epoch might exist and cannot be durably rotated, launch stops before complete preflight or recovery. Its redacted guidance asks you to repair the current user’s secure OS runtime authority and NemoClaw state permissions, then retry. A failed live check never becomes a successful launch because a lease exists.
Immediately before the first mutation in the complete preflight, the producer revalidates its sandbox-global runtime epoch while holding the sandbox lifecycle lock followed by the owning gateway lock. It holds both locks through all mutations in the complete preflight, final state capture, and publication. If another producer has replaced the epoch, the stale producer makes no changes and re-inspects the newer lease.
The 24-hour lifetime does not extend when you launch repeatedly. Exiting the agent with /exit does not revoke the lease. If state changes before expiry, NemoClaw fences the old evidence and runs the complete preflight. A successful preflight in that interval keeps the original start and expiry time. After expiry, a successful complete preflight starts a new 24-hour lease only when publication succeeds.
If unsafe or malformed authority history makes the prior lease timeline untrustworthy, NemoClaw durably invalidates the old epoch and starts one conservative 24-hour quarantine. Both wall time and monotonic uptime must span the full quarantine, and publication remains disabled during it. Repeated attempts do not extend the quarantine. After it elapses, the next successful complete preflight can publish a new fixed 24-hour lease. You do not create or refresh this lease manually, and launch has no lease-control flags. After lease validation or the automatic fallback that runs the complete preflight, launch starts the sandbox’s agent in your terminal instead of opening a sandbox shell.
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.
The sandbox name is required, and the command takes no flags. The sandbox must already exist in the local NemoClaw state. If it is not registered locally, launch exits before it runs an OpenShell command or readiness recovery and reports that the sandbox is not registered in the local NemoClaw state. When the agent exits, you return to the host shell.
launch returns the agent’s exit code.
When you want a shell inside the sandbox rather than an agent session, use nemohermes <name> connect.
nemohermes <name> connect
Connect to a sandbox by name. Bare nemohermes connect (no sandbox name) connects to the registry default. NemoClaw uses the stored default when it names a non-pending registered sandbox, then falls back to the first non-pending registration. If only pending registrations remain, the command exits non-zero and tells you to wait for onboarding or remove the incomplete sandbox. If the registry remains empty after recovery, it tells you to run nemohermes onboard. A registered sandbox literally named connect keeps the name-first reading. If the sandbox is not yet in the Ready phase, connect polls openshell sandbox list every few seconds and prints the current phase. This gives you progress output right after onboarding, when the 2.4 GB image is still pulling, instead of a silent hang. Control the wait budget with NEMOCLAW_CONNECT_TIMEOUT in integer seconds. An interactive connection defaults to 120 seconds, while --probe-only and nemohermes <name> start default to 300 seconds so a scripted health check can wait through a cold sandbox start. When the deadline expires, connect exits non-zero with the last-seen phase.
On a TTY, a one-shot hint prints before dropping into the sandbox shell. The hint is agent-aware. It names the correct TUI command for the sandbox’s agent and reminds you to use /exit to leave the chat before exit returns you to the host shell. Set NEMOCLAW_NO_CONNECT_HINT=1 to suppress the hint in scripted workflows. If the sandbox is running an outdated agent version, a non-blocking warning prints before connecting with a nemohermes <name> 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 for provider-global identity, route drift, and hard-error recovery.
Use nemohermes inference set --provider <provider> --model <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 nemohermes <name> doctor.
For NVIDIA Endpoints and supported fixed hosted selections, 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.
The request must return a structurally valid successful inference result before connect opens SSH.
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 nemohermes onboard after a reboot in this case.
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/<numeric-uid>. 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:
readinesswaits for the sandbox state.authorityvalidates launch-readiness authority and evidence.lifecycleverifies or recovers the selected runtime lifecycle.gatewayverifies the owning gateway path.processesverifies or repairs managed in-sandbox processes.forwardverifies or restores required host forwards.inferenceverifies the selected inference route.pairingsettles OpenClaw operator pairing when applicable.publicationpublishes 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.<observation>=<milliseconds>ms and readiness.<observation>.attempts=<count>.
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=<stage> 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 nemohermes launch <name>.
Use nemohermes launch <name> when you want launch-readiness validation, an automatic fallback that runs the complete preflight, and then the agent instead of a sandbox shell.
nemohermes <name> exec
Run a single command non-interactively in a running sandbox via the OpenShell exec endpoint. The command runs as the sandbox user with HOME=/sandbox, so in-sandbox tooling resolves NemoClaw-provisioned config the same way it does for connect and openshell sandbox connect. This is the supported substitute for docker exec on the sandbox container; raw docker exec runs as root and lands on HOME=/root, where the selected agent config is not present. For a registered sandbox, NemoClaw selects its recorded owning OpenShell gateway before the workdir probe and command dispatch. If gateway selection fails, exec stops without running the sandbox command.
Hermes config resolves under /sandbox/.hermes.
Everything after -- is forwarded verbatim to the sandbox command, including flags the inner command needs.
The exit code is the remote command’s exit code.
By default, NemoClaw inherits caller stdin only when it is a terminal. Non-terminal or unavailable stdin is closed so SSH, CI, and other one-shot commands cannot wait on an inherited pipe. Pass --stdin to forward an intentional pipe, or --no-stdin to close terminal stdin explicitly.
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:
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.
nemohermes <name> agent
The agent wrapper rejects Hermes sandboxes with guidance for the Hermes HTTP API. Each Hermes sandbox exposes an OpenAI-compatible API inside the sandbox on its own port, which defaults to 8642, so non-interactive use does not need a wrapper command. When another sandbox or a host listener already holds 8642, the sandbox receives the next free port from 8642 through 8652. The rejection message names that port and the NemoClaw recovery command for its managed forward. Use the allocated API port shown by nemohermes <name> status below.
Recover the managed forward, then POST chat completions directly:
Advanced Sandbox Maintenance Commands
The following commands are available for targeted host-side maintenance, but they are not part of the top-level public command list.
nemohermes <name> 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.
nemohermes <name> config set
Write one value into the agent configuration in a sandbox. The command validates every HTTP and HTTPS URL in the value, including URLs nested inside JSON objects or arrays. It pins an HTTP host to the validated IP address.
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.
Host-side config, inference, gateway recovery, backup, policy, channel, and sandbox destruction mutations serialize per sandbox.
nemohermes <name> recover
Restore sandbox readiness and re-establish host-side forwards without opening an SSH session.
Use this after a sandbox crash or when nemohermes <name> status reports a stopped sandbox or an unhealthy forward.
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 nemohermes <name> gateway restart when you deliberately need a running gateway to reload runtime configuration or plugins.
nemohermes <name> 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.
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 nemohermes <name> config set and nemohermes 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 nemohermes <name> stop and nemohermes <name> 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=<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 nemohermes <name> stop followed by nemohermes <name> 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 nemohermes <name> 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.
nemohermes <name> 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 nemohermes <name> destroy when you want to delete it instead.
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. 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.
nemohermes <name> start
Ask OpenShell to start a sandbox stopped with nemohermes <name> stop or by a host reboot, then repair the in-sandbox gateway and host-side forwards the same way nemohermes <name> recover does.
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.
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 and supported fixed hosted providers use native endpoints through sandbox-attached OpenShell providers. Custom and local providers retain the shared inference.local route. A reachable provider path can still reject an inference request or return an invalid result, so the command exits non-zero in either case. It prints the probe result, including the HTTP status when the path returned one, 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.
nemohermes <name> status
Show sandbox-scoped status, health, and inference configuration for one registered sandbox. Use this form when you care about a specific sandbox’s live OpenShell state, agent runtime, inference health, GPU proof, permissions, and recovery hints. Do not pass a sandbox name to nemohermes status; that command is the global all-sandbox/service overview. NemoClaw resolves the sandbox’s recorded owning OpenShell gateway before querying live state. If another gateway is active, it selects the owner and queries again instead of trusting a result from the sibling gateway.
For a 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 or fixed hosted 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 and fixed hosted provider attachments do not report shared-route drift. 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 for the route-sharing workflow. openshellDriver and openshellVersion are always strings (falling back to "unknown" when the registry has no value), so consumers can rely on typeof checks. agent is always a string and reports openclaw when the registry records no agent for the sandbox. failureLayer is null when no preflight failure was detected and otherwise one of docker_unreachable, sandbox_container_stopped, or sandbox_dashboard_port_conflict; when set, inferenceHealth is suppressed to null so automation does not see a stale remote-provider healthy status during a local outage. inferenceHealth.ok reports whether the selected provider path returned a structurally valid result for one request sent from inside the sandbox. The result must match Chat Completions, Responses, or Anthropic Messages for the selected route. An empty body, malformed JSON, provider-error envelope, or wrong response shape reports unhealthy, even with a 2xx status. The probe captures at most 64 KiB and does not include the response body in diagnostics. The 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 and hosted 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, 502, 503, or 504, status retries the provider path and inference request together 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, every other failure is final on the first attempt with no delay: HTTP 401, 403, 404, and 500, an invalid 2xx response body, a request that returned no HTTP status, and a failing provider-path probe. 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:
unauthorizedwhen the route rejected it with HTTP401or403.unhealthywhen the route returned another failing HTTP status or an invalid 2xx response body.unreachablewhen the request returned no HTTP status, including a probe that could not run.
A host-side upstream probe under inferenceHealth.subprobes stays a diagnostic and does not change inferenceHealth.ok, because the sandbox route is the one the agent uses. When the route probe failed, or the sandbox records no provider or no model, NemoClaw skips the inference request and inferenceHealth reports the route probe result alone. dockerPaused is true when NemoClaw detects that the Docker-driver sandbox container is paused. In that case, text output keeps OpenShell’s authoritative phase but prints a docker unpause <container> recovery hint instead of sending you directly to rebuild. For terminal runtime sandboxes, the command also checks cgroup OOM kill counters. If the counter records an OOM kill, text output prints Runtime health: degraded (... OOM kill recorded) and points you to nemohermes <name> 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 (<agent> 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, 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 nemohermes list. The alias form nemohermes <name> status --json requires the sandbox to be registered locally; the canonical form nemohermes sandbox status <name> --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:
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 nemohermes <sandbox-name> destroy to remove the owning sandbox and its managed runtime, and onboard again.
The shared model cache is preserved. See Upgrade or Roll Back.
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 and supported fixed hosted providers use native endpoints through sandbox-attached OpenShell providers. Custom and local providers retain the shared inference.local route. That inference request is the authoritative inference health check, and both checks exercise the path that agent traffic uses. The main Inference line reports one of these states:
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, nemohermes <name> 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 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 the request reaches the time limit, NemoClaw reports the provider as not probed and leaves model health unverified instead of reporting it as unhealthy. These checks are diagnostic only and do not override the authoritative 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, nemohermes <name> 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 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 nemohermes <sandbox-name> 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 nemohermes <sandbox-name> 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 nemohermes <name> 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: <label>) so automation and operators can distinguish configured GPU passthrough from proven CUDA access. Failed proofs include remediation guidance for the detected platform.
An SSH sessions line reports how many active SSH sessions the sandbox has, or none; the line is omitted when the session probe is unavailable.
The sandbox list in the status output includes the dashboard port suffix for sandboxes with a recorded dashboard port.
The Policy section displays the live enforced policy (fetched via openshell policy get --full), which reflects presets added or removed after sandbox creation. When OpenShell reports an active policy version, the displayed YAML version line uses that active version instead of the static schema version. If the sandbox is running an outdated agent version, the output includes an Update line with the available version and a nemohermes <name> rebuild hint.
When NemoClaw detects a messaging overlap between sandboxes in the selected OpenShell gateway’s
sandbox registry, the output includes a cross-sandbox overlap warning. The command cannot report
overlaps in an independent OpenShell gateway’s registry. The command also tails /tmp/gateway.log
inside the default sandbox and flags Telegram 409 Conflict errors that indicate a duplicate
consumer for the bot token.
Checking the Hermes version
Refer to Update Sandboxes for the Hermes version pin and rebuild policy.
nemohermes <name> status prints the running Hermes version on the Agent line:
Expected output:
If the sandbox is running an older Hermes version than this NemoClaw release expects, status and connect add an Update line pointing at nemohermes <name> rebuild to pick up the newer version. The rebuild reuses the existing sandbox name and transfers the complete native home while OpenShell keeps credential stores under its own lifecycle.
nemohermes <name> doctor
Run a focused health check for one sandbox and the host services it depends on. The command checks the local CLI build, Docker daemon, OpenShell CLI, NemoClaw gateway container, gateway port mapping, live sandbox state, inference route, configured-provider model invocation, Ollama reachability, and the cloudflared tunnel state.
Use nemohermes doctor when you need only the host and gateway checks or when no sandbox exists yet. A sandbox named doctor does not change the bare global command; use nemohermes doctor connect to connect to that sandbox explicitly.
For gateway-based agents, it also reports messaging channel conflicts within the selected OpenShell gateway’s sandbox registry.
doctor also checks whether the sandbox registry contains the metadata required for rebuild, upgrade, recovery, and reboot.
When lifecycle metadata is incomplete, the report names the missing or invalid fields and affected operations without printing stored values.
Dashboard metadata is required only for agents that manage a dashboard.
The Registered gateway binding result depends on the sandbox registry:
- For a registered sandbox with a valid binding,
doctorreports a successful check with the resolved gateway name. - For a registered sandbox with an invalid binding, the check fails, and
doctordoes not select, probe, or recover a gateway from that binding. - For an unregistered sandbox name,
doctoruses the gateway selected byNEMOCLAW_GATEWAY_PORTfor its other gateway checks and omits theRegistered gateway bindingcheck.
For inference health, doctor treats the selected provider path inside the sandbox as authoritative. Providers that still use the shared route probe the shared gateway route at https://inference.local/v1/models; responses from 200 through 499, including 401 and 403, pass that reachability check. NVIDIA Endpoints instead probes its sandbox-attached provider at https://integrate.api.nvidia.com/v1/models and requires a 2xx response. For the shared route, HTTP 500 through 599, interim 100 through 199, transport failures with status 000, invalid status values, and an unavailable authoritative probe fail the check. For native NVIDIA, any non-2xx response or unavailable probe fails it. Fixed hosted providers verify their recorded attachment and make an inference request to their native endpoint; a healthy shared route cannot satisfy that check. Host-side upstream probes use the same authenticated model-invocation checks as status and remain diagnostic only, so their failure does not fail doctor when the authoritative in-sandbox path is reachable. For gateway runtimes, doctor also reports an informational Serving process: not checked result because its fresh sandbox probes do not attest the long-running gateway process. This result does not fail the readiness check. Terminal runtimes omit it because they have no long-running gateway process. The Inference Route check warns when either the provider or model is unknown. After the gateway is healthy, run nemohermes <name> status to refresh the route information.
Warnings do not make the command fail. Failed checks, including a failed or unavailable authoritative inference route, exit non-zero so scripts can use doctor as a readiness gate. Use --json for machine-readable output. For a compatible-endpoint route that uses openai-completions, the JSON report includes an informational Inference check labeled Reasoning effort. The check reports low, medium, high, or endpoint-default and never includes credentials. Because the check has info status, it does not change the command’s exit status.
For a sandbox that owns managed llama.cpp, doctor adds secret-free identity and runtime checks. The runtime check passes only when the exact container is running. It warns for preparing or stopped, and it fails for absent, conflict, or unknown. The recovery hint tells you to rerun onboarding for the same sandbox so NemoClaw can use the persisted receipt and create journal.
nemohermes <name> exec
Run a command non-interactively inside a running sandbox through the OpenShell exec endpoint. The command runs as the sandbox user with HOME=/sandbox. Use -- to separate exec options from the command you want to run inside the sandbox.
The command exits with 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.
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:
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.
nemohermes <name> logs
View sandbox logs.
Use --follow to stream output in real time.
Use --tail <lines> or -n <lines> to limit the number of returned lines.
Use --since <duration> to show recent logs only, such as 5m, 1h, or 30s.
When --since is not set, the command reads both agent gateway output and OpenShell audit events,
so policy denials appear alongside the gateway log stream. With --since, the command reads only
OpenShell logs. If one log source is unavailable, NemoClaw prints a warning and keeps reading the
remaining source.
If NemoClaw cannot enable OpenShell audit logs, it prints a warning and policy-denial events can be
missing. With NEMOCLAW_NO_AUTO_AUDIT_LOGS=1, NemoClaw leaves the audit setting unchanged and does
not print that warning; policy-denial events can also be missing if audit logging was disabled. See
the audit-setting guidance.
NemoClaw’s --tail <lines> flag is a line-count flag; the lower-level openshell logs --tail flag means follow live output, so use openshell logs <sandbox> -n <lines> when running OpenShell directly for a fixed line count.
nemohermes <name> dashboard-url
Print the browser dashboard URL for a running Hermes sandbox. Hermes manages dashboard sessions itself, so this command prints a plain URL without an OpenClaw #token= fragment. The built-in dashboard is forwarded on port 18789 by default.
The Hermes OpenAI-compatible API is separate and serves /v1 on a per-sandbox port that defaults to 8642. Run openshell forward list to read the host bind for the dashboard and API forwards.
When onboarding records a non-loopback CHAT_UI_URL, dashboard-url returns that browser-facing URL.
The host forward remains bound to loopback unless you explicitly configure remote binding.
nemohermes <name> gateway-token
Print the Hermes API bearer token for a running sandbox to stdout. NemoClaw retrieves the sandbox’s API_SERVER_KEY, which authenticates OpenAI-compatible clients on the forwarded API port. During a normal sandbox lifecycle, the token is generated once for each sandbox home. Different sandbox homes receive different tokens. NemoClaw preserves it across a gateway restart, sandbox stop and start, and host OpenShell gateway restart. When you rebuild or replace the sandbox, the replacement home receives a new token. At gateway startup, NemoClaw also generates a new token when API_SERVER_KEY is missing or is not exactly 64 lowercase hexadecimal characters. If an ordinary restart changes the token while the existing API_SERVER_KEY was present and valid, collect the before and after sandbox identity plus redacted mint logs and report it as a bug. Capture the token and pass it in the Authorization header:
Treat the token like a password. Do not log it, share it, or commit it to version control.
The sandbox must be running for nemohermes my-assistant gateway-token --quiet to retrieve the token. Use this supported command instead of reading or editing .hermes/.env directly. For browser access to the dashboard, use nemohermes my-assistant dashboard-url.
nemohermes <name> destroy
Stop managed local inference resources, remove runtime-provider-owned resources created during onboarding, and delete the sandbox. This removes the sandbox from the registry. NemoClaw resolves the registry that owns the sandbox before it starts cleanup, even when another local OpenShell gateway is active. For Ollama-backed sandboxes, destroy also asks Ollama to unload currently loaded models and clears stale auth proxy state on a best-effort basis.
destroy considers retirement of the host-global nemoclaw-vllm container for a sandbox with provider vllm-local, including Local NIM.
It requires confirmed sandbox deletion and no remaining registered vllm-local consumer in any gateway state root.
Sandboxes with a runtime-provider host-local inference receipt use that provider’s cleanup instead.
destroy removes a verified NemoClaw-managed container by its inspected ID and frees any GPU memory it held.
Pass --keep-vllm or set NEMOCLAW_KEEP_VLLM=1 to preserve the container for a later sandbox.
destroy does not claim that retirement completed when:
- Another registered sandbox uses provider
vllm-local. - The container lacks the NemoClaw managed label.
- The container carries distributed vLLM labels but has no matching ownership receipt.
- An authenticated container does not match its persisted API key and receipt.
- A distributed vLLM receipt owns the container.
- NemoClaw cannot read every gateway sandbox registry.
- Docker is unavailable or cannot confirm whether the container exists.
- Container removal or private-state cleanup fails.
Before eligible registry removal, destroy writes the sandbox name to ~/.nemoclaw/host-local-vllm-pending-retirement.json.
This record supports a same-name retry after the registry entry is gone.
If the write fails and no matching record can be read, destroy preserves the registry entry and exits with an error.
Unfinished retirement retains the pending record.
Resolve the reported cause, then rerun the same destroy command to finish cleanup.
A completed retirement or a decision to keep the container for a consumer, preservation option, or distributed owner clears the record.
For Model Router sandboxes, destroy keeps the process and recovery identity when another sandbox uses the port or when session, process, or absence checks are inconclusive. It also preserves a replacement onboarding session when the captured session identity changed. If the captured session uses the destroyed sandbox name with another router port, destroy clears only the sandbox association and preserves that router’s recovery identity. For lock order, same-port peer handling, and cleanup checks, refer to Set Up Model Router.
If destroy warns that it could not identify or stop a listener for the deleted sandbox:
- Inspect the current listener process immediately before you stop anything.
- Stop it only if its command line identifies the Model Router on the named port.
- Do not stop the router recorded by a preserved session for another port.
- Do not stop a previously reported process ID if its command line no longer matches.
Download any files you need before destroying the sandbox; do not rely on retained OpenShell storage as a backup. NemoClaw removes managed OpenClaw and Hermes state volumes after confirmed deletion. Because OpenShell can retain the same-name /sandbox volume, Deep Agents Code destroy clears that complete persistence root before deletion and stops with the registry entry intact if cleanup cannot be confirmed.
If you want to upgrade the sandbox while preserving state, use nemohermes <name> rebuild instead.
If another terminal has an active SSH session to the sandbox, destroy prints an active-session warning and requires a second confirmation before it proceeds. Pass --yes, -y, or --force, or set NEMOCLAW_NON_INTERACTIVE=1, to authorize deletion without prompting in scripted workflows. These controls do not suppress the active-session warning. The warning lists the detected process IDs, and destroy still terminates those sessions with a Broken pipe error.
For eligible recovery without a sandbox identity on native Linux with default Docker, --force archives and removes local tracking after the owning gateway and current Docker daemon confirm absence.
It preserves runtime resources and shared providers; cleanup on the original runtime remains unverified.
A conflicting active session for the same name, sandbox-scoped providers, or additional resource ownership still blocks this operation.
The command prints the private archive path and keeps the archive after recovery.
Before changing a Docker-backed sandbox, NemoClaw inspects every container with the requested openshell.ai/sandbox-name label. The command continues when Docker returns no matching containers. For one matching container, the command continues only when all these labels have the required values:
openshell.ai/managed-by=openshell- A nonempty
openshell.ai/sandbox-workspace - A nonempty
openshell.ai/sandbox-id
In an ordinary destroy flow, if the initial inspection cannot complete, more than one container matches, a matching container has conflicting or incomplete labels, or Docker returns malformed identity data, destroy exits before changing sandbox resources.
Retained-sandbox recovery accepts multiple managed containers only when every immutable sandbox ID matches the retained recovery fingerprint.
The identity checks still apply with --force, --yes, or NEMOCLAW_NON_INTERACTIVE=1; those controls authorize confirmation but do not authorize an unproven container identity.
NemoClaw rechecks the identity after read-only preflight, before provider cleanup, and synchronously at the sandbox-deletion boundary.
If a later recheck detects drift or fails, destroy refuses sandbox deletion, preserves local ownership state, and reports any earlier cleanup already performed.
If OpenShell reports the sandbox absent after preflight captured one matching Docker container, destroy rechecks and removes only that container ID.
If Docker reports another OpenShell-managed container, removal fails, or NemoClaw cannot confirm removal, destroy exits nonzero and preserves the registry entry.
Correct the reported Docker state, then rerun destroy.
If Docker cannot complete the inspection, correct the reported Docker error before you rerun destroy.
For common recovery steps, refer to Docker is not running and Docker permission denied on Linux.
If onboarding fails before NemoClaw records a runtime provider, keep the original NEMOCLAW_GATEWAY_RUNTIME selection set when you rerun destroy.
Recorded sandbox or gateway ownership takes precedence over that fallback and must agree when both are present.
If destroy reports conflicting, incomplete, or malformed identity data, inspect the matching containers:
The labels show what each container claims. They do not prove container ownership.
Do not remove or recreate a container until you verify its purpose, ownership, and data-retention requirements. Removing or recreating a container can discard state that is not stored in a volume.
Resolve a conflict through the workflow that created the conflicting container. Docker cannot change labels on an existing container. Rerun the query after you resolve the conflict. Rerun destroy only when the query returns one complete expected label set that you verified belongs to the target sandbox, or no containers after you independently confirm that the sandbox is absent.
When the sandbox has MCP entries, destroy reads the current agent-native configuration and joins it to the live OpenShell policy and providers before deletion. It does not scrub the agent file or write an MCP destroy marker. OpenShell deletion owns sandbox-scoped policy and attachment cleanup. Workspace-level MCP providers and stored credentials are preserved, and NemoClaw prints their names for later inspection. --force does not bypass an unavailable, unsafe, or conflicting MCP source.
By default, unattended final-sandbox destroys (--yes, --force, or NEMOCLAW_NON_INTERACTIVE=1) remove the shared NemoClaw gateway on macOS so the host listener is released, while Linux preserves it for reuse.
Pass --cleanup-gateway to force removal, or --no-cleanup-gateway to force preservation.
These flags override both NEMOCLAW_CLEANUP_GATEWAY and the platform default.
When final-sandbox gateway cleanup is enabled or you accept its prompt, destroy confirms through openshell sandbox list that no live sandbox remains on the gateway.
A listed sandbox counts as live unless it is in the Error or Failed phase and NemoClaw confirms that no matching Docker container is running.
With the native Podman provider, NemoClaw does not probe Docker, so every listed sandbox counts as live and gateway cleanup requires an empty list.
If the deleted sandbox is the only listed live sandbox, destroy polls for up to 30 seconds until that row is gone.
If the deleted sandbox is still listed after that wait, if a different live sandbox remains, or if the list command fails, destroy leaves the gateway running and names the live sandboxes or the failed command.
When cleanup comes from the platform default, the environment, or an accepted prompt, destroy still exits 0 after a successful sandbox deletion.
When you pass --cleanup-gateway, destroy exits nonzero and the message states that the flag was not applied.
After that message, confirm that openshell sandbox list -g <gateway-name> reports no sandboxes.
Then run openshell gateway remove <gateway-name> to remove the gateway.
Cleaning up the gateway after the last sandbox also purges the shared cluster volume that retains the per-name persistent volume.
If NemoClaw detects active SSH sessions before destroy, it warns that destroy terminates them with a Broken pipe error and lists their process IDs.
This warning prints before the confirmation prompt and when --yes or --force skips that prompt.
If final gateway cleanup finds a live PID-file process whose command line does not prove it owns the target gateway, destroy exits nonzero after sandbox and registry deletion and skips gateway and volume removal.
NemoClaw preserves the per-gateway PID file and runtime marker so you can inspect the process.
Stop only the listener that matches the target gateway, then rerun destroy to converge cleanup.
When the default-port gateway runs under the packaged OpenShell gateway service, gateway cleanup stops that service before it reaps host processes.
The service is stopped, not disabled or removed, and the next onboarding run starts it again.
On headless Linux, the packaged service can exist while its systemd user manager is unavailable and the gateway runs through the standalone fallback.
For this recognized manager-unavailable failure only, destroy uses the per-gateway PID file when the service is not enabled for automatic activation.
If the recorded PID is live, its command line must match the exact gateway name and port before destroy stops it.
If the recorded process has exited, destroy continues only after it verifies that the gateway port is free.
If a live PID does not prove gateway ownership or the port remains occupied, destroy exits nonzero and preserves the runtime evidence for inspection.
For any other service stop failure, destroy exits nonzero after sandbox and registry deletion, prints the status command for the service, and skips gateway and volume removal.
If the OpenShell command completes with a gateway transport error and the sandbox has no source-observed MCP entries, --force removes only NemoClaw’s local registry entry and local artifacts.
Gateway-side deletion remains unconfirmed, shared host-service and gateway teardown are skipped, and the sandbox and retained volume can still exist if the gateway returns.
Start the gateway with nemohermes <name> status and retry destroy when you need confirmed deletion.
If the OpenShell sandbox deletion command reaches its 60-second timeout, NemoClaw preserves the local registry entry under both --yes and --force.
Retry after the recorded gateway is available.
An MCP source that cannot be safely inspected disables the local-only fallback.
After OpenShell confirms deletion of a sandbox that owns managed llama.cpp, destroy revalidates the exact container, internal network, lifecycle journal, and gateway-scoped receipt. It removes those resources by inspected ID, then removes the API key and managed ownership state. It preserves the shared ~/.cache/huggingface/ cache. If exact cleanup fails, destroy preserves the sandbox registry entry and ownership state so you can correct the reported conflict and retry.
nemohermes <name> policy get
Export the sandbox’s OpenShell base policy as parsed YAML. The command runs openshell policy get --base, strips the metadata header, and replaces literal credential values with [STRIPPED_BY_MIGRATION]. Before using the file with openshell policy set, replace every marker with a supported OpenShell credential binding or resolver placeholder. The command exits nonzero for an OpenShell failure, empty response, or invalid policy YAML.
Use --raw to retain safe OpenShell metadata with the parsed, credential-redacted policy:
The --raw output omits unknown metadata fields and literal credentials.
Do not pass it to openshell policy set because the metadata header is not part of the policy document.
nemohermes <name> policy add
Add a policy preset to a sandbox. Presets extend the baseline network policy with additional endpoints. Before applying, the command shows which endpoints the preset would open and prompts for confirmation. The scope comes from the exact preset YAML and includes each endpoint’s host, port, access, protocol, TLS, and enforcement settings, allowed methods and paths, and binary allowlist. When a lifecycle operation reapplies a preset, NemoClaw compares it with the live policy and reports whether the preset opens new egress, replaces a drifted entry, or is already effective with no new egress.
To apply a specific preset without the interactive picker, pass its name as a positional argument:
The positional form is required in scripted workflows. Set NEMOCLAW_NON_INTERACTIVE=1 instead of --yes for the same non-interactive behavior. If the preset is already present with identical content, the command reports no changes. If its content differs, NemoClaw previews the change and asks for confirmation before applying it again.
Every mutation starts from the parsed base document returned by OpenShell, merges the requested built-in or custom content, submits the complete document, and verifies the live result. NemoClaw stores no applied-preset list or custom-policy copy in its registry. Custom preset names are encoded in namespaced keys in the live policy so later policy list and policy remove commands can derive them from OpenShell. If the live policy cannot be read or parsed, the command exits without writing a replacement.
With --from-file or --from-dir, pass a repeatable --trusted-private-host <exact-host-or-ip> option to admit matching RFC1918, carrier-grade network address translation (CGNAT), or IPv6 unique local endpoints. The option is invalid for built-in presets. You can supply exact hosts through NEMOCLAW_TRUSTED_PRIVATE_HOSTS instead, and NemoClaw combines the variable with command options. NemoClaw resolves each matching exact host and adds generated allowed_ips pins to an in-memory copy of the preset. User-authored allowed_ips remains rejected. Dry-run output shows the generated pins. Applying the preset places those pins in the current OpenShell policy, which rebuild carries forward without re-resolving ambient DNS.
Use --dry-run to audit a preset before applying it:
Apply a custom preset file when you need to grant access to an endpoint that is not covered by a built-in preset:
For a trusted private endpoint, preview the generated pins before applying them:
For batch workflows, apply all preset files from a directory:
Review every host in custom preset files before applying them. Custom presets bypass the built-in preset review process and can widen sandbox egress.
nemohermes <name> policy list
List available policy presets and show which ones match the current OpenShell policy. Built-in rows are scoped to the active agent. Custom preset rows are decoded from namespaced keys in that live document. NemoClaw does not cross-reference a local preset registry or display baseline-exclusion records.
Each active preset is annotated with display-time provenance:
[from <tier> tier]means the name appears in the current tier definition.[from <agent> agent]means the name is an agent-specific preset for the active agent.[user-added]covers other live presets.[source unverified (gateway unreachable)]appears only when OpenShell cannot be read; no local policy fallback is shown.
Provenance tags are inferred from the sandbox’s current tier and agent metadata at display time and are not persisted per preset. A preset whose name appears in the sandbox’s current tier YAML is labelled [from <tier> tier] even when an operator added it manually with policy add after onboarding. Agent-specific preset names are only labelled [from <agent> agent] when the active agent matches that label. For a LangChain Deep Agents Code sandbox, observability-otlp-local is labelled [from dcode agent].
nemohermes <name> policy remove
Remove a previously applied policy preset from a sandbox. The command derives applied presets from the current OpenShell policy, prompts you to select one, shows the endpoints that would be removed, and asks for confirmation before narrowing egress.
To remove a specific preset non-interactively, pass its name as a positional argument:
Set NEMOCLAW_NON_INTERACTIVE=1 as an alternative to --yes. Without a preset name, policy remove reports the same two picker errors as policy add and exits non-zero. If the preset is unknown or absent from the live OpenShell policy, the command exits non-zero with a clear error. When NemoClaw cannot query OpenShell, it refuses the mutation instead of consulting a local policy record.
Unchecking a preset in the onboard TUI checkbox also removes it from the sandbox.
nemohermes <name> policy exclude <key>
Remove one exact entry from the current OpenShell policy after previewing the egress and support impact that the change removes. The preview names the supported features that may stop working. The command refuses an entry that does not have a reviewed feature-impact disclosure. No exclusion record or replay journal is written: OpenShell’s resulting policy is the complete state, and rebuild carries that live document forward. The command refuses to exclude a key that an applied preset also requires, because removing that live key would remove the preset’s access. The critical managed_inference entry cannot currently be excluded pending product direction. Use --force or --yes for explicit non-interactive acknowledgement, or --dry-run to preview without changing the sandbox. A run with NEMOCLAW_NON_INTERACTIVE=1, or a run without a terminal on stdin, does not prompt and requires one of those acknowledgement flags.
To restore an entry, run nemohermes <name> policy restore <key> --dry-run to preview the current baseline egress, then run it with --force after review. If the current baseline no longer defines the key, the command reports that there is nothing to restore and leaves the live OpenShell policy unchanged.
nemohermes <name> policy restore <key>
Restore one entry from the current agent baseline into the current OpenShell policy. --dry-run lists the egress that restoration would allow again; after review, --force applies it. Both paths require explicit acknowledgement unless you use --dry-run; use --force or --yes for non-interactive acknowledgement. As with policy exclude, a run with NEMOCLAW_NON_INTERACTIVE=1, or a run without a terminal on stdin, does not prompt. The command writes no exclusion record or journal and verifies the resulting live OpenShell policy before returning.
The restore command accepts these flags:
nemohermes <name> policy explain
Print a redacted summary of the current OpenShell policy context for a sandbox so an agent or operator can reason about what is allowed, what is blocked, and how to request a change. The output covers inferred tier and preset context, allowed host categories, known unapplied presets, policy-change commands, and the support boundaries between NemoClaw, OpenShell, and the agent. Raw policy YAML, rule bodies, and credential metadata are deliberately not included.
Pass --json to emit the same context as a structured object for agent consumption:
The context also documents how a failed host or integration attempt should be classified. The classifications are blocked-by-policy, missing-approval, unsupported, and unknown, so the agent can pick a remediation step instead of surfacing a lower-level network error.
nemohermes <name> hosts-add
Add a host alias to the sandbox pod template. Use this when a sandbox needs a stable LAN-only name, such as a local SearXNG or internal model endpoint, without dropping to docker exec and kubectl patch. Host alias commands use the legacy Kubernetes gateway Sandbox resource path. In that older topology, the openshell-cluster-nemoclaw container runs an embedded k3s cluster with a sandboxes.agents.x-k8s.io custom resource definition, and an agent-sandbox-controller reconciles each Sandbox resource into the agent pod. They are not supported on Docker-driver or VM-driver sandboxes because those drivers do not run the gateway cluster container that owns this resource.
The command validates the hostname and IP address, rejects duplicate hostnames, and patches spec.podTemplate.spec.hostAliases on the sandbox resource.
nemohermes <name> hosts-list
List host aliases configured on the sandbox resource.
nemohermes <name> hosts-remove
Remove a hostname from the sandbox hostAliases list.
nemohermes <name> channels list
List the messaging channels supported by the sandbox’s agent runtime with a short description. Telegram, Discord, Slack, WeChat, WhatsApp, and Microsoft Teams are available for OpenClaw and Hermes. WeChat, WhatsApp, and Microsoft Teams are experimental. OpenClaw and Hermes also support experimental Google Chat.
The command reads the sandbox registry to select agent-compatible channel manifests. It does not inspect messaging credentials or the live sandbox runtime.
nemohermes <name> channels add <channel>
Register a messaging channel with the sandbox and rebuild so the image picks up the new channel. Channel enrollment uses these credential and pairing flows:
- Token paste (
telegram,discord,slack,teams): the command prompts for required channel inputs. It registers secret credentials with the OpenShell gateway and saves non-secret configuration for rebuilds. - Host-side QR (
wechat, experimental): the command renders an iLink QR code on the host and you scan it from WeChat on your phone. On confirm, NemoClaw captures the bot token, registers it with the OpenShell gateway, and stores non-secret per-account metadata (WECHAT_ACCOUNT_ID,WECHAT_BASE_URL,WECHAT_USER_ID) for the in-sandbox bridge. NemoClaw automatically adds the scanning operator’s WeChat user ID toWECHAT_ALLOWED_IDS. Supply additional comma-separated IDs to authorize more DM senders. NemoClaw advertises WeChat for both OpenClaw (the@tencent-weixin/openclaw-weixinplugin) and Hermes (the built-in iLink WeChat adapter). - In-sandbox QR (
whatsapp, experimental): the command records the channel without a host-side token or OpenShell credential provider. NemoClaw advertises WhatsApp for OpenClaw and Hermes sandboxes; after rebuild, runopenclaw channels login --channel whatsappfor OpenClaw orhermes whatsappfor Hermes. This intentionally leaves QR-created mutable session state in the sandbox until you unpair it or clear the durable agent state.
Google Chat uses an experimental token-paste flow for the service-account JSON on both agents. OpenClaw also requires interactive public-webhook confirmation and prompts for optional app-principal configuration during enrollment. Hermes instead prompts for the Google Cloud project ID, complete Pub/Sub subscription name, and email sender allowlist. It pulls inbound events from Pub/Sub over REST and does not create a public webhook endpoint.
After registering the channel, NemoClaw asks whether to rebuild immediately.
Running add for an already-configured channel overwrites the stored credentials where applicable.
Repeating a successful add with identical inputs is idempotent.
A failed re-add can leave residual gateway-provider state when prior refresh material cannot be restored.
Static channel credentials use a validated endpointless OpenShell provider profile so the gateway can replace their sandbox placeholders.
NemoClaw validates the complete checked-in profile contract, provider type, and credential keys before it reuses a provider.
For an existing refresh provider with matching metadata, it preserves the working credential until OpenShell mints the replacement.
A later refresh failure can still leave changed gateway refresh material; follow the rollback guidance below.
A missing provider is created when complete credentials are available.
OpenShell provider inspection uncertainty stops the operation before provider mutation.
On a fresh add, NemoClaw may already have applied the credential-free policy preset and attempts to remove it before exiting.
If that policy cleanup fails, rebuild the sandbox first, then run the nemohermes <name> policy remove <channel> command printed by the CLI.
With complete credentials, NemoClaw replaces a mismatched provider only when it is unattached or attached exclusively to the selected sandbox.
An attachment to another sandbox stops replacement.
The --force flag does not override this provider attachment authority.
Hermes Discord uses its dedicated static provider type because its policy binds the Discord API and Gateway endpoints.
Channel names are trimmed and lowercased before NemoClaw stores credentials, names bridge providers, or prints rebuild messages.
NemoClaw requires the matching built-in network policy preset YAML to be present.
A missing or malformed preset YAML (no network_policies: section) aborts channels add before any token prompt, registry write, or rebuild prompt.
After validating that preset, NemoClaw discloses its effect before prompting for credentials or changing gateway or registry state.
It prints the exact effective egress scope when the preset would open or replace access, or reports that no new egress would be opened when the preset is already effective.
The --dry-run path prints the same disclosure without collecting credentials or applying changes.
With the preset file in place, NemoClaw applies it to the sandbox before the rebuild so the bridge has egress to its upstream API.
When final policy application fails after provider registration during a fresh add, NemoClaw attempts to roll back the bridge providers, preset, and staged environment credentials before registry state is written, then exits without prompting for a rebuild.
If any gateway-side step fails, rollback continues and prints a Rollback could not fully clean <surfaces> warning so the operator can clean up manually.
When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior messagingChannels entry, staged environment credentials when available, and registry credential hashes.
An existing provider can be changed during re-add.
NemoClaw attempts to restore stored provider credentials, but it cannot restore prior gateway refresh material that was available only during the earlier setup command.
It flags gateway-providers as residual.
Inspect the channel’s gateway providers, restore the preset YAML, and correct the gateway failure.
When the gateway is reachable, run the nemohermes <name> channels remove <channel> command printed by the CLI, then rerun nemohermes <name> channels add <channel>.
After a successful rebuild, channels add verifies that the selected Telegram, Discord, or Slack bridge starts and reports credential, startup, or plugin discovery warnings.
For OpenClaw, an official-plugin provenance failure stops the image build before those runtime checks. Follow the recovery procedure in Official messaging plugin verification stops the build.
Slack requires both SLACK_BOT_TOKEN (bot user OAuth) and SLACK_APP_TOKEN (app-level Socket Mode token); the command prompts for each in turn. The conflict check compares only sandboxes in the selected OpenShell gateway’s sandbox registry. It cannot detect Slack token reuse across independent OpenShell gateways. Run only one active Slack sandbox on each OpenShell gateway, and use distinct Slack bot and app tokens across gateways. Optional Slack allowlists come from SLACK_ALLOWED_USERS and SLACK_ALLOWED_CHANNELS at rebuild time. Telegram and Discord mention mode default to 1 when no environment, session, or saved state value exists for that setting. Discord applies that default only when a server ID is configured. A run with NEMOCLAW_NON_INTERACTIVE=1, or a run without a terminal on stdin, fails fast on any missing token and shows no rebuild prompt. Instead, the change is queued and you are told to run nemohermes <name> rebuild manually. An SSH command without -t, a service unit, or a CI job has no terminal on stdin, so it does not need NEMOCLAW_NON_INTERACTIVE=1 to reach this path. If you omit the required <channel> argument, the CLI prints the channels add <channel> usage with the supported channel list instead of falling back to top-level help.
nemohermes <name> channels remove <channel>
Clear the stored credentials for a messaging channel and rebuild the sandbox so the image drops the channel. Running remove for a channel that was never configured is a no-op against the credentials file and normally still triggers the rebuild prompt. OpenClaw WeChat also checks for orphaned physical session state when no channel or policy entry exists; if cleanup cannot be confirmed, removal stops before rebuilding. When the bridge provider is attached to a live sandbox, NemoClaw detaches it before deleting the provider from the OpenShell gateway. If deletion fails, NemoClaw attempts to restore the attachment before returning the failure. If restoration also fails, the diagnostic names the provider and sandbox and warns that channel delivery may remain interrupted. If the matching built-in policy preset is applied, NemoClaw also removes that preset from the current OpenShell policy so the upstream API is no longer allow-listed after the channel is gone. When removing Teams, NemoClaw removes Teams-owned Microsoft login credential bindings from matching Outlook policy endpoints. It refuses to remove a binding owned by another integration. No session preset list exists to synchronize.
For QR-paired channels (today: WhatsApp), NemoClaw destructively clears the in-sandbox session directories before the rebuild so the complete native-home transfer does not restore the removed auth blob and let the channel reconnect:
- OpenClaw:
/sandbox/.openclaw/<channel>/(for example/sandbox/.openclaw/whatsapp/). - Hermes:
/sandbox/.hermes/platforms/<channel>/(for example/sandbox/.hermes/platforms/whatsapp/). For WhatsApp, NemoClaw also clears compatibility sessions left by older images at/sandbox/.hermes/profiles/dashboard-home/platforms/whatsapp/session/and/sandbox/.hermes/dashboard-home/platforms/whatsapp/session/.
NemoClaw runs cleanup for a running sandbox through native OpenShell execution. Cleanup succeeds only when the command exits successfully and returns its completion sentinel. If execution fails or the result is inconclusive, the command refuses to rebuild and prints recovery guidance. Fix the reported condition, then rerun the command so a rebuild cannot restore stale channel authentication files.
For OpenClaw WeChat only, NemoClaw checks the registered runtime provider for its distinct stopped-state cleanup before native execution. The provider must confirm sandbox ownership, a stopped runtime resource, and one writable state resource containing the declared paths. If the registry entry is missing, the provider does not support stopped-state cleanup, or no eligible stopped runtime resource exists, NemoClaw falls through to native cleanup. Removal proceeds only when that command exits successfully and returns its completion sentinel.
As with channels add, NEMOCLAW_NON_INTERACTIVE=1 or a run without a terminal on stdin skips the rebuild prompt and queues the change for a manual nemohermes <name> rebuild. channels start and channels stop follow the same rule. If you omit the required <channel> argument, the CLI prints the channels remove <channel> usage with the supported channel list.
Host-side removal is the supported path because managed startup (or an explicit custom image build) materializes agent channel config as image-owned state (/sandbox/.openclaw/openclaw.json for OpenClaw and /sandbox/.hermes/.env for Hermes); agent-specific channel removals inside the sandbox would modify the running config but not persist changes across rebuilds.
nemohermes <name> channels stop <channel>
Pause one configured messaging channel without clearing its credentials. The command verifies that the sandbox’s agent runtime supports the channel before reading configured or disabled channel state. It then requires the channel to be configured for the sandbox. The channel is marked disabled in the per-sandbox registry, and the rebuild omits its runtime configuration, token upsert, and startup effects. Generic channel providers and refresh bridges remain detached while the channel is stopped.
When a stopped Hermes Discord channel keeps a credential-bound policy, the rebuild retains and attaches only the validated static provider that the policy requires.
It does not start Discord or recreate the provider credentials.
The provider remains registered with the OpenShell gateway, so a later channels start brings the bridge back without re-entering tokens.
Use channels stop instead of channels remove when you want to pause a bridge temporarily. channels remove is destructive to credentials; channels stop is not.
nemohermes <name> channels start <channel>
Re-enable a channel previously paused with channels stop. The command verifies that the sandbox’s agent runtime supports the channel before reading configured or disabled channel state. It then requires the channel to be configured for the sandbox. NemoClaw removes the channel from the disabled list and records it as enabled in the messaging plan. The rebuild uses that plan to attach the existing bridge provider before applying its matching built-in network policy preset to the replacement sandbox. Before updating the disabled list, NemoClaw prints the exact effective egress scope when the preset would open or replace access, or reports that no new egress would be opened when the preset is already effective. If the command queues the change without rebuilding, the running sandbox keeps its existing bridge and network policy until you run nemohermes <name> rebuild.
nemohermes <name> channels status
Run messaging channel status checks. Without --channel, the command prints a compact summary for every configured channel, including registration, policy coverage, and non-secret rendered config comparisons. For channel and agent combinations that support a detailed probe, the summary adds a Runtime health: not checked in summary view pointer instead of running the probe, so it never reads as healthy without an explicit check. With --channel, it prints the detailed status for that channel.
For an OpenClaw WhatsApp sandbox, --channel whatsapp probes the sandbox to separately report pairing/session state, the Noise WebSocket connection, inbound event delivery, and policy coverage. A paired channel with no observed inbound delivery exits non-zero with verdict idle so an unhealthy bridge cannot pass as healthy. The detailed WhatsApp probe stays focused on QR/session runtime diagnostics and does not include rendered-config comparison lines. For a Hermes WhatsApp sandbox, --channel whatsapp first checks the shared gateway path and the profiles/dashboard-home path for creds.json. The status compatibility probe has this contract:
After validation, the command checks the configured path and reports a Session path override signal. An unsupported path produces a warning, and the report uses the default gateway path. If the dashboard path has credentials and the gateway path is empty, the report tells you to run nemohermes <sandbox> channels remove whatsapp and then nemohermes <sandbox> channels add whatsapp, because a rebuild restores the legacy session instead of dropping it. Pair again from the dashboard so credentials use /sandbox/.hermes/platforms/whatsapp/session. Rerun nemohermes <sandbox> channels status --channel whatsapp. NemoClaw does not treat a Hermes session file as live inbound-health evidence.
For Telegram, --channel telegram probes the sandbox to report the gateway process, Bot API reachability, and inbound delivery alongside the config comparison. Detailed non-wait JSON keeps the schema-version-1 {schemaVersion,sandbox,channel,report} envelope. When a probe-capable channel is paused, the command skips the live probe, returns report.verdict as info with paused registration and runtime-health signals, and exits 0. It classifies the state as healthy, idle, token_rejected, unreachable, not_started, policy_gap, config_gap, unknown, or probe_failed. A network or egress failure, or a non-authentication Bot API startup HTTP error, produces unreachable; a 401 or 404 response produces token_rejected. A missing, malformed, mismatched, identityless, or non-OpenShell runtime credential also produces token_rejected. It reads the gateway’s own startup and poll log breadcrumbs rather than issuing its own Bot API request, so the resolved bot token never leaves the gateway. The verdict reflects the most recent evidence in the log window, so a bridge that recovered after a blocked start reports healthy while one blocked again reports unreachable. Telegram health is probed only for OpenClaw sandboxes; a Hermes Telegram sandbox uses the basic config report.
For OpenClaw Slack, --channel slack reports registration, policy coverage, the account runtime, Socket Mode transport, and the account probe. Add --wait to poll these conditions until Slack becomes operational, a terminal error occurs, or the timeout expires. The default timeout is 180 seconds, and --timeout <seconds> requires --wait. NemoClaw treats the timeout as the total budget for polling and live probes, limits each live probe to the remaining budget, and starts no probe at or after the deadline. Use --json with --wait for a structured readiness result with readiness.state, readiness.category, readiness.reason, readiness.retryable, readiness.attempts, readiness.elapsedMs, readiness.lastTransitionAt, and readiness.lastObserved. Slack --wait applies only to OpenClaw sandboxes and uses its manifest-defined check; other channel manifests return readiness_not_supported until they define one. For an OpenClaw sandbox, if Slack is paused with channels stop, the command skips the live probe and returns one terminal result with readiness.reason set to channel_paused. On timeout, the command exits nonzero with readiness.state, readiness.category, and readiness.reason set to timeout; its readiness.retryable mirrors the last observed state, whose category and reason preserve the underlying cause.
For registered channel details and the compact summary, the status output compares non-secret config inputs from the sandbox registry against the values rendered into the agent config, such as Telegram group policy in openclaw.json or mention mode in Hermes config. Secret inputs, including tokens, are not printed. If the registry contains a non-secret expected value but NemoClaw cannot read or check the rendered source, the comparison is a warning and the detail includes (not checked). Optional unset inputs remain informational.
Each live probe is bounded by an in-sandbox openshell sandbox exec with a hard timeout. The WhatsApp probe returns strict OpenClaw status JSON to the host, where NemoClaw allowlists pairing, liveness, connection-state, and timestamp fields before rendering the report and discards phone-number and free-text error fields. The Hermes WhatsApp probe returns fixed session-presence booleans to the host. When the shared gateway path is empty, a sandbox-local parser can also return the configured WhatsApp session path. The parser does not return other Hermes configuration values. NemoClaw validates the path before it uses the path in a second session-presence probe. The Telegram probe returns only matched gateway log lines to the host, where NemoClaw reduces them to fixed classifications without rendering the raw lines, message bodies, or tokens. The Slack probe returns OpenClaw status JSON to the host. NemoClaw reduces it to allowlisted account booleans, credential availability, probe success, fixed error categories, and timestamps; the rendered and JSON readiness reports omit tokens and free-text errors.
nemohermes <name> mcp list
List MCP servers configured for a sandbox. The command reports the selected agent’s MCP support status and, for each configured server, whether the generated OpenShell provider, policy, and agent adapter are present.
nemohermes <name> mcp add
Add an MCP Streamable HTTP server to a sandbox. Pass --url for the MCP endpoint and the required single --env KEY bearer credential for the sandbox-side MCP client. Pass repeatable --deny-tool <name-or-glob> options to block matching tools/call requests at the OpenShell proxy. The generated deny rules match tool names only and do not inspect arguments. Pass a repeatable --trusted-private-host <exact-host-or-ip> option to admit an exact RFC1918, CGNAT, or IPv6 unique local destination for the current command. The declaration must equal the normalized host from --url. For managed MCP, use a DNS hostname for an IPv6 unique local address because NemoClaw has not qualified direct IPv6-literal MCP URLs. You can supply exact hosts through NEMOCLAW_TRUSTED_PRIVATE_HOSTS instead, and NemoClaw combines the variable with command options. NemoClaw records the resulting exact trust intent and address pins, so restart, rebuild, and restore do not depend on the ambient environment. NemoClaw registers that credential in an OpenShell provider, installs a generated OpenShell protocol: mcp policy for the target endpoint, attaches the provider to the running sandbox, and writes only an OpenShell resolver placeholder for the recorded key into the agent configuration. Inline --env KEY=VALUE is rejected because it would expose the value in NemoClaw process arguments. Load the variable from a secret manager or masked prompt, export it without recording the value in shell history, and pass only --env KEY. All endpoints must use HTTPS. The full URL and path are persisted and displayed, so URLs cannot contain userinfo, query strings, fragments, known secret-shaped path material, percent-escaped or glob-style paths, or port zero. Server names must start with a letter and contain at most 64 letters, digits, hyphens, or underscores, and endpoint hostnames must use canonical lowercase DNS labels. NemoClaw rejects invalid names and endpoints before it writes lifecycle state or changes OpenShell resources. NemoClaw generates a narrow protocol: mcp policy for the destination, literal path, adapter binaries, pinned addresses, explicit MCP methods, and a 131,072-byte request-body limit. OpenShell 0.0.116 evaluates that policy before replacing the attached provider placeholder in the allowed request header. NemoClaw imports the endpointless nemoclaw-mcp-v1 profile and binds the dedicated provider to that endpoint with credential_binding.provider. OpenShell withholds the credential before the binding is active and outside the bound host, port, and path. The sandbox client connects directly through OpenShell’s existing egress path, and NemoClaw does not run a host-side MCP data-plane bridge, proxy, relay, or listener. After the add commits, NemoClaw freshly verifies the exact generated policy, expected provider attachment, recorded provider ID, nemoclaw-mcp-v1 type, valid resource version, and exactly one credential key matching the recorded key. If those readiness checks pass, it sends a differential pair of wire-level MCP initialize requests from inside the sandbox — one with the placeholder header and one with an unresolvable control bearer — to verify that OpenShell resolves the credential on egress; otherwise it reports an inconclusive probe skipped result and sends no request. Neither outcome fails the committed add, and --no-probe skips this check. For full setup details, see Add an MCP Server.
Credential-bound managed definitions may share a normalized endpoint only when they intentionally share one credential binding. NemoClaw rejects the same endpoint with different credential bindings; use a distinct endpoint URL when different credentials are required.
The generated policy is also binary-scoped: the selected agent’s adapter binaries are allowed, while an interactive /usr/bin/curl request to the same endpoint is denied.
Use mcp status <server> to inspect policy readiness and run the supported bounded in-sandbox reachability check.
The command verifies credential resolution only when it reports a verified verdict; other probe outcomes are inconclusive.
A failed shell curl is not evidence that the managed MCP route is broken.
Hermes includes the stable credential handle from the readiness check in the resolver placeholder and preserves it through inspection, rollback, and lifecycle reconciliation while OpenShell still reports it.
For a private endpoint, use its URL host:
nemohermes <name> mcp migrate
Preview or apply the one-time conversion from the retired host-registry representation and legacy agent adapter file to the agent’s native MCP configuration. The preview is read-only and is the default. Pass --apply to authorize native materialization and legacy cleanup only after the native result verifies successfully. Native state wins: when the native and legacy definitions conflict, migration stops before any mutation and requires you to resolve the conflict explicitly.
OpenClaw converts managed Mcporter entries into openclaw.json mcp.servers. Deep Agents carries legacy .deepagents/.nemoclaw-mcp.json entries through a normal rebuild into .deepagents/.mcp.json, then removes the verified legacy projection. Hermes already uses native config.yaml and ordinarily requires no file conversion. Existing OpenShell policy, provider, attachment, and credential state are reused; migration never copies a raw credential into agent configuration. The live OpenShell policy owns denied-tool selectors, and a conflicting legacy-registry selector stops before mutation. OpenClaw migration reloads and verifies the running gateway before legacy cleanup.
nemohermes <name> mcp update
Update the denied-tool list or refresh public address pins for one registered MCP server.
Both operations use the live OpenShell policy and preserve the agent-native endpoint, credential reference, provider, attachment, and agent adapter.
Pass one or more --deny-tool <name-or-glob> options, or pass --clear-deny-tools to remove every denied-tool rule.
Use only one mode per command: --deny-tool, --clear-deny-tools, or --refresh-public-pins.
Live OpenShell policy is the enforcement source of truth; NemoClaw does not persist duplicate MCP intent. A denied-tool update validates the current source and address pins, removes the current route, and applies the replacement. If activation fails, the route remains blocked and the error prints the exact mcp update retry command. Rebuild captures and restores the complete live policy, including denied-tool rules.
Public-pin refresh requires matching current sources and existing exact public pins. It preserves all other policy fields, including denied tools, methods, binary grants, and credential bindings. It rejects private or special-use answers, address ranges, and conflicting sources before writing. If the update is not confirmed, inspect status and the live policy before retrying. Restart, rebuild, and restore do not refresh pins.
nemohermes <name> mcp status
Inspect MCP server state for one server or for all servers discovered from the agent-native configuration. Status joins that source with the live OpenShell policy, provider, attachment, and credential-key shape; no MCP registry row is consulted or created. Status also compares current DNS answers with recorded pins without changing the policy. Text output reports public address pins: or private address pins: with match, drift, or unresolved; public targets that resolve to private or special-use addresses report rejected. JSON output reports the state, recorded pins, and validated current pins when available in publicTarget or trustedPrivateTarget. Public drift directs you to mcp update <server> --refresh-public-pins, which changes only the live endpoint address pins. Trusted-private drift still requires review and remove-and-add approval. When a single server is named, status requests a differential wire-level credential-resolution probe. It sends no probe traffic unless the policy binding is present, the expected provider attachment is confirmed, and the live provider has the nemoclaw-mcp-v1 type, a valid resource version, and exactly one credential key matching the source placeholder; a readiness failure reports unknown with a probe skipped detail. When ready, the same MCP initialize is sent from inside the sandbox once with the recorded resolver placeholder header and once with a deliberately-unresolvable control bearer. Classification uses the two HTTP status codes plus curl exit codes for transport, timeout, and policy-denial outcomes; response bodies are never captured or printed. A verified verdict requires the placeholder request to be accepted (HTTP 2xx) while the control is rejected — the only outcome that proves a valid credential was on the wire. Identical HTTP 400, 401, or 403 rejections raise a warning that names the hypotheses — the placeholder forwarded verbatim, an expired or revoked credential that resolved correctly, or (for HTTP 400) endpoint request validation — and tells you to verify the stored credential first. For HTTP 401 or 403, a confirmed-valid credential means the host is not rewriting placeholders and agent runtimes receive the same auth failure and skip the server; HTTP 400 remains inconclusive because the endpoint may reject the probe request itself. Every other outcome — differing rejections (an endpoint may reject two different literal bearers differently), endpoints that skip authentication, endpoint outages, policy denials, and unreachable sandboxes — reports as unknown rather than blaming the credential rewrite, and a source URL that fails the current authenticated-endpoint boundary is never probed.
Pass --tools with one server name to request a live tool inventory. The shared client runs through the managed registration’s existing OpenShell credential provider and policy; OpenShell injects the credential at that boundary, and the runtime never accepts it as an argument, environment value, or authorization option. It performs initialize, notifications/initialized, and paginated tools/list, then attempts to close the MCP session and transport. Cleanup errors do not replace the bounded discovery result. It retains and returns deterministic tool names only, never prints the other tool-definition fields returned by tools/list, and never calls a tool. The operation is bounded by total and per-request timeouts plus response-byte, page, tool-count, cursor-length, and tool-name limits.
Use --tools only with a configured endpoint you trust to advertise names while authenticated. The endpoint controls its returned names and can derive them from the request or credential it receives; NemoClaw validates and bounds the text but cannot prove that the endpoint did not encode credential-derived data in an otherwise valid name.
The toolDiscovery JSON field contains ok, count, tools, truncated, and commandStatus.
A failed result also contains failedStage, failureClass, and a redacted detail.
An invalid JSON, JSON-RPC envelope, or tool-list schema reports failureClass: "protocol".
A runtime-emitted precondition reports commandStatus as 0.
A bridge-level precondition that skips runtime execution reports null.
An unreachable sandbox also reports null when no runtime exit status exists.
These names are the server’s point-in-time advertised tools, not an attestation of the exact tools visible to the model after agent filters, progressive disclosure, or session state.
An older sandbox image without the shared client reports that the sandbox must be rebuilt.
Tool discovery is opt-in and sends authenticated network traffic to the configured endpoint. Passing --tools suppresses the named-server credential-resolution probe that otherwise runs by default. Pass --probe --tools to request both checks explicitly. An unsuccessful discovery exits nonzero but does not remove the ordinary provider, policy, environment, or adapter status from the result.
nemohermes <name> mcp restart
Refresh one MCP server registration, or every server on the sandbox when no server is supplied. Restart reads the current agent configuration and live OpenShell state, verifies that the policy, provider, attachment, and credential binding are ready, then reloads the agent registration from that current configuration. It does not recreate a missing provider, rotate a credential, regenerate policy, or restore agent configuration from local intent. Repair the reported source directly, or remove and add the server when you intend to establish new policy or credential state.
nemohermes <name> mcp remove
Remove an MCP server from a sandbox.
NemoClaw first removes the named agent-native entry so the agent can no longer use it, then removes the deterministic policy key and detaches the exact live provider when the policy binding, provider identity, type, and credential key agree. The workspace provider and its stored credential are deliberately preserved because current OpenShell provider deletion is name-based. The command reports the retained provider name so an operator can inspect or remove it separately after confirming it is unused.
The command fails closed when it cannot safely identify the source entry. --force permits removal of a modified same-name agent entry, but it does not widen policy or provider authority and never deletes a provider. A named legacy Mcporter or .nemoclaw-mcp.json entry can be removed directly only when its committed NemoClaw registry row proves ownership. An unproven legacy entry is preserved; use mcp migrate --apply when you intend to convert it to native state.
Legacy removal also requires every other committed legacy row to have an observed legacy entry with the same server name.
If a registry-only row remains, NemoClaw preserves all sources and refuses removal.
Run nemohermes my-assistant mcp migrate --apply when you intend to convert those registrations to native configuration, or explicitly resolve the registry-only rows first.
nemohermes <name> skill install <path>
Add a local skill directory to a running sandbox. NemoClaw validates and privately stages the local regular-file tree, then invokes the selected agent’s native add command when one exists. If the pinned agent has no native local-add command, NemoClaw places only a new named tree in the agent’s manifest-declared canonical writable user-skill root. This fallback refuses to replace an existing same-name entry; remove that canonical-root copy explicitly before reinstalling it.
The skill directory must contain a SKILL.md file with YAML frontmatter that includes a name field. Skill names must contain only alphanumeric characters, dots, hyphens, and underscores. For a registered sandbox, skill commands select the agent from its registry record. They ignore another sandbox’s latest onboarding selection.
Hermes plugins are different from agent skills. Because the pinned Hermes CLI has no native local-add verb, NemoClaw places the skill only at /sandbox/.hermes/skills/<name>. Hermes owns discovery and session activation; use skill list and a new Hermes session to observe the result.
Run nemohermes <name> skill install --help to print usage for this subcommand. If you pass a plugin-shaped directory to skill install, the CLI prints a plugin-specific hint instead of treating it as a missing skill file.
Before upload, NemoClaw snapshots at most 1,024 files and 64 MiB with no-follow reads. Files with names starting with . are skipped and listed. Unsafe paths, symlinks, and special files are rejected. Staging uses a private temporary directory for the current invocation and is cleaned up on the ordinary completion path. NemoClaw does not record, recover, or reconcile staging state.
NemoClaw creates no installed-skill inventory, receipt, provenance record, mirror, or ownership ledger. A successful filesystem placement says only that the named canonical-root copy was placed; it does not claim the skill is active.
nemohermes <name> skill list
Invoke the unmodified selected agent’s native list command and stream its stdout, stderr, and exit status. Native flags can be appended except the option separator and lifecycle-bound agent-selection overrides, which NemoClaw refuses so the command remains bound to the sandbox-selected agent. This command is the authoritative view exposed by the selected agent; NemoClaw never reconstructs the result from host or sandbox state.
nemohermes <name> skill remove <skill>
Remove a named skill through the selected agent’s unmodified native remove command when one exists. Otherwise, delete only that name from the manifest-declared canonical writable user-skill root. NemoClaw does not search other roots and does not claim that the skill is globally absent afterward; skill list and a new agent session remain authoritative.
The pinned Hermes skills uninstall verb applies only to hub-installed skills and is not equivalent for a locally placed tree. NemoClaw therefore deletes only /sandbox/.hermes/skills/<name>.
Use the skill name from the SKILL.md frontmatter, not the local directory name. Skill names must contain only alphanumeric characters, dots, hyphens, and underscores, and cannot be . or ...
nemohermes <name> sessions
List Hermes conversation sessions in the sandbox. NemoClaw invokes hermes sessions list via openshell sandbox exec, forwards native Hermes flags such as --source and --limit, and streams the output unchanged.
nemohermes <name> sessions list
Invoke hermes sessions list inside the sandbox. NemoClaw forwards native Hermes flags such as --source and --limit and streams the output unchanged.
nemohermes <name> sessions delete <id>
Invoke hermes sessions delete <id> --yes inside the sandbox to remove a session from the Hermes store. Pass a native Hermes session id from sessions list (for example 20260727_130357_cb2b61). The OpenClaw-only --agent, --keep-transcript, --json, and --verbose flags are not supported on a Hermes sandbox.
nemohermes <name> sessions export
Export a Hermes sandbox’s session history from the running sandbox to the host.
The command invokes the in-sandbox hermes sessions export against a staging path under /sandbox/.nemoclaw-staging, then downloads the resulting single JSONL stream to the host.
For a registered sandbox, export, transfer, and staging cleanup use its recorded OpenShell gateway.
NemoClaw reports success only after the OpenShell transfer process, artifact verification, host publication, transfer-process cleanup, and lifecycle-lock release.
Hermes stores session history in a SQLite database, so the command refuses positional keys, --format tar, and --include-trajectory with a clear error.
--agent accepts only hermes as a no-op alias on a Hermes sandbox and rejects any other value.
The host destination defaults to ./sessions-<sandbox>.jsonl; --out picks a different path.
Session JSONL can contain pasted secrets, such as API keys or tokens, so exported files are written owner-only (0600). The in-sandbox staging artefact is additionally created with umask 077 and removed after the host download completes. If the staging cleanup fails, the command warns with the retained path and a manual removal command. The retained artifact can contain session JSONL with pasted secrets. Run the exact removal command from the warning, then inspect that same retained path to confirm it no longer exists.
The export keeps its original success or failure result, so a cleanup warning after a successful download does not make the export fail.
nemohermes <name> download <sandbox-path> [host-dest]
Host-side wrapper around openshell sandbox download that checks the live sandbox.
For a registered sandbox, it sends the transfer and source checks to the sandbox’s recorded OpenShell gateway.
It waits for the OpenShell transfer process, verification, publication, and cleanup before it returns.
The command confirms before and after transfer that the source remains a file or directory.
Symbolic links, source-type changes, and other special source types are refused.
A directory source is refused when any member is a symbolic link or another special file, and the host destination is not created for a refused source.
If the command cannot confirm the source type, it exits without publishing.
If the source does not exist, the command exits with status 2.
Other failures use a different nonzero status.
The command downloads to a fresh private temporary directory on the host, verifies that OpenShell wrote an artifact, publishes the artifact to your destination, and removes the temporary directory.
An existing destination directory is resolved to its canonical path before publication.
The command refuses an existing file destination that is a symbolic link and a new destination below a symbolic-link parent.
It checks every component of the destination parent, so it refuses the destination whether or not the directories below the symbolic link already exist.
Pass the canonical path, or an existing destination directory, to publish below a symbolic link on purpose.
Regular files are published through a private temporary entry and atomically replace an existing regular file.
Relative host destinations resolve against the caller’s working directory.
Absolute host destinations do not use caller-working-directory resolution.
With no host-dest the destination defaults to the current directory.
For a relative sandbox path that begins with -, place the standard outer -- before the path.
NemoClaw anchors the source so OpenShell treats it as a path.
nemohermes <name> upload <host-path> [sandbox-dest]
Host-side wrapper around openshell sandbox upload.
It confirms that the sandbox is live and resolves relative host source paths from the caller’s working directory.
For a registered sandbox, it sends the transfer to the sandbox’s recorded OpenShell gateway.
It waits for the OpenShell transfer process to close before it returns.
OpenShell performs the transfer.
With no sandbox-dest, the destination defaults to /sandbox/ inside the sandbox.
nemohermes <name> rebuild
Upgrade a sandbox to the current agent version while preserving its complete native home/workspace. The command captures that complete tree and the current OpenShell policy in private temporary handoffs, destroys the old sandbox, recreates it with the current image, and restores the complete tree.
If the sandbox or its retained recovery record belongs to another local OpenShell gateway registry, NemoClaw runs the rebuild or recovery retirement from that registry.
It asks for confirmation before it starts the delegated rebuild worker unless you pass --yes or --force.
The worker uses the sandbox’s recorded gateway state and credentials; you do not need to select the gateway first.
Prepared backup recovery for a legacy upgrade reuses the digest-verified pre-upgrade policy handoff instead. It stops before deletion if that handoff is missing or changed.
NemoClaw inspects the complete native-home archive before replacement. Credential-bearing or uninspectable content stops the rebuild and removes the unpublished archive; it is not stripped from an otherwise published transfer. Move credentials to supported OpenShell credential storage or bindings, then retry. The replacement receives the captured OpenShell document directly; NemoClaw does not reconstruct policy from preset records. The replacement uses the recorded compatible-endpoint reasoning mode, reasoning effort, web search selection, and serving-profile provenance instead of ambient shell values. When same-gateway legacy sandbox records use the selected supported provider but omit its credential environment-variable name, rebuild fills only those missing names from the provider’s canonical configuration. The target update and peer metadata migration use one registry update. Conflicting credential environment-variable names, custom endpoints, or API families still stop the rebuild. Incomplete routes and invalid gateway bindings also stop the rebuild. NemoClaw checks the shared route again immediately before deleting the original sandbox.
Rebuild starts with the recorded sandbox GPU enablement mode and the recorded device selector for an explicitly enabled sandbox.
When a Docker runtime snapshot contains one replayable NVIDIA GPU selector, rebuild creates the replacement with that provider-observed selector.
Device-path evidence remains restore evidence and is not used as a creation selector.
Rebuild stops before deletion when the observed selector conflicts with a recorded GPU opt-out or cannot be represented by one selector.
An auto-mode sandbox remains auto when its runtime snapshot has no replayable GPU selector.
Rebuild re-resolves the Docker-driver GPU route from the current host and current NEMOCLAW_DOCKER_GPU_PATCH value, so native-only, explicitly authorized native-with-fallback, and compatibility-only routing may differ from the original onboarding run.
A rebuild preserves the recorded tool-disclosure mode unless --tool-disclosure explicitly changes it; it ignores an ambient NEMOCLAW_TOOL_DISCLOSURE value while recreating the sandbox.
A rebuild preserves the recorded Deep Agents Code observability choice and matching local OTLP policy state unless --observability or --no-observability explicitly changes them.
A rebuild preserves the recorded Deep Agents Code auto-approval capability unless --dcode-auto-approval explicitly changes it.
A sandbox onboarded with an explicit GPU opt-out (stored as sandboxGpuMode: "0", plus legacy registry entries that only record gpuEnabled: false) is recreated with the same opt-out, so the inner onboard --resume skips the Docker CDI GPU preflight on hosts without an NVIDIA GPU.
If replacement onboarding returns nonzero, rebuild stops before post-create state restoration and retains recovery state.
Rebuild transfers the complete Hermes native home/workspace, including configuration and unknown agent-written paths. NemoClaw then reapplies host-owned gateway, managed inference-route, credential, and policy settings from recorded host state. Refer to Rebuild While Preserving State for capture, verification, and failure handling.
If another terminal has an active SSH session to the sandbox, rebuild prints an active-session warning and requires confirmation before destroying the sandbox. Pass --yes, -y, or --force to skip the prompt in scripted workflows.
For other eligible sources, the backup step normally reaches the sandbox over its live transport. When that first attempt fails because the transport is unreachable, and the sandbox has exactly one eligible stopped container, rebuild starts that container, retries the backup, and returns the container to its stopped state before continuing. rebuild aborts before deleting the original sandbox when it finds no eligible stopped container, when the retried backup also fails, or when it cannot return the started container to its stopped state; in that last case it names the container so you can stop it yourself before retrying.
If the complete native home/workspace cannot be archived, rebuild stops before deleting the original sandbox. This fail-closed behavior also applies to --force.
Follow Continue an Interrupted Replacement for the retained-backup recovery procedure.
For a sandbox with managed MCP servers, rebuild reads the agent-native MCP source before teardown.
If that source cannot be read safely, rebuild stops before deletion even with --force.
NemoClaw carries the source entries only in the bounded rebuild transaction and does not persist a second MCP registry.
NemoClaw rechecks the source, recorded gateway, resolved targets, policy, and provider identities immediately before deletion.
Legacy, conflicting, or ambiguous bridge state stops before deletion and points to mcp migrate when conversion is available.
Except for prepared legacy backup recovery, rebuild independently captures the complete current OpenShell policy and hands it to replacement creation.
NemoClaw sends the delete request and every deletion-confirmation lookup to the sandbox’s exact recorded gateway.
Across every rebuild path, NemoClaw does not attempt to stop local NIM until sandbox deletion is positively confirmed.
It then attempts NIM cleanup on a best-effort basis.
When openshell sandbox delete exits nonzero, an exact recorded-gateway lookup distinguishes explicit absence from a confirmed Ready or Running sandbox.
Any other phase or probe failure is ambiguous.
Explicit absence continues the rebuild.
Confirmed intact state triggers an attempt to restore prepared MCP state.
NemoClaw reports any MCP restoration failure and does not present the operation as a successful rollback.
Ambiguous state preserves the bounded MCP handoff and recovery metadata without attempting to stop NIM or claiming the original sandbox remains intact.
Before backup or deletion, rebuild checks the staged messaging configuration against other sandboxes in the selected OpenShell gateway’s sandbox registry.
A rebuild cannot detect messaging conflicts in an independent OpenShell gateway’s registry.
A conflict aborts with the original sandbox registered and intact so you can resolve the conflict before retrying.
After OpenShell accepts the sandbox deletion, rebuild waits until OpenShell explicitly reports that the old sandbox is absent.
Only then can NemoClaw perform any required local registry removal and begin creating the replacement.
If OpenShell does not confirm absence within the bounded wait, including when gateway transport errors block the probes, rebuild exits nonzero before registry removal or replacement creation and preserves both the local registry entry and the state backup.
Restore OpenShell connectivity and confirm the sandbox’s live state before you retry.
Keep the printed backup path for recovery.
Before deletion, rebuild records a replacement journal that binds the operation to the recorded gateway, source identity, and target settings.
Rerunning the same rebuild continues from the recorded boundary or accepts the proven replacement instead of deleting it again.
An older recovery marker can lack an MCP handoff, as can an interruption before NemoClaw records the handoff.
NemoClaw reads MCP state again only when the source still exists and the matching journal remains in the planned or deleting phase.
If either check fails, the retry stops without another delete attempt.
A mount-free journal written before host-mount identity binding remains resumable.
An older journal that used host mounts fails closed because it cannot prove the original host source identity, even when the visible mount settings are unchanged.
Preserve the sandbox, onboarding session, printed backup, exact error, and Journaled replacement diagnostic.
Then follow the legacy journal guidance in Continue an Interrupted Replacement.
Use --verbose to print the replacement identifier, gateway, and journal phase.
Refer to Continue an Interrupted Replacement for the recovery procedure and fail-closed conditions.
After restore, the command starts the rebuilt Hermes gateway with the complete source native home, including its /sandbox/.hermes config and unknown agent-written paths.
A rebuild creates a new sandbox home and a new Hermes API bearer token.
After the rebuild succeeds, retrieve the replacement token with nemohermes my-assistant gateway-token --quiet before reconnecting API clients.
nemohermes update
Check for a NemoClaw CLI update and, when requested, run the maintained installer flow. This command is a discoverable CLI wrapper around the supported installer path. The update request and every redirect require HTTPS:
nemohermes update updates the host-side NemoClaw installation. The maintained installer flow follows the admin-promoted lkg release tag by default, so it may trail the newest semver or latest tag while validation completes. Because of that, an install can be newer than the maintained tag. Without --allow-downgrade, --fresh runs only when the maintained build is the same version or newer than the installed version. When the maintained tag resolves, the command passes that repository revision to the installer, so a later tag change cannot select a different build for that update. It reports the reason and exits non-zero in these cases:
- The installed version is newer than the maintained tag.
- The versions cannot be ordered.
- The maintained tag does not resolve to a version.
NemoClaw cannot order a git describe version against a different prerelease on the same release line. Rerun with --allow-downgrade to reinstall regardless; --yes waives the confirmation prompt only and never accepts a downgrade on its own. It does not replace nemohermes upgrade-sandboxes; use that command to inspect or rebuild existing sandboxes after the CLI has been updated. When the command is running from a source checkout, it reports that state and does not replace the checkout with a global package install.
nemohermes upgrade-sandboxes
Rebuild sandboxes whose base image is older than the one currently pinned by NemoClaw. NemoClaw resolves the digest of ghcr.io/nvidia/nemoclaw/sandbox-base:latest from the registry, then compares it against the digest each sandbox was created with. Sandboxes that match the current digest are left alone. NemoClaw also checks the build fingerprint recorded on each managed sandbox image. A sandbox needs upgrade when its agent version is stale, when its recorded NemoClaw image fingerprint differs from the running CLI, or both. When the target version is older than the recorded one (for example after reinstalling with an older NEMOCLAW_INSTALL_TAG), the stale listing marks the change with a (downgrade) suffix instead of framing it as a routine upgrade. Custom Dockerfile sandboxes are not classified by image drift because rebuilding them onto the default image would drop the custom image. Legacy sandboxes without a recorded fingerprint opt into this check after their next rebuild. A recorded sandbox that is not observed in any phase on its own recorded gateway is reported as not found there, with remediation guidance — this typically means its gateway registration or Docker image was removed (for example by nemohermes uninstall, which preserves sandboxes.json but removes both).
External-image sandboxes are excluded from agent version and image drift classification.
The command lists them as pinned, publisher-managed images and does not rebuild them, including with --auto.
After you update NemoClaw, run nemohermes <name> rebuild to revalidate the external image and recreate the sandbox from its recorded digest.
Before it inspects a gateway or starts a rebuild, the command validates every registered sandbox name against the NemoClaw sandbox name format. Route-only reservations are not sandboxes and are excluded from this validation. If the command finds incompatible names, it lists each name before any gateway inspection or rebuild. With --check, the command then returns without changing state. In a mutating mode, it exits with a nonzero status. NemoClaw does not truncate or rename a registered sandbox identity. Follow Update Sandboxes to transfer state to a compatible replacement before you rerun the command.
Each rebuild reuses the same whole-home transfer as nemohermes <name> rebuild, so the complete OpenShell-provided native home/workspace survives the upgrade. If the registry or required managed-image catalog evidence is unavailable, NemoClaw fails closed instead of selecting an unpinned image. Restore registry access, then rerun the command so NemoClaw can validate the exact image digest. During installer recovery, stale or non-Ready registered sandboxes can be rebuilt from their validated latest backups. That recovery requires a NemoClaw-managed image fingerprint or the installer’s explicit confirmation for a listed pre-fingerprint OpenClaw or Hermes entry. The legacy confirmation never overrides recorded custom-image evidence. OpenClaw’s native plugin and package state transfers with unknown files, configuration, histories, hooks, cron data, and child-agent state; NemoClaw does not require separate ownership metadata.
When installer recovery rebuilds an intentionally stopped sandbox, NemoClaw returns the replacement to Stopped.
The command exits nonzero if OpenShell cannot confirm that phase or a required post-stop reconciliation fails.
Rerun nemohermes upgrade-sandboxes --auto to reconcile the stopped state without rebuilding a current replacement again.
The retry is complete when the command exits zero and reports that the sandbox was reconciled to stopped state; nemohermes upgrade-sandboxes --check should then omit that sandbox from the reconciliation plan.
nemohermes backup-all
Back up each registered sandbox’s complete OpenShell native home/workspace to ~/.nemoclaw/rebuild-backups/. A registered docker-driver sandbox whose container is stopped is started for the duration of the backup and returned to its stopped state afterward. If the container cannot be returned to the stopped state, the command fails and reports that the container was left running. Sandboxes that are not running and cannot be started this way are skipped with remediation guidance.
For a stopped sandbox, backup-all first asks OpenShell to start it in a separate bounded operation.
After OpenShell accepts the start, one lifecycle transaction waits for SSH readiness, captures state, and returns the sandbox to Stopped.
It reserves time for the return transition.
A readiness, backup, or return failure marks that sandbox as failed, and backup-all continues with the next sandbox.
Before an OpenShell upgrade, the installer prepares the current release CLI and uses it to run backup-all in strict mode. Strict mode requires every registered sandbox that still has a runtime to produce a fresh backup and aborts before gateway changes if an ordinary sandbox is skipped or fails. When strict mode reports an ordinary skipped sandbox, start that sandbox or its container and rerun the installer or nemohermes backup-all. A registry record that the selected gateway and container provider both prove has no remaining runtime is reported as confirmed stranded, produces no backup, and does not fail strict mode. Follow the reported cleanup or recreation action in Resume a Manually Prepared Upgrade before recovery.
A running sandbox whose in-sandbox SSH endpoint does not answer fails its backup and aborts the run. For a standalone nemohermes backup-all run, set NEMOCLAW_SKIP_UNREACHABLE_SANDBOX_BACKUP=1 exactly to skip such sandboxes instead of failing. Other values such as true, yes, or 0 are not accepted. This variable does not weaken the installer’s strict pre-upgrade requirement. A skipped sandbox’s uncommitted state is not included in its last successful backup.
nemohermes <name> share mount
Mount the sandbox filesystem on the host machine via SSHFS for bidirectional file sharing. Files edited on the host appear instantly inside the sandbox, and vice versa.
Expected output:
Prerequisites:
sshfsmust be installed on the host (sudo apt-get install sshfson Linux,brew install macfuse && brew install sshfson macOS).- The sandbox must be running.
- The remote sandbox path must exist. NemoClaw verifies it against the target sandbox before invoking
sshfsand prints aconnect, thenls <path>check when the probe fails. - Sandboxes created before the
openssh-sftp-serverbase image update must be rebuilt withnemohermes <name> rebuild. - The local mount path must be on a writable filesystem; FUSE creates the mount on the host side. If the default
~/.nemoclaw/mounts/<name>lives on a read-only filesystem, pass an explicit writable path as the second positional argument.
nemohermes <name> share unmount
Unmount a previously mounted sandbox filesystem.
nemohermes <name> share status
Check whether the sandbox filesystem is currently mounted.
Expected output:
openshell term
Open the OpenShell TUI to monitor sandbox activity and approve network egress requests. Run this on the host where the sandbox is running.
For a remote server, connect through SSH and run openshell term on that server.
nemohermes tunnel start
Start optional host auxiliary services.
This is the cloudflared tunnel when cloudflared is installed, which exposes the dashboard with a public URL.
Channel messaging is not started here; it is configured during nemohermes onboard and runs through OpenShell-managed constructs.
By default, NemoClaw starts a Cloudflare quick tunnel and prints the generated *.trycloudflare.com URL when cloudflared reports it. Set CLOUDFLARE_TUNNEL_TOKEN to start a Cloudflare named tunnel instead. The named tunnel hostname and localhost:<dashboard-port> route must already be configured in the Cloudflare dashboard. NemoClaw passes the token to cloudflared through the TUNNEL_TOKEN environment variable, so the token does not appear in the cloudflared command-line arguments.
For a named tunnel, NemoClaw verifies that the reported ingress route targets the selected dashboard port before treating startup as successful. If it cannot confirm that route, it stops the newly started tunnel and returns an error. If shutdown cannot be confirmed, it retains the process and dashboard-port records so cleanup can be retried safely.
On Windows, a quick tunnel started by an older NemoClaw release may not have a recorded dashboard port. tunnel start can safely replace it when NemoClaw verifies the running cloudflared.exe process and determines that its quick-tunnel target does not match the selected dashboard port. If NemoClaw cannot confirm the process identity, determine its target, or stop it, the command fails closed; verify the command line identifies cloudflared.exe, stop it manually, and run tunnel start again.
nemohermes start remains as a deprecated compatibility command. It exits successfully after printing guidance for nemohermes <name> start and nemohermes tunnel start; it does not start either resource itself.
nemohermes tunnel stop
Stop host auxiliary services that nemohermes tunnel start started (for example cloudflared).
If NemoClaw cannot confirm that cloudflared stopped, the command returns an error and retains the process, PID file, and dashboard-port record. Do not stop the recorded PID while its identity is uncertain. Before stopping it manually, use the host process manager to verify that the recorded process is cloudflared (cloudflared.exe on Windows), then stop it and retry nemohermes tunnel stop.
When stop confirmation fails, NemoClaw also skips dependent gateway, channel, model, and managed gateway-port cleanup. After safely stopping the verified cloudflared process, rerun the command to retry that cleanup.
If NemoClaw finds an unmanaged cloudflared process or cannot inspect tunnel ownership, it preserves that process and continues sandbox channel, Ollama, and requested gateway cleanup before returning an error.
Use nemohermes <name> channels stop <channel> when you only want to pause one messaging bridge.
The command asks NemoClaw to stop an in-sandbox gateway only when NemoClaw directly owns that process. Supervisor-owned agent runtime processes remain managed inside their sandbox. The command leaves agent-owned host forwards and the managed OpenShell gateway port available.
If command-line inspection is unavailable for a live cloudflared PID, Windows can still verify cloudflared.exe and stop it through an identity-bound process handle. Other platforms require process inspection before signaling. If NemoClaw cannot perform identity-bound signaling, it leaves the process and PID record untouched and reports incomplete cleanup. Independently verify and stop the recorded cloudflared process with the host process manager, keep the PID record until that process exits, then retry nemohermes tunnel stop.
nemohermes stop remains as a deprecated legacy full stop. In addition to stopping tunnel services, it attempts to stop the selected agent’s host forwards when the sandbox uses a manifest-resolved non-OpenClaw agent. It also attempts to safely release an unshared OpenShell gateway port whose ownership NemoClaw can verify. Shared gateways remain running, and ambiguous ownership fails closed without releasing the port. Use nemohermes tunnel stop when the shared gateway should remain available.
nemohermes tunnel status
Show the current cloudflared public-URL tunnel status and the selected or default sandbox dashboard. Selection honors an explicitly set NEMOCLAW_GATEWAY_PORT; otherwise the command uses the selected or default sandbox’s owning gateway and falls back to the process-default gateway when no sandbox resolves. If the sandbox name belongs to more than one gateway registry, selection fails closed. Sandbox selection honors NEMOCLAW_SANDBOX_NAME, then NEMOCLAW_SANDBOX, then SANDBOX_NAME, then the registry default. Before reporting status, when no live gateway-scoped PID record exists, the command can move exactly one live legacy PID record that matches a sandbox in the selected gateway registry into gateway-scoped state. The output reports whether cloudflared is running, stopped, stale, or has a live PID whose process identity cannot be verified safely. When identity is unavailable, nemohermes tunnel start refuses to create a second tunnel. Windows may verify and stop cloudflared.exe through an identity-bound process handle even when command-line inspection is unavailable; other platforms require process inspection before signaling. If safe identity verification or signaling is unavailable, restore inspection access or independently verify and stop the process before retrying. Other stopped and stale states include the same recovery hint used by nemohermes status.
When no live managed tunnel record exists, non-Windows hosts scan the current user’s process list and report an unrecorded cloudflared executable as a conflict. Windows skips this scan. If process listing fails on another platform, tunnel start fails closed instead of starting another tunnel; status cannot report unmanaged conflicts until process inspection is restored.
nemohermes start
Deprecated. Use nemohermes <name> start for a stopped sandbox or nemohermes tunnel start for
the optional public-URL tunnel.
This compatibility command prints migration guidance and exits successfully without changing sandbox or tunnel state.
nemohermes stop
Deprecated legacy full stop. Use nemohermes tunnel stop when the shared gateway should remain
available.
This command stops tunnel services and, for a manifest-resolved non-OpenClaw agent, attempts to stop the selected agent’s host forwards. It attempts to release the managed OpenShell gateway port only when the gateway is unshared and ownership is safely resolved; otherwise it preserves the gateway. When no sandbox name resolves, gateway release requires a valid, explicitly set NEMOCLAW_GATEWAY_PORT; a bare command leaves the process-wide default gateway running and reports Host services stopped; managed gateway not released. If NemoClaw attempts the release but cannot confirm it, the command reports that outcome and does not claim that all services stopped. For manifest-resolved non-OpenClaw agents, it also requests cleanup of host-forwarding resources that nemohermes tunnel stop leaves running. The command is retained for compatibility with full-stop automation. Supervisor-owned agent runtime processes remain managed inside their sandbox.
nemohermes status
Show the sandbox inventory for the gateway port that NEMOCLAW_GATEWAY_PORT selects and the gateway-scoped host-side status of auxiliary services such as cloudflared.
It reads the selected port’s registry, live inference route, and gateway health; it does not scan registries for other gateway ports.
For gateway-based messaging agents, it also reports messaging overlap warnings within the selected OpenShell gateway’s sandbox registry.
Use nemohermes <name> status when you need one sandbox’s live health and recovery guidance.
Pass --json for machine-readable output with registered sandboxes, service state, inference routes, and health details.
Each sandbox row’s configuredInference object contains that sandbox’s recorded provider and model.
For schema-version-1 compatibility, the row-level provider and model fields keep their existing effective-route behavior; use configuredInference when you need the recorded route.
When the latest resumable onboarding session owns the matching inference-route reservation, it appears under Incomplete onboarding in text and as incompleteOnboarding in JSON.
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.
It is not counted as a registered sandbox and does not trigger sandbox or gateway health probes.
Each JSON sandbox row reports agent as a string, never null.
The row reports openclaw when the registry records no agent for the sandbox.
This command reads the registry without gateway recovery, so it never reports unknown.
For each listed sandbox, the text output includes the configured inference provider and model plus the number of active SSH sessions when the session probe is available.
That route line is labeled Inference (configured):.
An unavailable recorded provider or model appears as unknown.
When onboarding records a browser-facing dashboard URL from CHAT_UI_URL, text output adds a Dashboard URL: line for that sandbox.
The port suffix beside the sandbox name remains the recorded local forwarding port.
For the default sandbox, an Inference (live): line also appears when the shared gateway route differs from the recorded route.
Use nemohermes <name> status for the sandbox’s full live health and recovery details.
Cloudflared PID and log lookup use the gateway-scoped state selected by an explicit NEMOCLAW_GATEWAY_PORT, or otherwise by the selected or default sandbox’s owning gateway. If no sandbox resolves, lookup falls back to the process-default gateway; ambiguous cross-gateway sandbox ownership fails closed.
Before reporting auxiliary services in text or JSON, root status can perform the same bounded legacy tunnel-state migration as nemohermes tunnel status.
When at least one sandbox is registered and the named NemoClaw gateway is unreachable, unhealthy, or attached to a different sandbox, the command prints a gateway: down [state] (reason) line between the sandbox list and the host-service list. The command classifies the failing layer when possible: the named gateway port is not accepting connections, the named gateway is running but not Connected, the active OpenShell gateway points at a different name, or the named gateway is not configured at all. It then prints the gateway recovery guidance for your host. That guidance names nemohermes onboard when NemoClaw starts the gateway process. When another deployment owns that process, the guidance directs you to start it with the owning deployment and run openshell gateway select <gateway>. It exits with code 1 so shell scripts and CI can detect the degraded state from $?. For --json, the structured output includes gatewayHealth, and the exit code is set after the report is generated. A clean machine with no registered sandboxes keeps the legacy 0 exit because no gateway is expected to be configured yet. If cloudflared is installed but not running, the host-service section reports whether the PID file is missing, invalid, or points at a dead process, then suggests nemohermes tunnel start as the recovery command.
nemohermes inference get
Show the provider and model for the selected inference path.
When the selected sandbox has a valid native NVIDIA or hosted provider attachment, the command reports its recorded provider, model, and native endpoint without reading the shared gateway route.
For providers that still use the shared route, the command reports the active live route from the NemoClaw-managed OpenShell gateway that NEMOCLAW_GATEWAY_PORT selects.
For a compatible custom provider, also show the persisted endpoint URL when the selected gateway’s matching registry metadata is safe, unambiguous, and reusable.
Use this command when you want the selected inference path without the rest of the sandbox status output.
It is also available in sandbox-first form as nemohermes <name> inference get.
A valid native NVIDIA or hosted attachment adds its native endpoint to the recorded provider-and-model output. Other managed providers keep the provider-and-model output. Compatible providers add the endpoint only when published same-gateway metadata matches the live route and is safe to display; otherwise the command keeps the live provider and model and returns credential-free recovery information. Refer to View the Selected Inference Path for the exact text and JSON fields, omission states, safety rules, and recovery procedures.
For the sandbox-first grammar, NEMOCLAW_GATEWAY_PORT first selects the sandbox registry and fallback gateway.
When <name> has a valid native NVIDIA or hosted provider attachment, the command reports its recorded provider, model, and native endpoint without reading the shared gateway route.
Otherwise, when that registry contains <name>, the command resolves the sandbox’s recorded gateway and reads that gateway’s live route.
It does not search registries for other gateway ports.
When the live provider and model match the sandbox’s recorded route, text and JSON output identify a llama-cpp-local route as managed or attached.
JSON reports this value as llamaCpp.kind.
An attached route also reports the fixed loopback URL as llamaCpp.endpointUrl; NemoClaw does not report a stored arbitrary endpoint.
When the ownership receipt is unreadable, llamaCpp.kind is unavailable and the output includes diagnostic and recovery text.
The command omits llamaCpp when the recorded and live routes differ.
For a shared-route lookup, the global form omits llamaCpp details.
Shared-route lookup failures include timeouts, nonzero exits, no exit status, and output NemoClaw cannot interpret after a command exits successfully.
The error names the gateway without rendering command output.
It directs a direct lookup to nemohermes status and a sandbox-first lookup to nemohermes <name> status.
nemohermes inference set
Switch the active inference provider or model for a NemoClaw-managed Hermes sandbox.
For NVIDIA Endpoints, OpenAI, Anthropic, Gemini, OpenRouter, and Hermes Provider, the command attaches or updates the selected sandbox’s native provider.
Custom endpoints and local providers retain their existing shared OpenShell route.
It then patches the shared native /sandbox/.hermes/config.yaml, recomputes the config hash, and updates the NemoClaw registry.
Changes between shared routes do not rebuild or restart Hermes.
If the current or selected route uses a native hosted provider, NemoClaw restarts the Hermes gateway after configuration sync.
Active agent requests can be interrupted during the restart.
If the restart fails, the route and configuration remain committed.
Run nemohermes <name> gateway restart to apply the switch.
Shared routes use the OpenShell proxy API-key placeholder. On a live NVIDIA Endpoints switch, NemoClaw writes the newly attached provider’s scoped OpenShell credential reference into the Hermes config. Other native hosted providers use their managed credential placeholders. None of these values is a raw provider credential. The gateway, CLI, TUI, and Web Dashboard read the same configuration.
The command is also available in sandbox-first form as nemohermes <name> inference set --provider <provider> --model <model>. Under the nemohermes alias, it uses the registered Hermes sandbox when exactly one exists; otherwise pass --sandbox <name> to target one explicitly.
By default, the command syncs the default registered sandbox.
NVIDIA Endpoints and the five fixed hosted providers use sandbox-attached providers without changing the shared route. The following route-conflict rules apply to providers that still use the shared gateway route, including custom endpoints and local providers.
Before changing the route, NemoClaw compares it with every same-gateway registry entry, including stopped sandboxes.
When only the provider or model differs, the command names the affected sandboxes and warns immediately before it re-points the shared route.
Those sandboxes use the new live route until connect, onboarding, or another inference set command re-points it.
For the same provider name, custom compatible routes must have matching normalized endpoint URLs and API families. Provider-global credential environment-variable names must also match. Endpoint, API-family, credential, incomplete-route, and invalid-gateway-binding conflicts remain fail-closed. The command exits nonzero before changing the OpenShell route, agent config, or host registry and names the conflicting sandboxes. Align the provider-global configuration, repair incomplete metadata, or remove a conflicting sandbox that you no longer need.
Onboarding, connect, and inference set can time-share compatible provider and model routes without replacing provider-global configuration. Refer to Use Shared Gateway Routes for route-change warnings, compatibility fields, and the status drift report.
You can also name the sandbox in sandbox-first position instead of passing --sandbox. nemohermes <name> inference set --provider <provider> --model <model> targets <name> directly and is equivalent to nemohermes inference set --provider <provider> --model <model> --sandbox <name>.
Pass both --provider and --model to select the provider and model for the target sandbox. For NVIDIA Endpoints and the five fixed hosted providers, NemoClaw attaches or updates the selected sandbox’s native provider and syncs its agent config without changing the shared route. Custom endpoints and local providers retain their existing shared-route workflow. NemoClaw resolves the OpenShell gateway from the target sandbox’s recorded gateway binding, including non-default NEMOCLAW_GATEWAY_PORT deployments. Do not run openshell inference set directly on a shared NemoClaw gateway because that bypasses registry compatibility checks and can break other sandboxes. When either flag is missing, nemohermes inference set reports both required flags without suggesting a raw OpenShell command. The command updates the host registry after the selected inference path changes.
If the in-sandbox config write or integrity hash update fails, the selected inference path and NemoClaw registry remain committed, but the command exits with status 1 and points you to nemohermes <name> rebuild.
Canonical supported provider IDs are nvidia-prod, nvidia-nim, nvidia-router, openai-api, openrouter-api, anthropic-prod, compatible-anthropic-endpoint, gemini-api, compatible-endpoint, hermes-provider, llama-cpp-local, ollama-local, and vllm-local.
The installer alias llama-cpp is accepted and normalized to llama-cpp-local.
Recognized underscore spellings of canonical provider IDs and hyphenated installer aliases are also accepted.
For example, ollama_local normalizes to ollama-local, nvidia_prod normalizes to nvidia-prod, and open_router normalizes to openrouter-api.
NemoClaw preserves an unrecognized underscore spelling for normal provider validation.
Use --no-verify only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential.
When you explicitly supply a direct compatible endpoint at http://host.openshell.internal:<port>, NemoClaw skips OpenShell’s host-side provider probe because that hostname resolves only inside the sandbox network.
Before it persists the route in the NemoClaw registry or agent config, the command sends a validation request from the target sandbox.
The output limit is 16 tokens for ordinary providers and 256 tokens for Google Gemini.
When the switch changes the API family and that request returns HTTP 400 or 404, NemoClaw retries up to two times after delays of 2 and 4 seconds.
NemoClaw uses the same retry schedule when validation fails before it receives an HTTP status, such as while the gateway route is reloading.
Each retry uses the same output limit for the selected provider.
Other HTTP failures are not retried.
If OpenShell rejects provider verification before it persists the route or confirms that it did not apply the route, NemoClaw leaves the inference selection unchanged.
Sandbox-side verification occurs after route application.
If that verification fails, NemoClaw tries to restore the previous selection and reports whether restoration succeeded.
If OpenShell cannot confirm whether it changed the route, NemoClaw stops and reports an unknown result.
Run nemohermes <name> inference get to inspect the selected sandbox’s gateway before you use the route or retry.
NemoClaw removes the provider only when it can verify the revision created by this switch.
If removal was not attempted or could not be confirmed, rerun onboarding before using that provider route or retrying the switch.
Provider updates for DNS-backed HTTPS routes occur after route selection.
If sandbox verification fails after an existing provider update succeeds, NemoClaw restores the previous inference selection but leaves the updated provider binding in place.
Rerun onboarding before using that provider route or retrying the switch.
If NemoClaw rejects an update before the provider command runs, the provider binding stays unchanged.
If a provider command fails without confirming that no change occurred, provider state may be partial.
If the error says that provider state may be partial, rerun onboarding to reconcile the provider before using the route or rerunning inference set.
If NemoClaw cannot restore the previous selection, resolve the reported restore failure.
Then rerun onboarding before you use the route.
Refer to Switch Inference Providers for the complete recovery procedure.
Endpoint-shape and shared-gateway compatibility checks still apply.
When switching to compatible-endpoint or compatible-anthropic-endpoint from a different provider family, pass --endpoint-url with the trusted custom provider URL and, except for the Hermes case below, --inference-api with its API family so NemoClaw can persist a complete route identity for rebuild and shared-gateway checks.
For a Hermes compatible-anthropic-endpoint target, --inference-api may be omitted because NemoClaw deterministically selects openai-completions; an explicit different API family is rejected.
NemoClaw rejects loopback, link-local, private, and internal endpoint addresses, including public hostnames that resolve to a private address.
For a same-provider model change, omit the endpoint options so NemoClaw reuses the endpoint recorded for the target sandbox.
When you supply endpoint options, missing or inference set provenance and every different URL remain subject to the full address validation above.
For public HTTP URLs, NemoClaw stores the validated IP address to prevent DNS rebinding.
For a DNS-backed HTTPS URL, NemoClaw routes the endpoint through a local HTTPS Pin Runtime adapter that terminates a pinned, SNI-correct outbound connection to the real upstream hostname; the sandbox and the persisted registry only ever see a local host.openshell.internal route, never the real hostname.
HTTPS IP-literal URLs remain supported and do not need the adapter.
NemoClaw accepts http://host.openshell.internal:<port> only with an explicit port from 1024 through 65535; this narrow exception supports NemoClaw’s sandbox-to-host inference routes and is not a general private-endpoint bypass.
--credential-env may also be supplied for compatible provider metadata; supported --inference-api values are openai-completions, anthropic-messages, and openai-responses.
nemohermes setup
nemohermes setup command is deprecated. Use nemohermes onboard instead.This command remains as a compatibility alias to nemohermes onboard and accepts the same flags: --profile <name>, --non-interactive, --resume, --fresh, --recreate-sandbox, --apf-interceptor, --gpu / --no-gpu, --from, --from-image, --name, --host-mount, --sandbox-gpu / --no-sandbox-gpu, --sandbox-gpu-device, --vllm-gpu-device, --agent, --agents <agents.yaml>, --tool-disclosure <progressive|direct>, --dcode-auto-approval <disabled|thread-opt-in>, --observability / --no-observability, --control-ui-port, --yes / -y, --no-ollama-autostart, --yes-i-accept-third-party-software.
nemohermes setup-spark
The nemohermes setup-spark command is deprecated. Use the standard installer and run nemohermes onboard instead, because current OpenShell releases handle the older DGX Spark cgroup behavior.
This command remains as a compatibility alias to nemohermes onboard and accepts the same flags: --profile <name>, --non-interactive, --resume, --fresh, --recreate-sandbox, --apf-interceptor, --gpu / --no-gpu, --from, --from-image, --name, --host-mount, --sandbox-gpu / --no-sandbox-gpu, --sandbox-gpu-device, --vllm-gpu-device, --agent, --agents <agents.yaml>, --tool-disclosure <progressive|direct>, --dcode-auto-approval <disabled|thread-opt-in>, --observability / --no-observability, --control-ui-port, --yes / -y, --no-ollama-autostart, --yes-i-accept-third-party-software.
nemohermes doctor
Run read-only checks for the host and the NemoClaw gateway without selecting a sandbox.
The command works before you create a sandbox.
It checks the NemoClaw CLI build, the selected host runtime provider, the OpenShell CLI, the sandbox registry, and the gateway selected by NEMOCLAW_GATEWAY_PORT.
It does not start, select, restart, or repair a gateway.
It does not run sandbox, inference, messaging, agent-version, config-permission, or agent-service checks.
Use nemohermes <name> doctor when you need those sandbox checks.
If a sandbox is named doctor, the bare command still selects this global report. Use nemohermes doctor connect to connect to that sandbox explicitly.
The command exits nonzero when a required check fails.
Pass --json for a redacted, schema-versioned report with scope: "global" and no sandbox field.
--json and --text are mutually exclusive.
With both flags, doctor exits before it runs checks, writes one JSON error to standard output, and writes the conflict diagnostic to standard error.
nemohermes debug
Collect diagnostics for bug reports.
The command gathers system information, Docker state, gateway logs, and sandbox status into a summary or tarball.
Use --sandbox <name> to select a sandbox, --quick for a smaller snapshot, or --output <path> to save a tarball.
If --output is set and the tarball cannot be written (for example, the destination directory is missing or read-only), the command exits non-zero so scripts can detect the failure. The tarball is written to a temporary sibling and renamed on success, so a pre-existing file at --output is preserved when tar fails.
An explicit name can come from --sandbox, NEMOCLAW_SANDBOX_NAME, NEMOCLAW_SANDBOX, or SANDBOX_NAME, in that precedence order.
The name must match a registered sandbox.
NemoClaw checks the sandbox on its registered owning gateway.
An unknown sandbox, invalid gateway binding, denied OpenShell observation, or confirmed absence from that gateway exits nonzero without writing a tarball.
The error names the sandbox and the source environment variable when applicable.
Without an explicit name, NemoClaw selects the registered default sandbox, or the first registered sandbox when no default exists.
It exits nonzero when that selected sandbox fails the same availability checks.
nemohermes credentials list
List the provider credentials registered with the OpenShell gateway. Values are not printed.
nemohermes credentials add <PROVIDER>
Register a provider credential with the OpenShell gateway by name and type. Each --credential takes the env variable name whose value the gateway should read; export the value first so it is not placed in argv. Pass either repeatable --credential <ENV_NAME> or --from-existing, but do not combine them. With --from-existing, NemoClaw inspects the provider profile and rejects registration when one of its credential keys is reserved by a managed MCP server. After the gateway accepts the provider, rebuild each sandbox that should use it.
After a successful provider creation or attachment, NemoClaw compares a previously verified profile with its current gateway definition. If it warns that verification did not complete or the profile changed, the successful operation remains successful. Ask the gateway operator to inspect the profile before relying on its credential boundary.
Registered providers are gateway-wide and attach to every sandbox you build or rebuild after the call. nemohermes credentials reset <PROVIDER> removes the provider from the gateway and detaches it from every sandbox currently using it; it cannot limit the provider to selected sandboxes. To replace a credential, reset the provider, register the replacement, and rebuild each detached sandbox.
Tavily requires a provider profile that permits the intended agent runtime.
Use --type tavily --agent hermes to select the versioned tavily-hermes-v1 profile for Hermes Python.
The explicit --type tavily-hermes-v1 form remains supported without --agent.
OpenClaw and Deep Agents use the existing tavily profile with --agent openclaw or --agent dcode.
Without --agent, --type tavily retains that profile and prints a warning that it does not authorise Hermes Python.
--agent accepts hermes, openclaw, langchain-deepagents-code, and their aliases only for Tavily profiles.
An explicit Hermes profile combined with a non-Hermes agent is rejected before gateway operations.
This option selects a credential profile only: it does not select a sandbox or gateway, restrict gateway-wide attachment, enable web search, or apply egress policy.
Register the credential for the intended runtime:
For an existing incorrect binding, follow Repair a Hermes Tavily Provider.
nemohermes credentials reset <PROVIDER>
Remove a provider credential from the OpenShell gateway by provider name. After removal, re-running nemohermes onboard re-prompts for that provider’s credential. Run nemohermes credentials list first if you are not sure of the provider name.
When a sandbox records an attachment to a native NVIDIA or supported fixed hosted provider, reset stops without detaching or deleting it.
Rotate its credential in place by supplying the selected provider’s credential through the host environment and rerunning nemohermes onboard --name <sandbox>. Use NVIDIA_INFERENCE_API_KEY for NVIDIA Endpoints and the provider-specific variable documented under onboard for another selection.
To remove it completely, preserve required sandbox state, destroy every attached sandbox, and then retry reset.
nemohermes gc
Remove orphaned sandbox Docker images from the host. Sandbox creation can build images in the gateway-managed openshell/sandbox-from repository or the locally prebuilt nemoclaw-sandbox-local repository. The destroy and rebuild commands clean up the image automatically, but images from older NemoClaw versions or interrupted operations may remain. Docker images are shared across gateways on the host. This command lists images from both repositories, checks every validated host gateway registry, and removes only images that no registered sandbox uses. It checks the registries again after confirmation, so images registered while the prompt was open remain protected.
If the command cannot safely read a gateway registry, it stops before deletion. Correct the reported gateway-state problem, then rerun nemohermes gc --dry-run before removing images.
nemohermes uninstall
Run uninstall.sh to uninstall NemoClaw. The CLI runs the local uninstall.sh shipped with the installed npm package. If that local script is missing, the CLI does not auto-fetch a remote copy. It prints the versioned URL of the matching uninstall.sh so you can download, review, and run it manually.
When the gateway is externally supervised, full uninstall refuses bulk sandbox cleanup and exits nonzero before deleting selected sandboxes, provider registrations, or the local gateway registration. It preserves that downstream state. Restore a NemoClaw-managed lifecycle authority and retry. It also preserves the externally supervised process, Docker resources, and OpenShell binaries. For a managed dual-Station vLLM runtime, full uninstall revalidates the exact recorded pair and removes both managed containers before starting the remaining uninstall steps. If that cleanup fails, uninstall exits nonzero, preserves its owner-only cleanup receipt, and tells you to resolve the reported peer error before retrying. Pair cleanup can partially complete before an error; verify both Stations before the retry. For an authenticated host-local vLLM runtime, full uninstall verifies the exact named container, NemoClaw ownership label, persisted API key, and authentication fingerprint before removing the container by its inspected ID. When that ownership state is missing, full uninstall removes the reserved nemoclaw-vllm container only when Docker reports its NemoClaw managed label and a valid container ID. An unlabeled container or malformed inspection remains in place and stops the remaining uninstall steps. For managed llama.cpp, full uninstall verifies the exact named container and network ownership before removing both resources by their inspected IDs. These host-local checks run before NemoClaw deletes their state. If Docker is unavailable or a resource does not match its persisted ownership state, uninstall exits nonzero before the remaining uninstall steps and preserves that state for recovery. Host-local cleanup can partially complete before an error. Restore Docker access or resolve the named ownership conflict, inspect the remaining container and network, and retry uninstall. Managed llama.cpp and vLLM model files remain in the shared Hugging Face cache by default. --delete-models deletes every model in the local Ollama inventory and all non-credential data in the current user’s shared ~/.cache/huggingface/ cache. This opt-in can delete cached files that other applications installed or use. It preserves the Hugging Face token and stored_tokens authentication files. NemoClaw stops and verifies its managed local and distributed model runtimes before it deletes non-credential data from the local Hugging Face cache. It does not scan arbitrary directories or delete model caches on remote peers. When sibling gateway environments remain, uninstall preserves both model stores even if you pass --delete-models. An Ollama inventory error, model deletion error, unsafe cache path, or cache-data deletion error makes uninstall exit nonzero. Cleanup can partially complete before an error, so resolve the reported error and rerun uninstall.
uninstall also stops any orphaned openshell host processes left behind by previous onboard or destroy cycles, including openshell sandbox create, openshell ssh-proxy, and SSH sessions spawned by OpenShell. Earlier releases only stopped openshell forward processes, so those orphans accumulated across runs.
uninstall also stops matching Ollama auth proxy processes before deleting ~/.nemoclaw state so stale proxy listeners do not block a later reinstall. When sibling gateways remain, uninstall leaves the shared proxy running for them.
For Hermes setups, uninstall inspects the selected gateway’s managed port-forward watcher state, stops each verified watcher process and its sandbox-scoped forward, and leaves sibling gateway state untouched. If any watcher or forward cleanup cannot be confirmed, uninstall exits nonzero and preserves the selected gateway’s watcher state so you can retry cleanup.
Linux uninstall removes ~/.local/state/nemoclaw unless you pass --keep-openshell, the gateway is externally supervised, or another gateway-port environment remains on the host.
That directory contains NemoClaw-owned Docker-driver gateway configuration and SQLite data, audit logs, VM-driver state, and standalone-fallback gateway PID files.
Uninstall preserves it when the managed or externally supervised gateway process remains because that process depends on the state.
When another gateway-port environment remains, uninstall removes only the selected gateway port’s subdirectory of that directory and keeps the other ports’ subdirectories.
Run nemohermes uninstall --all-gateway-ports to remove every gateway port on the host.
Keep an externally supervised lifecycle authority’s declared stateDir outside that NemoClaw-owned path.
Uninstall preserves that externally supervised directory.
This differs from a managed NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR override, which successful managed cleanup removes unless --keep-openshell.
For a Docker Hermes sandbox that uses the NemoClaw-managed image, uninstall removes its managed
state volume even without --destroy-user-data. Back up required Hermes state first. NemoClaw
removes only a volume with exact ownership labels; inspection or removal failure exits nonzero
and preserves registry state for retry.
NEMOCLAW_GATEWAY_PORT selects the gateway instance and state root to uninstall.
Port 8080 selects nemohermes and the shared ~/.nemoclaw/ root; a non-default port selects nemoclaw-<port> and ~/.nemoclaw/gateways/<port>/.
For example, NEMOCLAW_GATEWAY_PORT=9123 nemohermes uninstall selects nemoclaw-9123.
If onboarding also set NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR, pass its original resolved absolute directory to uninstall so configuration, namespace, process, and state cleanup target that exact directory.
Use the dedicated gateway state directory created for that port, not a shared or parent directory.
Onboarding rejects relative overrides, the shared NemoClaw state root or its parents, and existing nonempty directories without valid NemoClaw-managed gateway configuration.
Let onboarding create the directory when possible. Every existing ancestor, from its containing directory to the filesystem root, must be a real directory owned by the current user or root and must not be group- or world-writable. If the state directory already exists, it must be an owner-controlled, non-symbolic-link directory with mode 0700.
If onboarding stops immediately after reserving that directory, uninstall removes the marker-only reservation only while the selected gateway port is free. Gateway configuration, a runtime marker, or a PID file moves cleanup to the managed-gateway checks instead. A port-bound marked gateway with valid generated configuration can be retired after the port is free and a bounded process scan proves that no live process claims its state. A listener, unreadable process identity, or a scan that reaches its probe limit preserves the directory. Inspect and stop the listener or matching gateway process, then rerun uninstall after the port is free.
If a prior uninstall removed a non-default gateway but retained its registry and backups, rerun NEMOCLAW_GATEWAY_PORT=<port> nemohermes uninstall --destroy-user-data to remove that retained data.
This recovery requires the default state directory for that port, with NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR unset, and retained rows that explicitly identify Docker.
The selected gateway registration, runtime directory, processes, listener and sandbox containers must be absent.
A same-name container is preserved as a sibling only when its Docker identity matches another published registry row and that sibling gateway currently confirms the same sandbox identity.
Missing or failed inventory, unknown ownership, or conflicting identity preserves the data and makes uninstall exit nonzero.
The diagnostic identifies unreadable Docker inventory, a remaining selected container, or unproven same-name container ownership and gives its retry action. Keep NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR unset for this retained-data recovery.
Restore access to Docker and the affected sibling gateway, resolve the reported conflict, then retry the same command.
When NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR is unset, a non-default port can also remove NemoClaw state after onboarding fails during preflight, before it creates a gateway or sandbox.
This interrupted-preflight cleanup does not apply to a custom state root.
For a custom state root, uninstall exits nonzero and preserves the interrupted state.
Resolve the preflight failure, then resume onboarding with the original port and custom state root.
After onboarding creates the managed gateway, run uninstall with those same settings.
The failed checkpoint must identify the selected gateway and port, the selected registry and gateway state must be absent, the port must be free, and complete process and gateway-registration checks must prove absence.
Uninstall acquires the onboarding lock, recovers a stale lock when its recorded process is no longer active, revalidates the evidence throughout cleanup, and atomically detaches the validated state root before deleting it.
An active lock, changed checkpoint, new selected-gateway state, occupied port, incomplete process evidence, or ambiguous registration preserves the state root and makes uninstall exit nonzero so you can resolve the reported condition and retry.
If a sibling gateway appears during cleanup, uninstall switches to gateway-scoped cleanup and preserves shared resources.
Onboarding holds an exclusive lifecycle lock from reservation through gateway initialization.
If uninstall reports that onboarding owns the state directory while onboarding is active, wait for onboarding to finish and rerun uninstall; the reservation is preserved.
If the reported onboard.lock remains after onboarding ends abruptly, wait briefly and rerun uninstall to retry lock acquisition.
A recorded PID or command describes the lock record. It does not prove that process owns an active lock.
Do not stop a process or delete the lock from that record.
NemoClaw preserves a recent malformed lock for 30 seconds because another process can still be writing it.
Wait at least 30 seconds, then retry.
Successful managed cleanup recursively removes that directory and all contents; --keep-openshell preserves it.
Before cleanup, uninstall validates port-bound state-root ownership and exact live process identity. A marked, stopped gateway can instead use a free port plus a bounded process-absence scan that proves no live process claims its state; pre-marker gateways can use their owner-private generated configuration as the legacy ownership proof only with live process identity.
The compatibility --gateway flag cannot select another instance: when present, it must match the name derived from NEMOCLAW_GATEWAY_PORT, or uninstall exits before cleanup.
Default-port uninstall removes NemoClaw-managed entries in openshell/gateway.env.
For a NemoClaw-managed authority, it also removes only NemoClaw’s marked Linux gateway unit.
It preserves upstream Linux package units, the macOS Homebrew service, and unrelated environment entries.
Gateway-scoped cleanup removes that gateway’s OpenShell resources first, then the marked Linux unit.
The OpenShell gateway service therefore keeps running while uninstall deletes the selected gateway’s sandboxes.
If OpenShell resource cleanup fails, uninstall exits nonzero and preserves the marked Linux unit and gateway process.
If marked Linux unit cleanup fails, uninstall exits nonzero before it scans for or stops a remaining gateway process or continues with later Docker and gateway-state cleanup.
OpenShell resource and Linux unit cleanup can partially complete before either failure.
After selected sandbox cleanup succeeds, uninstall removes those entries from sandboxes.json before gateway registration and Linux unit cleanup.
If a later step fails, the retry skips the completed sandbox deletions and resumes the remaining cleanup.
Resolve the reported error.
Inspect the remaining gateways with openshell gateway list.
Rerun NEMOCLAW_GATEWAY_PORT=<port> nemohermes uninstall with the gateway port from the failed uninstall.
For an externally supervised authority, uninstall preserves the selected local gateway state in both full and gateway-scoped cleanup.
It also preserves the gateway process, supervisor resources, marked Linux unit, Docker resources, OpenShell binaries, and the declared external state directory.
A custom-port uninstall does not stop or remove the default gateway service or its environment file.
Uninstall does not stop an openshell-gateway process that another non-root user owns and that this installation did not record.
It names the owner and process ID, leaves that process running, and continues with the remaining cleanup.
If no other cleanup fails, uninstall exits with status 0 even though that process can keep its port in use.
Uninstall still tries to stop a root-owned process and the gateway process that this installation recorded.
If either stop fails, uninstall reports the process without printing a reusable privileged kill command.
Do not signal a PID from saved output.
Immediately before a privileged stop, verify that the live process owner and openshell-gateway command line match the gateway name and port.
Also prove that the PID file, runtime marker, and loaded sandbox namespace still match the selected state directory.
Rerun uninstall after the process stops.
A gateway-scoped uninstall and every --all-gateway-ports pass exit nonzero after that failure.
A single full uninstall reports the process and continues.
Before each sandbox deletion during scoped Docker cleanup, NemoClaw proves the selected configuration and running gateway identity again and passes the selected gateway name to OpenShell.
The configuration and running process must use the state-root-specific OpenShell sandbox namespace that NemoClaw generated.
For a standalone NemoClaw-managed gateway, the live proof also binds the process owner, PID file, runtime marker, and command line to the gateway name and port.
For a package-managed gateway, NemoClaw instead binds the trusted active service’s current main process, executable, owner, and loaded sandbox namespace to the default gateway.
For an externally supervised gateway, NemoClaw proves the configured state.
It binds the supervisor’s current main process to its owner, loaded sandbox namespace, declared executable, selected gateway name, and selected port.
When NemoClaw can prove an owner-private, generated configuration and complete JWT bundle that predate state-root scoping, restart keeps the legacy gateway ID, JWT bundle, and Docker driver’s default namespace.
That compatibility keeps the gateway able to find existing containers and keeps their non-expiring sandbox JWT issuer valid.
NemoClaw regenerates the other gateway settings from the current runtime configuration.
For a proven legacy Podman gateway, NemoClaw preserves the gateway ID that existing sandbox JWTs use; the supported Podman schema has no sandbox_namespace setting to preserve.
If the existing identity is ambiguous or unsafe, or durable gateway state remains without its configuration, restart fails closed without rewriting the configuration or JWT bundle.
Fresh state roots and already scoped configurations continue to use the state-root-specific identity.
The legacy default namespace is not isolated across gateways, so it cannot satisfy the scoped-uninstall proof while sibling gateways remain.
Scoped uninstall stops before it deletes a sandbox, registry row, or gateway registration and preserves the selected gateway’s runtime evidence and local state.
Because the supported OpenShell Podman schema does not expose sandbox_namespace, scoped Podman uninstall fails closed before signaling and preserves the gateway runtime evidence and local state.
For Docker, if any proof is absent, uninstall exits nonzero before it signals the host gateway.
NemoClaw preserves the gateway runtime evidence and local state.
Keep that state intact.
For an already scoped gateway with stale runtime evidence, restore it through the supported install or onboarding recovery flow, verify the generated identity, and retry.
A proven legacy gateway is not silently converted by onboarding.
To retire one, first remove sibling gateways through their own proven scoped cleanup, verify that only the legacy gateway remains, and then use the full single-gateway uninstall path.
For an ambiguous or incomplete identity, stop the gateway and restore the generated openshell-gateway.toml and complete jwt/ directory from a dedicated host-level backup path, represented here as <gateway-identity-backup>.
The backup must have been captured from that gateway’s state directory before the failure and kept under the owning user’s exclusive access.
Keep the <gateway-identity-backup> directory and its nested jwt/ directory at mode 0700, and keep the configuration and JWT files at mode 0600.
The default gateway stores them under ~/.local/state/nemoclaw/openshell-docker-gateway/; a non-default gateway uses ~/.local/state/nemoclaw/openshell-docker-gateway-<port>/.
Restore them as the owning user.
Keep the gateway state root and its jwt/ directory at mode 0700, and do not grant group or other access to the configuration or JWT files.
NemoClaw does not reconstruct gateway identity from native-home backups or backup-all; if no matching gateway-state backup exists, keep the state intact rather than attempting a scoped cleanup.
Verify every gateway with openshell gateway list.
Retain <gateway-identity-backup> only until that command reports the restored gateway and the affected existing sandboxes authenticate successfully.
Then remove that dedicated backup directory as the owning user and verify its absence by replacing the placeholder in test ! -e '<gateway-identity-backup>' with the full backup path.
If verification fails, keep the backup under the same access restrictions and stop.
Do not add sandbox_namespace manually to a live gateway configuration because the running process can still be using its previous namespace.
Uninstalling Every Gateway Port
A single uninstall is scoped to one gateway port, so the other ports on the host keep running and keep their ports bound.
When uninstall detects other gateway-port environments, it names each one, gives the NEMOCLAW_GATEWAY_PORT=<port> command that removes one of them, and points at the whole-host sweep.
A gateway environment whose port cannot be read is reported as an unidentified environment rather than omitted.
--all-gateway-ports, or NEMOCLAW_UNINSTALL_ALL_GATEWAY_PORTS=1, uninstalls all of them in one run.
The sweep enumerates the default state root and the non-default roots under ~/.nemoclaw/gateways/.
When the sweep finds more than one port, it confirms once against the resulting port list, then uninstalls each other port before the port NEMOCLAW_GATEWAY_PORT selects.
When it finds only the selected port, it uses the standard uninstall confirmation without a port list and runs that port once.
Each port runs as its own uninstall so that every port-scoped value, including the state root, registry file, gateway name, and Docker resource names, resolves from that port rather than from the calling environment.
An ambient NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR applies only to the currently selected port, which runs last.
The sweep restores each port’s custom state directory from its sandbox registry or verified incomplete-create checkpoint.
Invalid or conflicting recorded directories stop the sweep before any port cleanup.
Ports without recorded directories use their per-port defaults, except when the selected port has an explicit override.
For an older custom gateway whose directory was not recorded, rerun NEMOCLAW_GATEWAY_PORT=<failed-port> NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR="<original-absolute-path>" nemohermes uninstall.
The selected port runs last so its pass can remove the shared host resources once no other environment remains.
--delete-models, --destroy-user-data, and --keep-openshell apply to every port; --gateway remains a check against the selected port only.
A failure to enumerate the gateway state roots safely stops the sweep before any port uninstall begins.
The sweep cannot select an unidentified environment until its gateway port can be determined.
A port that fails to uninstall is reported, the sweep continues, and the exit code is nonzero.
That port still counts as a live sibling, so the final pass falls back to gateway-scoped cleanup and preserves the shared host resources.
Cleanup that completed before a port failure is not rolled back.
Resolve the reported error, inspect the remaining gateways with openshell gateway list, and rerun the sweep or the named per-port command.
User-data preservation under ~/.nemoclaw/
To avoid uninstall destroying host-side user data, uninstall preserves the following entries in the selected gateway’s state root by default. The default gateway uses ~/.nemoclaw/; a non-default gateway uses ~/.nemoclaw/gateways/<port>/.
When uninstall confirms that no sibling gateways remain, it also removes shared host resources such as the gateway source clone, runtime state, and the Ollama auth proxy PID file. When sibling gateways remain, it removes only the selected gateway’s resources and port-scoped state while preserving those shared host resources. With --destroy-user-data, that scoped path removes installer-managed user-local CLI shims under ~/.local/bin/ only when sibling evidence is unidentified (for example odd ~/.nemoclaw/gateways/ entries or an unreadable gateway list). When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package and the other shared host resources. If the OpenShell command is unavailable or its gateway list cannot be read, uninstall cannot confirm that the selected gateway is the last one, so it uses the same scoped path and preserves the shared resources. When the command itself is unavailable, uninstall exits nonzero before OpenShell cleanup so you can restore the command and retry.
When used alone, --yes only acknowledges the global Proceed? confirmation prompt and preserves the listed host-side entries. Removing the preserved entries requires the explicit opt-in flag (--destroy-user-data) or the matching env var (NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1). Existing automation that uses --yes without either data-removal option retains those entries.
Decision matrix:
The preserved entries survive uninstall as inert files on disk. They are not a public snapshot-restore interface.
The preserved sandboxes.json file does not make resources deleted by a completed managed uninstall recoverable on its own. A NemoClaw-managed uninstall deletes the selected sandboxes and attempts to remove the local gateway registration. After it confirms that no sibling gateways remain, it also deletes provider registrations and removes the Docker image. Uninstall warns about this at preserve time. After reinstalling, the installer reports records for deleted resources as not found on their recorded gateway instead of claiming they were recovered. Run nemohermes <name> destroy to clear a stranded record, then nemohermes onboard to rebuild it. Pass --destroy-user-data at uninstall time if you prefer to purge the registry along with its dependencies.
For an externally supervised gateway, full uninstall instead preserves the selected sandboxes, provider registrations, local gateway registration, and registry state. Restore NemoClaw-managed lifecycle authority and rerun uninstall. Do not use the stranded-record recovery above unless a managed cleanup path deleted the resource.
nemohermes uninstall vs. the hosted uninstall.sh
Both forms execute the same uninstall.sh with the same flags, but differ in where the script comes from and how much they trust the network. Use nemohermes uninstall by default. Use the hosted curl … | bash form only when the CLI is broken or already partially removed.
Internal Commands
NemoClaw registers a hidden internal command namespace. These commands are compatibility entrypoints for repo-owned scripts, such as the installer, the uninstaller, DNS setup, and developer tooling. They are not part of the supported public CLI surface.
Each command class sets hidden = true, so the commands stay out of nemohermes --help. They remain registered and routable, which is why they are listed here for reference. Treat their names, flags, and output as implementation details. They exist to back install.sh, uninstall.sh, and related automation, and they may change or be removed without notice. Most run indirectly through those scripts rather than being typed by hand.
For contributor guidance on how these command files are structured, refer to src/commands/internal/README.md.
These commands do not appear in the command-level parity check, which compares nemohermes --help against the public command headings in this reference; hidden commands are excluded from both. The table above is the canonical reference for the script-backed family. The experimental adapter is documented separately because it has no owning script.
nemohermes internal voice-gateway serve is registered for the OpenClaw-only experimental adapter described below. Hermes and Deep Agents Code do not have an equivalent adapter.
The experimental voice gateway has no Hermes or Deep Agents Code equivalent.
Environment Variables
NemoClaw reads the following environment variables to configure service ports, onboarding behavior, and lifecycle defaults. Set them before running nemohermes onboard or any command that starts services. For NEMOCLAW_GATEWAY_PORT, NEMOCLAW_DASHBOARD_PORT, NEMOCLAW_HERMES_API_PORT, NEMOCLAW_HERMES_DASHBOARD_PORT, NEMOCLAW_HERMES_DASHBOARD_INTERNAL_PORT, NEMOCLAW_VLLM_PORT, NEMOCLAW_OLLAMA_PORT, NEMOCLAW_OLLAMA_PROXY_PORT, and the three runtime-adapter port overrides, the value after whitespace trimming must use canonical decimal notation with no leading zero. Service ports must be from 1024 through 65535; NEMOCLAW_HERMES_API_PORT must be from 8642 through 8652.
CLI Logging
The centralized CLI logger writes its output to stderr and uses info verbosity by default. These controls affect leveled logger output; they do not suppress command results or command-specific output that has not migrated to the centralized logger.
The environment precedence is NEMOCLAW_LOG_LEVEL, then NEMOCLAW_DEBUG, followed by the default info level. The error level prints errors only, warn also prints warnings, info also prints informational messages, and debug prints all levels with timestamps. Use these NemoClaw-specific variables instead of the generic DEBUG variable. DEBUG is not a NemoClaw logger control and can enable dependency diagnostics that include raw command arguments.
Commands whose parser owns the base logging options also accept the hidden long-form --debug and --quiet flags, even though these options do not appear in command help. The flags are mutually exclusive. --debug overrides the environment-derived threshold and selects debug, while --quiet caps verbosity at warn without increasing an environment-derived error threshold. There is no global -q logging shorthand. Passthrough commands do not consume flags intended for the downstream command as host logging options, so use the environment variables when you need unambiguous host logging around a passthrough invocation.
Set NEMOCLAW_NO_AUTO_AUDIT_LOGS=1 to prevent nemohermes <name> logs and failed nemohermes <name> exec policy checks from enabling OpenShell OCSF JSON audit logging. Setting NEMOCLAW_NO_POLICY_HINT=1 skips the failed-exec policy-denial probe and its audit-setting attempt entirely. NemoClaw prints a notice before attempting to enable the setting when automatic audit logging remains active. Policy denial hints may be unavailable if audit logging remains disabled.
| NEMOCLAW_DASHBOARD_PORT | 18789 (auto-derived from CHAT_UI_URL port if set) | Dashboard or
API forward |
| NEMOCLAW_VLLM_PORT | 8000 | vLLM / NIM inference | | NEMOCLAW_OLLAMA_PORT | 11434 | Ollama
inference | | NEMOCLAW_OLLAMA_PROXY_PORT | 11435 | Ollama auth proxy | |
NEMOCLAW_BEDROCK_RUNTIME_ADAPTER_PORT | 11436 | Host-side Bedrock Runtime adapter | |
NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT | 11437 | Host-side adapter for retained legacy OpenRouter shared routes | |
NEMOCLAW_HTTPS_PIN_RUNTIME_ADAPTER_PORT | 11438 | Host-side HTTPS Pin Runtime adapter |
| NEMOCLAW_DASHBOARD_BIND | unset (loopback outside WSL) | Dashboard or API forward bind
address. WSL uses an all-interface forward for Windows-host reachability. Set to 0.0.0.0 to opt
in to remote bind on other SSH-deployed hosts. |
New OpenRouter selections use the sandbox-attached native provider and do not use
NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT. The port remains reserved for legacy shared routes.
If a port value is not a valid integer or falls outside the allowed range, the CLI exits with an
error. NEMOCLAW_GATEWAY_PORT also cannot overlap configured service, vLLM, Ollama, Ollama proxy,
Bedrock Runtime adapter, legacy OpenRouter runtime adapter, or HTTPS Pin Runtime adapter ports, and cannot
use reserved auto-allocation ranges or the default inference/proxy ports 8000, 8081, 11434,
11435, 11436, 11437, and 11438. Port 8081 is reserved for authenticated existing-server
attachment and the managed llama.cpp runtime. It cannot be assigned to another configurable NemoClaw
service port. Each runtime adapter port must be distinct from the gateway, vLLM, Ollama, Ollama
proxy, dashboard allocation range, and other runtime adapter ports. When you run multiple NemoClaw
gateways with different NEMOCLAW_GATEWAY_PORT values, NemoClaw derives a separate gateway name,
state directory, and compatibility container name from the port so one gateway does not tear down
another. Only port 8080 uses a NemoClaw-managed Linux systemd user service or macOS Homebrew
service. NemoClaw-managed gateways on custom ports run as detached processes and do not change the
default gateway service. An externally supervised gateway can use any matching configured port and
must be recovered through its declared supervisor. On non-WSL hosts, NEMOCLAW_OLLAMA_PORT and
NEMOCLAW_OLLAMA_PROXY_PORT must be different. If you run Ollama on port 11435, set
NEMOCLAW_OLLAMA_PROXY_PORT to another free port before onboarding.
NEMOCLAW_GATEWAY_BIND_ADDRESS accepts only 127.0.0.1 and 0.0.0.0, but NemoClaw rejects 0.0.0.0 for Docker-driver gateways while gateway JWT auth is active.
Keep the OpenShell gateway on loopback and use NEMOCLAW_DASHBOARD_BIND when you need remote browser/API access.
NEMOCLAW_DASHBOARD_BIND controls the dashboard or API port forward bind address. Outside WSL, the forward stays on 127.0.0.1 (loopback only) by default. On WSL, NemoClaw binds the host-side forward on all interfaces so the Windows host can reach it, while the ready summary continues to print a loopback dashboard URL. On non-WSL SSH-deployed hosts, set NEMOCLAW_DASHBOARD_BIND=0.0.0.0 before nemohermes onboard to prepare the sandbox for remote exposure and bind the forward on all interfaces. Use the same setting for later nemohermes <sandbox> connect calls. A sandbox created without this opt-in must be recreated with NEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemohermes onboard --recreate-sandbox before a remote-bind connect is allowed. Only 0.0.0.0 enables the remote bind; onboarding rejects any other non-empty value.
These overrides apply to onboarding, status checks, health probes, and the uninstaller. Defaults are unchanged when no variable is set, except that a recorded automatic gateway-port marker selects its alternate port.
If NEMOCLAW_DASHBOARD_PORT or the port from CHAT_UI_URL is already occupied by another sandbox, onboarding scans 18789 through 18799 and uses the next free dashboard port.
Pass --control-ui-port <N> to require a specific port.
For Hermes, NEMOCLAW_DASHBOARD_PORT controls the built-in dashboard forward, which defaults to 18789. The OpenAI-compatible API is separate and serves /v1 on a per-sandbox port that defaults to 8642. If 8642 is already held by another sandbox or by a non-OpenShell host listener, onboarding scans 8642 through 8652 and uses the next free API port. Set NEMOCLAW_HERMES_API_PORT=<N> before you onboard a new sandbox to pin a port from 8642 through 8652. If another sandbox or host listener holds the pinned port, onboarding exits instead of selecting a different port. The sandbox relay binds the port when the sandbox starts, so set this variable for an existing sandbox only together with --recreate-sandbox. For an existing sandbox, a different value without --recreate-sandbox exits before the host forward changes. Set NEMOCLAW_HERMES_DASHBOARD=1 to enable the optional Hermes dashboard. The dashboard port overrides apply only when this variable is enabled. Set NEMOCLAW_HERMES_DASHBOARD_TUI=1 only when you want the optional in-browser TUI tab.
Onboarding Configuration
The following variables let you tune onboarding without editing the Dockerfile or passing repeated flags. Set them before running nemohermes onboard.
| NEMOCLAW_OPENSHELL_BIN | path | Overrides the openshell binary the CLI invokes. Defaults to
openshell (resolved via PATH). | | NEMOCLAW_SANDBOX_NAME | sandbox name | Preferred
environment override for the default sandbox. Used by onboarding defaults and host-level commands
such as list, status, tunnel, services, and debug. | | NEMOCLAW_SANDBOX | sandbox name |
Alternate spelling of NEMOCLAW_SANDBOX_NAME; used when neither a flag nor NEMOCLAW_SANDBOX_NAME
is set. | | SANDBOX_NAME | sandbox name | Compatibility spelling used after
NEMOCLAW_SANDBOX_NAME and NEMOCLAW_SANDBOX. | | NEMOCLAW_INSTALL_REF | git ref | For internal
installer commands: the git ref to install from. A nonempty value takes precedence over
NEMOCLAW_INSTALL_TAG. Overridden by the --install-ref flag. | | NEMOCLAW_INSTALL_TAG | release
tag | For internal installer commands: the release tag to install when NEMOCLAW_INSTALL_REF is
unset or empty. Defaults to the admin-promoted lkg tag when unset. Overridden by the
--install-tag flag. | | NEMOCLAW_ENABLE_LOCAL_MODEL_PROFILE | 1 to enable | Enables the fixed
vLLM local model profile. Requires NEMOCLAW_LOCAL_MODEL_RUNTIME=vllm. Direct nemohermes onboard
use also requires NEMOCLAW_NON_INTERACTIVE=1. The hosted installer makes onboarding
non-interactive, disables Express selection, and sets this value automatically when it receives
--local-model-runtime=vllm. | | NEMOCLAW_LOCAL_MODEL_RUNTIME | vllm | Selects the fixed vLLM
local model profile. Requires NEMOCLAW_ENABLE_LOCAL_MODEL_PROFILE=1; direct onboarding also
requires NEMOCLAW_NON_INTERACTIVE=1. The hosted installer sets this value from
--local-model-runtime=vllm. | | NEMOCLAW_VLLM_MODEL | registry slug, Hugging Face model ID, or
registered served model name | Selects the model the managed-vLLM install path serves and remains
authoritative during DGX Station installer setup. Slugs, full model IDs, and registered served model
names are case-insensitive. Recognized slugs: qwen3.6-27b, qwen3.6-35b-a3b-nvfp4,
muse-glimmer-30b, nemotron-3.5-lightning-30b, nemotron-3.5-super-vl-120b, nemotron-3-nano-4b, deepseek-v4-flash,
nemotron-3-ultra-550b-a55b, deepseek-r1-distill-70b. The muse-glimmer-30b and
nemotron-3.5-lightning-30b profiles are Experimental on DGX Spark and Linux x86_64 with a
qualifying NVIDIA GPU. NemoClaw does not enable vision or DFlash speculative decoding for Muse
Glimmer. New single-Station Express installs select nemotron-3.5-super-vl-120b; a qualified reciprocal pair uses distributed Ultra.
An existing legacy single-Station Ultra workload keeps Ultra when automatic pair discovery finds no qualified pair. Outside
Station Express, unset uses the per-platform profile default. Gated models (for example,
deepseek-r1-distill-70b) require HF_TOKEN or HUGGING_FACE_HUB_TOKEN. | |
NEMOCLAW_DGX_STATION_PEER | SSH host or user@host | Selects one exact, already-trusted DGX
Station peer for Nemotron 3 Ultra pair qualification. The peer must match the reciprocal private
/30 rail and hardware checks; an explicit peer failure stops setup instead of falling back.
NemoClaw does not enroll SSH trust or accept a port or SSH option in this value. When unset, DGX
Station installer discovery checks only the two deterministic /30 counterpart addresses. A peer
cannot be combined with an explicit non-Ultra model; conflicting explicit selections fail before
pair preparation. | | NEMOCLAW_DGX_STATION_SSH_BINDING | opaque installer-managed token | Carries
the qualified peer endpoint and host-key binding from DGX Station pair preparation into the current
managed-vLLM install. The installer creates and clears this token; operators should not set or
persist it. Missing, changed, or mismatched binding state fails before peer SSH or Docker work. | |
NEMOCLAW_VLLM_EXTRA_ARGS_JSON | JSON array of non-blank strings | Appends advanced operator-owned
tokens to the managed vllm serve command after NemoClaw’s registry defaults. Example:
["--max-num-seqs","2"]. Malformed JSON, non-string tokens, blank tokens, or an invalid
--gpu-memory-utilization override fail before Docker work starts. The last memory-utilization
override also controls the early and immediate pre-launch GPU-memory checks. |
| NEMOCLAW_MODEL_ROUTER_PYTHON | absolute path | Pins the host Python interpreter used to create
the Model Router virtual environment. Strict. NemoClaw probes only that interpreter and aborts with
the failure reason if it does not qualify, rather than silently falling back to another python.
Relative command names such as python3.12 are rejected. When unset, NemoClaw probes python3.13,
python3.12, python3.11, python3.10, and bare python3, retains every interpreter whose
version is in [3.10, 3.14) and whose ensurepip, pyexpat, ssl, and venv stdlib modules
import cleanly, and tries python -m venv on each in priority order until one succeeds. Set the pin
when the auto-discovered interpreter is broken (for example, Homebrew python@3.14 with a pyexpat
dlopen mismatch on macOS). |
Hermes-specific onboarding configuration:
Extra placeholder keys
Set NEMOCLAW_EXTRA_PLACEHOLDER_KEYS before running nemohermes onboard when one container hosts multiple Hermes profiles and each profile needs its own messaging-bridge credential.
For each entry, NemoClaw registers an OpenShell provider with the endpointless nemoclaw-mcp-v1 profile. OpenShell resolves the named credential placeholder to the operator-supplied value at egress. The Hermes profile .env files are operator-owned: write ${TELEGRAM_BOT_TOKEN_AGENT_A} (or the matching placeholder for each entry) into the per-profile .env so the in-sandbox Hermes process inherits the OpenShell placeholder instead of a raw token. NemoClaw never reads, writes, or rewrites these .env files; verify after onboarding that each profile’s .env references the placeholder and that no raw bot token value sits on disk.
Entries are split on whitespace and commas and must match ^[A-Z][A-Z0-9_]{0,127}$. Each entry must extend a canonical channel envKey with a non-empty _<suffix> (for example TELEGRAM_BOT_TOKEN_AGENT_A); the canonical envKeys are TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN, SLACK_APP_TOKEN, WECHAT_BOT_TOKEN, BRAVE_API_KEY, and TAVILY_API_KEY. Bare canonical envKeys, the control env itself, and arbitrary host secret names (GITHUB_TOKEN, AWS_SECRET_ACCESS_KEY, KUBECONFIG, and similar) are refused so they cannot leak into the sandbox provider gateway. Duplicates are dropped silently. The list is capped at 32 entries per sandbox. Offending tokens emit one warning each and are skipped.
When NemoClaw creates the canonical provider, it omits an extension whose credential is unavailable from both the credential store and its environment variable. The primary credential is required to create that provider. An extension already stored in an existing provider remains available until that provider is replaced or removed. If the extension credential is absent from the credential store, export it before onboarding.
Linux Ollama install mode details
Set NEMOCLAW_OLLAMA_INSTALL_MODE=system to run the official https://ollama.com/install.sh installer, which uses sudo, writes to /usr/local, and configures systemd. Set NEMOCLAW_OLLAMA_INSTALL_MODE=user to extract the release tarball to ${HOME}/.local without sudo and launch the daemon manually without systemd persistence. Leave NEMOCLAW_OLLAMA_INSTALL_MODE empty or unset to let NemoClaw auto-detect the mode. Auto-detection selects system when the current user is root or passwordless sudo works. Auto-detection selects user in non-interactive runs without passwordless sudo. An interactive shell falls back to system so the official installer can prompt for the password. NemoClaw rejects any other value. On upgrades, NemoClaw rejects user because a user-local install cannot replace the system daemon on :11434. On upgrades, NemoClaw also rejects system under NEMOCLAW_NON_INTERACTIVE=1 when passwordless sudo is unavailable because the installer would hang on a hidden sudo prompt. The run exits with an actionable diagnostic instead.
Experimental NemoCUA
Keep NEMOCLAW_CUA_ENABLED=1 set whenever NemoClaw uses the experimental nemocua agent, including discovery, launch, agent commands, sandbox creation, and rebuild.
NemoCUA does not currently support host-local inference. Do not set NEMOCLAW_PROVIDER=ollama
when onboarding a nemocua sandbox; that combination exits with Unsupported host-local inference application 'nemocua'. Choose a non-host-local inference provider instead.
When NemoCUA retains a legacy shared route for the recorded openrouter-api provider, https://inference.local/v1/models returns HTTP 404 by design because NemoClaw’s OpenRouter adapter serves Chat Completions without a model catalog.
NemoClaw reports the route ready only after a bounded inference request successfully serves the selected model.
If that request fails, the expected catalog response does not make the route ready.
Onboarding Behavior Flags
The following flags toggle optional behaviors during onboarding. Set them before running nemohermes onboard.
| NEMOCLAW_SKIP_TELEGRAM_REACHABILITY | 1 to enable | Skips the Telegram bot reachability probe during onboard (useful in restricted networks). |
| NEMOCLAW_SKIP_SLACK_AUTH_VALIDATION | 1, true, yes, or on to enable | Skips the live Slack auth.test and apps.connections.open credential probes during onboard and channels add slack. Use only in restricted networks or hermetic test environments; Slack token format checks still apply. |
| NEMOCLAW_RESOURCE_PROFILE | profile name or default | Selects a sandbox CPU/RAM resource profile from the blueprint during onboarding. default means no resource preference, so NemoClaw passes no OpenShell CPU or memory flags. Unknown names fail fast. |
| NEMOCLAW_CPU | percentage or Kubernetes CPU quantity | Overrides the selected profile’s CPU size passed to OpenShell --cpu. Percentages resolve against detected capacity. |
| NEMOCLAW_RAM | percentage or Kubernetes memory quantity | Overrides the selected profile’s memory size passed to OpenShell --memory. Percentages resolve against detected capacity. |
| NEMOCLAW_SANDBOX_GPU | auto, 1, or 0 | Controls sandbox GPU passthrough during onboarding. auto enables GPU passthrough when an NVIDIA GPU is detected, 1 requires GPU passthrough, and 0 forces CPU-only sandbox creation. |
| NEMOCLAW_SANDBOX_GPU_DEVICE | NVIDIA GPU index, UUID, or CDI device name | Selects the GPU through OpenShell driver config on native Docker and Podman routes, or through the equivalent container-runtime selector on a compatibility route. Requires explicit sandbox GPU enablement with NEMOCLAW_SANDBOX_GPU=1 (or --sandbox-gpu for CLI-driven onboarding); otherwise onboarding rejects the selector instead of treating it as an implicit opt-in. |
| NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH | 1, true, yes, or on to enable | Bypasses recorded sandbox base-image resolution metadata during onboarding, recreation, and rebuild. NemoClaw reruns candidate resolution but can still use a compatible image from Docker’s local image store. Versioned release candidates that exist locally but fail validation are refreshed from the registry once during normal resolution. This setting does not discard onboarding session state. |
| NEMOCLAW_SANDBOX_BASE_LOCAL_BUILD | unset or auto (default); 1, true, yes, or on to enable; 0, false, no, or off to disable | Controls whether base-image resolution may build a compatible image locally. The default allows builds during normal CLI runs and disables them when NODE_ENV=test or VITEST=true. When source inputs or a missing/incompatible release-version base require a fresh build, disabling local builds makes resolution fail instead of using an unproven image. |
| NEMOCLAW_DOCKER_GPU_PATCH | unset, auto, fallback, 1, or 0; other legacy nonzero values remain accepted through v0.0.x and will be removed in v0.1.0 | Selects Linux Docker-driver GPU routing. Unset, auto, or 0 uses native OpenShell GPU injection on ordinary native Linux. fallback explicitly opts into one native attempt followed by one bounded compatibility retry when trusted host evidence identifies a GPU-routing failure. 1 and legacy nonzero values select the compatibility patch from the outset. Docker Desktop WSL and Jetson/Tegra use the compatibility path by default; Docker Desktop WSL ignores 0, while Jetson/Tegra accepts 0 only as a troubleshooting override that bypasses device-group propagation. |
| NEMOCLAW_OPENSHELL_GATEWAY_CONTAINER_PATCH | 1 to enable; disabled by default | This setting explicitly opts into the Linux gateway compatibility container for an older host ABI or a diagnostic run; use it only on a trusted local host because it uses host networking and mounts the Docker socket read-only even though the socket still exposes the privileged Docker API; prefer OpenShell 0.0.116’s directly supported glibc 2.39+ path; see Gateway Compatibility Container for the container boundary and removal conditions. |
| NEMOCLAW_OPENSHELL_GATEWAY_BIN | path | Advanced override for the openshell-gateway binary used by Linux Docker-driver startup. For the default port, the installer accepts the binary under an absolute XDG_BIN_HOME when set, otherwise ~/.local/bin/openshell-gateway; it also accepts /usr/local/bin/openshell-gateway or /usr/bin/openshell-gateway. Another path fails service staging. The macOS Homebrew service uses the formula’s binary. Defaults to the binary next to openshell, then common install paths. |
| NEMOCLAW_OPENSHELL_SANDBOX_BIN | path | Advanced override for the openshell-sandbox binary used by Linux Docker-driver startup. The macOS Homebrew service uses the formula’s driver layout. Defaults to the binary next to openshell, then common install paths. |
| NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR | path | Advanced override for the Linux Docker-driver gateway SQLite state directory and standalone-fallback PID file. Use a dedicated absolute directory; onboarding rejects relative paths, the shared NemoClaw state root or its parents, and existing nonempty directories without valid managed gateway configuration. Let onboarding create it when possible; its containing directory must be owned by the current user or root without group or world write access, and a pre-created state directory must be owner-controlled, non-symbolic, and mode 0700. For an externally supervised gateway, use the stateDir declared by NEMOCLAW_GATEWAY_MANAGEMENT; if this variable is also set, it must resolve to that same directory. Pass the original resolved absolute value with NEMOCLAW_GATEWAY_PORT when uninstalling that gateway. Port 8080 defaults to ~/.local/state/nemoclaw/openshell-docker-gateway; non-default ports default to ~/.local/state/nemoclaw/openshell-docker-gateway-<port>. |
| NEMOCLAW_AUTO_FIX_FIREWALL | 1 to enable | Opts in to automatic UFW remediation when Linux Docker-driver sandbox containers cannot reach the host gateway after a proven TCP failure. NemoClaw runs sudo -n only, validates the narrow Docker bridge subnet → gateway IP:port rule before invoking UFW, re-probes after applying it, and otherwise falls back to the printed manual command. |
| NEMOCLAW_WECHAT_QUIET | 1 to enable | Silences [wechat] poll diagnostics, including status updates and recoverable errors, during the host-side WeChat QR login. Host-side IDC redirect notices remain visible. |
Set NEMOCLAW_HERMES_SANDBOX_BASE_IMAGE_REF to a Hermes sandbox-base tag or digest to override base-image resolution for a legacy Dockerfile workload during onboarding or rebuild. Remote overrides must use the official repository and resolve to a repository digest. During a legacy rebuild, NemoClaw accepts a caller-supplied local alias only when Docker proves that the alias and the tracked official image have the same image ID, operating system, architecture, and official repository digest; the recreate handoff uses that immutable digest. On Linux, accepted images must pass the OpenShell ABI check. On every platform, they must pass the required MCP and ACP runtime and immutable security package inventory checks. During onboarding, NemoClaw accepts local bases only when it builds and pins them itself; a local image reference supplied through this environment variable is rejected. Onboarding uses the override whenever it selects a legacy Dockerfile workload, including --from <Dockerfile>. Managed-image onboarding and rebuild install an exact, pre-verified digest and do not consult the override, so they fail closed when the variable is set.
Onboard Profiling Traces
Set NEMOCLAW_TRACE=1 before nemohermes onboard to write an OpenTelemetry-style JSON trace for the run. If you do not set a trace path, NemoClaw writes a timestamped file under .e2e/traces/ in the current working directory. Use NEMOCLAW_TRACE_DIR to choose the output directory, or NEMOCLAW_TRACE_FILE to choose the output file.
Trace artifacts include onboard phase timing, sandbox and service readiness waits, policy application, inference validation probes, curl probe results, and sandbox build progress events. Secret-like metadata such as API keys, bearer tokens, cookies, and credentials is redacted before the file is written.
Probe Timeouts
The following variables tune how long internal probes wait before giving up. Defaults are sized for typical hardware; override only if you see false-positive timeouts.
Onboard and Sandbox Readiness Timeouts
The following environment variables tune onboard-time and recovery wall-clock limits. Set the onboarding variables before running nemohermes onboard if a slow connection or large model pull risks tripping the default.
For newly created OpenClaw and Hermes sandboxes, NEMOCLAW_SANDBOX_READY_TIMEOUT also covers the durable sandbox ID and no-op command checks that follow the OpenShell Ready state.
An unset, blank, invalid, or negative NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS value uses 30 seconds for OpenClaw gateway health and 90 seconds for Hermes gateway health.
Post-recovery OpenShell readiness uses 120 seconds when the recovery path does not supply another budget.
For managed or provider recovery, NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS covers gateway health and post-recovery OpenShell readiness.
When the deadline expires, NemoClaw leaves the existing container identity unchanged and does not restore the primary dashboard or API host forward.
Set the recovery override before a start or recover command when gateway health or OpenShell readiness needs more time.
If the Ollama pull or post-create readiness timeout fires, onboarding emits the elapsed budget plus a hint to raise the relevant variable. The Ollama pull preserves its partial download for the next attempt. A post-create readiness timeout preserves the sandbox. Follow Inspect retained sandbox recovery, and retry onboarding only after retained recovery completes.
A post-policy re-registration failure leaves the sandbox in place and reports that OpenShell did not re-register it.
Lifecycle Behavior Flags
The following flags change defaults for commands that manage existing sandboxes.
| NEMOCLAW_CONFIG_ACCEPT_NEW_PATH | Exactly "1" to opt in (true, yes, on are not accepted) | Allows nemohermes <name> config set to write a dotpath that does not already exist in the sandbox config, without the interactive confirmation. Equivalent to passing --config-accept-new-path, and it takes precedence over NEMOCLAW_NON_INTERACTIVE=1. Without it, a run without a TTY refuses the write instead. |
| NEMOCLAW_CONFIRM_LEGACY_MANAGED_RECREATE | JSON array of sandbox names | Confirms to the installer that the listed set of pre-fingerprint OpenClaw or Hermes sandboxes used NemoClaw-managed images, allowing recovery onto the current managed image. The normalized names must exactly match the installer’s printed array. Set it only after verifying every named sandbox. Recorded custom-image evidence remains blocked. |
| NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR | 1 to enable | Skips automatic DNS-proxy mutation for stale inference.local routes during nemohermes <name> connect and nemohermes <name> connect --probe-only. The command still probes the route and exits non-zero when the provider-specific requirement fails. An ollama-local route still requires a healthy authenticated proxy and HTTP 2xx from inference.local/v1/models. Use only as a troubleshooting escape hatch. |
| NEMOCLAW_SKIP_UNREACHABLE_SANDBOX_BACKUP | Exactly 1 to opt in (true, yes, 0 are not accepted) | Applies to standalone nemohermes backup-all runs. Skips running sandboxes whose in-sandbox SSH endpoint does not answer. It does not relax the installer’s strict pre-upgrade backup, which still aborts if any registered sandbox is skipped or fails. Any uncommitted state since the last successful backup is not included in the skipped backup. |
| NEMOCLAW_UNINSTALL_ALL_GATEWAY_PORTS | 1 to opt in | Makes nemohermes uninstall remove every gateway port on the host instead of only the port NEMOCLAW_GATEWAY_PORT selects. Equivalent to passing the --all-gateway-ports flag; the whole-host Proceed? confirmation still applies unless --yes is also passed. Each port runs as its own uninstall, and the variable is dropped from those runs so the sweep cannot re-enter itself. |
| NEMOCLAW_UNINSTALL_DESTROY_USER_DATA | 1 to opt in | Acknowledges data loss during nemohermes uninstall, skips eligible fresh sandbox backups, and removes the otherwise-preserved entries (rebuild-backups/, backups/, sandboxes.json) in the selected gateway’s state root. It does not select the explicit --destroy-user-data CLI-shim removal path; shim handling follows the ordinary selected-gateway scope. The global Proceed? confirmation still applies unless --yes is also passed. |
Legacy nemohermes setup
Deprecated. Use nemohermes onboard instead. Running nemohermes setup now delegates directly to nemohermes onboard.