> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemoclaw/llms.txt. > For full documentation content, see https://docs.nvidia.com/nemoclaw/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemoclaw/_mcp/server. # Manage Sandbox Lifecycle > List sandboxes, check health, inspect logs, manage dashboard ports, reconfigure providers, rebuild safely, upgrade sandboxes, and uninstall NemoClaw. Use this guide after you finish the [OpenClaw quickstart](../get-started/quickstart). Use this guide after you finish [Quickstart with Hermes](../get-started/quickstart-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](../reference/cli-selection-guide) for the boundary between `nemoclaw` and `openshell`. When a workflow uses the lower-level OpenShell CLI, see [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `nemohermes`, `nemoclaw`, and `openshell`. ## List Sandboxes List every sandbox registered on this host: ```bash nemoclaw list ``` ```bash nemohermes list ``` The list shows each sandbox's model, provider, policy presets, active SSH session indicator, and dashboard URL when a dashboard port is recorded. Use JSON output for scripts: ```bash nemoclaw list --json ``` ```bash nemohermes list --json ``` ## Check Sandbox Health Check a specific sandbox's health, inference route, active connections, live policy, update status, and messaging-channel overlap warnings: ```bash nemoclaw my-assistant status ``` ```bash nemohermes my-assistant status ``` Use the host-level status command when you want the sandbox inventory plus host auxiliary service state, such as cloudflared: ```bash nemoclaw status ``` ```bash nemohermes status ``` ## Inspect Logs View recent sandbox logs: ```bash nemoclaw my-assistant logs ``` ```bash nemohermes my-assistant logs ``` Stream logs while you reproduce a problem: ```bash nemoclaw my-assistant logs --follow ``` ```bash nemohermes my-assistant logs --follow ``` The log command reads both OpenClaw gateway output and OpenShell audit events, so policy denials appear beside gateway logs. The log command reads both Hermes gateway output and OpenShell audit events, so policy denials appear beside gateway logs. ## Collect Diagnostics Collect diagnostics for bug reports or support handoff: ```bash nemoclaw debug --sandbox my-assistant --output nemoclaw-debug.tar.gz ``` ```bash nemohermes debug --sandbox my-assistant --output nemoclaw-debug.tar.gz ``` Use `--quick` for a smaller local summary: ```bash nemoclaw debug --quick --sandbox my-assistant ``` ```bash nemohermes debug --quick --sandbox my-assistant ``` The debug command gathers system information, Docker state, gateway logs, and sandbox status. ## Manage Dashboard Ports 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. ```bash openshell forward start --background my-gpt-claw ``` To list active forwards across all sandboxes, run the following command. ```bash openshell forward list ``` ## Run Multiple Sandboxes Each sandbox needs its own dashboard port, since `openshell forward` refuses to bind a port that another sandbox is already using. When the default port is already held by another sandbox, `nemoclaw onboard` scans ports `18789` through `18799` and uses the next free port. 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. ```bash nemoclaw onboard # first sandbox uses 18789 nemoclaw onboard # second sandbox uses the next free port, such as 18790 ``` ```bash nemohermes onboard # first sandbox uses 18789 nemohermes onboard # second sandbox uses the next free port, such as 18790 ``` To choose a specific port, pass `--control-ui-port`: ```bash nemoclaw onboard --control-ui-port 19000 ``` ```bash nemohermes onboard --control-ui-port 19000 ``` You can also set `CHAT_UI_URL` or `NEMOCLAW_DASHBOARD_PORT` before onboarding: ```bash CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard NEMOCLAW_DASHBOARD_PORT=19000 nemoclaw onboard ``` ```bash CHAT_UI_URL=http://127.0.0.1:19000 nemohermes onboard NEMOCLAW_DASHBOARD_PORT=19000 nemohermes onboard ``` For full details on port conflicts and overrides, refer to [Port already in use](../reference/troubleshooting#port-already-in-use). ## Reconfigure or Recover Recover from a misconfigured sandbox without re-running the full onboard wizard or destroying workspace state. ### Change Inference Model or API Change the active model or provider at runtime without rebuilding the sandbox: ```bash nemoclaw inference set --model --provider ``` ```bash nemohermes inference set --model --provider ``` Refer to [Switch Inference Providers](../inference/switch-inference-providers) for provider-specific model IDs and API compatibility notes. ### Restart the Gateway and Port Forward If `nemoclaw status` reports the sandbox is alive but the gateway is not running, run the recover command instead of opening a shell. If `nemohermes status` reports the sandbox is alive but the Hermes gateway is not running, run the recover command instead of opening a shell. ```bash nemoclaw recover ``` ```bash nemohermes recover ``` 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 [`nemoclaw recover`](../reference/commands#nemoclaw-name-recover) for details. Refer to the command reference for details on `nemohermes recover`. ### Reset a Stored Credential If a provider credential was entered incorrectly during onboarding, clear the gateway-registered value and re-enter it on the next onboard run: ```bash nemoclaw credentials list # see which providers are registered nemoclaw credentials reset # clear a single provider, for example nvidia-prod nemoclaw onboard # re-run to re-enter the cleared provider ``` ```bash nemohermes credentials list # see which providers are registered nemohermes credentials reset # clear a single provider, for example nvidia-prod nemohermes onboard # re-run to re-enter the cleared provider ``` The credentials command is documented in full at [`nemoclaw credentials reset `](../reference/commands#nemoclaw-credentials-reset-provider). The credentials command is documented in full in the [Commands reference](../reference/commands). ### Rebuild a Sandbox While Preserving Workspace State If you changed the underlying Dockerfile, upgraded OpenClaw, or want to pick up a new base image without losing your sandbox's workspace files, use `rebuild` instead of destroying and recreating: 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: ```bash nemoclaw rebuild ``` ```bash nemohermes rebuild ``` 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 [`nemoclaw rebuild`](../reference/commands#nemoclaw-name-rebuild) for flag details. Refer to the [Commands reference](../reference/commands) for `nemohermes rebuild` flag details. ### Add a Network Preset After Onboarding Apply an additional preset, such as Telegram or GitHub, to a running sandbox without re-onboarding: ```bash nemoclaw policy-add ``` ```bash nemohermes policy-add ``` Refer to [`nemoclaw policy-add`](../reference/commands#nemoclaw-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`](../reference/commands#nemoclaw-onboard) for the full table. ## Update to the Maintained Version When a maintained NemoClaw release becomes available, update the `nemoclaw` CLI on your host and check existing sandboxes for stale agent/runtime versions. 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 may trail the newest semver or `latest` tag while validation completes. ### Update the NemoClaw CLI Re-run the installer. Before it onboards anything, the installer calls [`nemoclaw backup-all`](../reference/commands#nemoclaw-backup-all) automatically, storing a snapshot of each running sandbox in `~/.nemoclaw/rebuild-backups/` as a safety net. 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 automatic path is offered only when the existing `nemoclaw` 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 `nemoclaw backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (both verbs are tried 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_OPENSHELL_UPGRADE_PREPARED=1 bash`. The automatic path is offered 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` (both verbs are tried 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`. ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` ### Upgrade Sandboxes with Stale Agent and Runtime Versions The installer checks registered sandboxes after onboarding succeeds and runs `nemoclaw upgrade-sandboxes --auto` for stale running sandboxes. 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. ```bash nemoclaw snapshot create --name pre-upgrade # optional, recommended nemoclaw update --yes # updates CLI through the maintained installer flow nemoclaw upgrade-sandboxes --check # verify or list remaining stale/unknown sandboxes nemoclaw upgrade-sandboxes # manually rebuild remaining stale running sandboxes ``` ```bash nemohermes snapshot create --name pre-upgrade # optional, recommended nemohermes update --yes # updates CLI through the maintained installer flow nemohermes upgrade-sandboxes --check # verify or list remaining stale/unknown sandboxes nemohermes upgrade-sandboxes # manually rebuild remaining stale running sandboxes ``` `nemoclaw update` is the CLI wrapper around the same installer path as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`. Use `nemoclaw update --check` when you only want to inspect version state and see the maintained update command. `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 `nemoclaw upgrade-sandboxes --auto` to skip the confirmation prompt. 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: ```bash nemoclaw snapshot restore pre-upgrade ``` ```bash nemohermes snapshot restore pre-upgrade ``` ### What Changes During a Rebuild Each rebuild destroys the existing container and creates a new one. NemoClaw protects your data through the same backup-and-restore flow as [`nemoclaw rebuild`](../reference/commands#nemoclaw-name-rebuild): * NemoClaw preserves manifest-defined workspace state. Before deleting the old container, NemoClaw snapshots the state directories and durable state files defined in the agent manifest, typically `/sandbox/.openclaw/workspace/`; for Hermes this also includes `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. * NemoClaw does not preserve runtime changes outside the workspace state directories. This includes packages installed inside the running container with `apt` or `pip`, files in non-workspace paths, and in-memory or process state. If you have customized the running container at runtime, capture that as `Dockerfile` changes for `nemoclaw onboard --from` or a manual `openshell sandbox download` before the rebuild starts. NemoClaw protects your data through the same backup-and-restore flow as `nemohermes rebuild`: * NemoClaw preserves manifest-defined Hermes state. Before deleting the old container, NemoClaw snapshots the state directories and durable state files defined in the Hermes manifest, including `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. * NemoClaw does not preserve runtime changes outside the manifest-defined state directories. This includes packages installed inside the running container with `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 required manifest-defined state cannot be copied, 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](backup-restore) for the full list of state-preservation guarantees, snapshot retention, and instructions for manual backups when the auto-flow is not enough. The rebuild preflight reads the provider credential recorded by your last `nemoclaw onboard` session. If you have switched providers since onboarding, for example from a remote API to a local Ollama setup, the preflight may still reference the old key and fail before any destroy step runs. To recover, re-run `nemoclaw onboard` and select your current provider. This refreshes the session metadata. 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 may 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. ## Uninstall To remove NemoClaw and all resources created during setup, run the CLI's built-in uninstall command: ```bash nemoclaw uninstall ``` ```bash nemohermes uninstall ``` | Flag | Effect | | ------------------ | ------------------------------------------ | | `--yes` | Skip the confirmation prompt. | | `--keep-openshell` | Leave OpenShell binaries installed. | | `--delete-models` | Also remove NemoClaw-pulled Ollama models. | 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](../reference/commands#nemoclaw-uninstall) 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: ```bash curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash ``` The same `--yes`, `--keep-openshell`, and `--delete-models` flags listed above also apply to the hosted script. Pass them after `bash -s --`. ```bash curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash -s -- --yes --delete-models ``` For a full comparison of the two forms, including what they fetch, what they trust, and when to prefer each, see [`nemoclaw uninstall` vs. the hosted `uninstall.sh`](../reference/commands#nemoclaw-uninstall-vs-the-hosted-uninstallsh). ## Related Topics * [Set Up Messaging Channels](messaging-channels) to connect Telegram, Discord, or Slack. * [Workspace Files](workspace-files) for persistent OpenClaw files inside the sandbox. * [Backup and Restore](backup-restore) for snapshot and restore workflows. * [Monitor Sandbox Activity](../monitoring/monitor-sandbox-activity) for observability tools.