NemoClawUse this guide after you finish Quickstart with Hermes. It covers day-two sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling.
When a workflow uses the lower-level OpenShell CLI, see CLI Selection Guide for the boundary between nemohermes, nemoclaw, and openshell.
List every sandbox registered on this host:
The list shows each sandbox’s model, provider, policy presets, active SSH session indicator, and dashboard URL when NemoClaw records a dashboard port. Use JSON output for scripts:
Check a specific sandbox’s health, inference route, active connections, live policy, update status, and messaging-channel overlap warnings:
Use the host-level status command when you want the sandbox inventory plus host auxiliary service state, such as cloudflared:
View recent sandbox logs:
Stream logs while you reproduce a problem:
The log command reads both Hermes gateway output and OpenShell audit events, so policy denials appear beside gateway logs.
Collect diagnostics for bug reports or support handoff:
Use --quick for a smaller local summary:
The debug command gathers system information, Docker state, gateway logs, and sandbox status.
If the forward stopped, or the installer reported that no active forward was found and the URL does not load, restart it manually with the port from the install summary.
To list active forwards across all sandboxes, run the following command.
Each sandbox needs its own dashboard port, since openshell forward refuses to bind a port that another sandbox is already using.
When the default API port is already held by another sandbox, nemohermes onboard scans for the next free port and records it for the sandbox.
If you intentionally run separate OpenShell gateways on the same host, set a different NEMOCLAW_GATEWAY_PORT before each onboarding run.
NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another.
To choose a specific port, pass --control-ui-port:
You can also set CHAT_UI_URL or NEMOCLAW_DASHBOARD_PORT before onboarding:
For full details on port conflicts and overrides, refer to Port already in use.
Recover from a misconfigured sandbox without re-running the full onboard wizard or destroying workspace state.
Change the active model or provider at runtime without rebuilding the sandbox:
Refer to Switch Inference Providers for provider-specific model IDs and API compatibility notes.
If nemohermes <name> status reports the sandbox is alive but the Hermes gateway is not running, run the recover command instead of opening a shell.
The command restarts the in-sandbox gateway and re-establishes the dashboard port-forward in one step.
It is idempotent and safe to script.
Refer to nemohermes <name> recover for details.
If you entered a provider credential incorrectly during onboarding, clear the gateway-registered value and re-enter it on the next onboard run:
The command reference documents nemohermes credentials reset <PROVIDER> in full.
If you changed the underlying Dockerfile, upgraded Hermes, or want to pick up a new base image without losing your sandbox’s state files, use rebuild instead of destroying and recreating:
Rebuild preserves the mounted workspace and registered policies while recreating the container.
If NemoClaw cannot archive any requested state path, it reports the backup failure and stops before deleting the original sandbox.
Refer to nemohermes <name> rebuild for flag details.
Apply an additional preset, such as Telegram or GitHub, to a running sandbox without re-onboarding:
Refer to nemohermes <name> policy-add for usage details and flags.
Non-interactive re-onboards in the default suggested policy mode preserve presets added this way.
To make a re-onboard authoritative, set NEMOCLAW_POLICY_MODE=custom and provide NEMOCLAW_POLICY_PRESETS with the exact list to apply; onboarding removes anything else.
See NEMOCLAW_POLICY_MODE for the full table.
When a maintained NemoClaw release becomes available, update the nemohermes CLI on your host and check existing sandboxes for stale agent/runtime versions.
The standard installer follows the admin-promoted lkg release tag by default, so it can trail the newest semver or latest tag while validation completes.
To pin a specific release in a curl | bash install, set NEMOCLAW_INSTALL_TAG on the bash side of the pipe, or export it before the pipeline:
Do not place NEMOCLAW_INSTALL_TAG=... only before curl; shell assignment in that position applies to curl, not to the installer running under bash.
If the requested ref cannot be fetched, the installer exits with a clear error instead of falling back to lkg.
Re-run the installer.
Before it onboards anything, the installer calls nemohermes backup-all automatically, storing a snapshot of each running sandbox in ~/.nemoclaw/rebuild-backups/ as a safety net.
If your existing gateway is from OpenShell earlier than 0.0.37, the installer prompts before it runs the new automatic gateway upgrade path.
The installer offers the automatic path only when the existing nemohermes CLI supports backup-all.
Older installs must preserve sandbox state manually before retiring the gateway.
For unattended installs, set NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1, or manually run nemohermes backup-all, openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy (the command tries both verbs so the right one runs on either OpenShell release), and sudo pkill -f openshell-gateway if a privileged host gateway remains before rerunning the installer as curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash.
The installer checks registered sandboxes after onboarding succeeds and runs nemohermes upgrade-sandboxes --auto for stale running sandboxes.
Use upgrade-sandboxes directly to verify the result, rebuild when you skipped the installer or onboarding step, or handle sandboxes that were stopped or could not be version checked.
The upgrade flow is non-destructive by default because NemoClaw preserves manifest-defined workspace state, but a manual snapshot before any major upgrade gives you a state restore point.
nemohermes update is the CLI wrapper around the same installer path with Hermes selected.
Use nemohermes update --check when you only want to inspect version state and see the maintained update command.
For scripted manual rebuilds, use nemohermes upgrade-sandboxes --auto to skip the confirmation prompt.
If the upgraded sandbox needs its workspace state reverted, restore the pre-upgrade snapshot into the running sandbox. This restores saved state directories only; it does not downgrade the sandbox image or agent/runtime:
Each rebuild destroys the existing container and creates a new one.
NemoClaw protects your data through the same backup-and-restore flow as nemohermes <name> rebuild:
SOUL.md and the SQLite database behind .hermes/state.db. Stored credentials (~/.nemoclaw/credentials.json) and registered policy presets live on the host and are re-applied to the new sandbox automatically.apt or pip, files in non-state paths, and in-memory or process state. If you have customized the running container at runtime, capture that as Dockerfile changes for nemohermes onboard --from or a manual openshell sandbox download before the rebuild starts.Aborts before the destroy step are non-destructive. The flow refuses to proceed past preflight if a credential is missing or past backup if it cannot copy required manifest-defined state, so a failed run leaves the original sandbox intact and ready to retry. When a backup command reports partial archive output, NemoClaw keeps the usable entries and reports only the manifest-defined paths that could not be archived.
See Backup and Restore for the full list of state-preservation guarantees, snapshot retention, and instructions for manual backups when the auto-flow is not enough.
If the rebuild aborts with Missing credential: <KEY>
The rebuild preflight reads the provider credential recorded by your last nemohermes onboard session.
If you have switched providers since onboarding, for example from a remote API to a local Ollama setup, the preflight can still reference the old key and fail before any destroy step runs.
To recover, re-run nemohermes onboard and select your current provider.
This refreshes the session metadata.
Your existing container keeps serving traffic until the new image is ready.
To remove NemoClaw and all resources created during setup, run the CLI’s built-in uninstall command:
The uninstall command preserves ~/.nemoclaw/rebuild-backups/ (host-side snapshots that snapshot and backup-all commands write), ~/.nemoclaw/backups/ (workspace backups that scripts/backup-workspace.sh writes), and ~/.nemoclaw/sandboxes.json (the sandbox registry) by default.
Uninstall removes every other entry under ~/.nemoclaw/.
Interactive runs prompt before they remove the preserved entries; the default answer keeps them.
For non-interactive runs (--yes, NEMOCLAW_NON_INTERACTIVE=1, or a non-TTY shell), set NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1 to acknowledge data loss and remove the preserved entries as well.
See the Commands reference for the full preservation contract.
The CLI uninstall command runs the version-pinned uninstall.sh that shipped with your installed CLI, so it does not fetch anything over the network at uninstall time.
If the CLI is missing or broken, fall back to the hosted script:
The same --yes, --keep-openshell, and --delete-models flags listed above also apply to the hosted script. Pass them after bash -s --.
For a full comparison of the two forms, including what they fetch, what they trust, and when to prefer each, refer to nemohermes uninstall vs. the hosted uninstall.sh.