> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemoclaw/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemoclaw/_mcp/server. # Manage Sandbox Lifecycle > List sandboxes, check health, inspect logs, reconfigure providers, rebuild safely, upgrade sandboxes, and uninstall NemoClaw. Use this guide after you finish [Quickstart with Deep Agents](../get-started/quickstart). It covers ongoing sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling. When a workflow uses the lower-level OpenShell CLI, refer to [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `nemo-deepagents`, `nemo-deepagents`, and `openshell`. ## List Sandboxes List every sandbox registered on this host: ```bash nemo-deepagents list ``` The list shows each sandbox's model, provider, policy presets, and active SSH session indicator. Use JSON output for scripts: ```bash nemo-deepagents list --json ``` ## Check Sandbox Health Check a specific sandbox's health, inference route, active connections, live policy, and update status: ```bash nemo-deepagents my-assistant status ``` Use the host-level status command when you want the sandbox inventory plus host auxiliary service state, such as cloudflared: ```bash nemo-deepagents status ``` ## Inspect Logs View recent sandbox logs: ```bash nemo-deepagents my-assistant logs ``` Stream logs while you reproduce a problem: ```bash nemo-deepagents my-assistant logs --follow ``` The log command reads Deep Agents sandbox output and OpenShell audit events, so policy denials appear beside terminal-runtime logs. ## Collect Diagnostics Collect diagnostics for bug reports or support handoff: ```bash nemo-deepagents debug --sandbox my-assistant --output nemoclaw-debug.tar.gz ``` Use `--quick` for a smaller local summary: ```bash nemo-deepagents debug --quick --sandbox my-assistant ``` The debug command gathers system information, Docker state, sandbox logs, and sandbox status. ## Run Multiple Sandboxes Deep Agents sandboxes do not expose a dashboard port. The first `nemo-deepagents onboard` run can use the default sandbox name from the wizard. When you create another Deep Agents sandbox, choose a distinct sandbox name in the wizard or pass `--name` in scripted runs. 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. Gateway cleanup is scoped by sandbox name and port. ```bash nemo-deepagents onboard # For an additional named sandbox: nemo-deepagents onboard --name ``` ## Reconfigure or Recover Recover from a misconfigured sandbox without re-running the full onboard wizard or destroying workspace state. ### Change Inference Model or API For Deep Agents, recreate the sandbox when you change the provider or model so `/sandbox/.deepagents/config.toml` and the OpenShell route stay aligned: ```bash nemo-deepagents onboard --fresh --name --recreate-sandbox ``` Refer to [Switch Inference Providers](../inference/switch-inference-providers) for provider-specific model IDs and API compatibility notes. ### Restart the Gateway and Port Forward Deep Agents sandboxes are terminal runtimes and do not expose an OpenClaw or Hermes in-sandbox gateway. Use `nemo-deepagents status`, `logs`, `connect`, and `rebuild` for recovery. If the terminal runtime reports degraded health, rebuild the sandbox instead of using `recover` or `gateway restart`. ### Reset a Stored Credential If you entered a provider credential incorrectly during onboarding, clear the gateway-registered value and re-enter it on the next onboard run: ```bash nemo-deepagents credentials list # see which providers are registered nemo-deepagents credentials reset # clear a single provider, for example nvidia-prod nemo-deepagents onboard # re-run to re-enter the cleared provider ``` Refer to [`nemo-deepagents credentials reset `](../reference/commands#nemo-deepagents-credentials-reset-provider) for full command details. ### Rebuild a Sandbox While Preserving Workspace State If you changed the underlying Dockerfile, upgraded Deep Agents Code, enabled Tavily Search, or want to pick up a new base image without losing manifest-defined Deep Agents state, use `rebuild` instead of destroying and recreating: ```bash nemo-deepagents rebuild ``` The rebuild command preserves manifest-defined Deep Agents state, regenerates `config.toml`, reconstructs managed MCP projection state, and reapplies 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. When rebuild starts with shields up, NemoClaw opens a 30-minute shields-down window for backup and recreation. A detached auto-lock timer remains the recovery authority until NemoClaw commits a successful shields-up state, including when the host rebuild process exits unexpectedly. Refer to [`nemo-deepagents rebuild`](../reference/commands#nemo-deepagents-name-rebuild) for flag details. ### Add a Network Preset After Onboarding Apply an additional preset, such as Telegram or GitHub, to a running sandbox without running onboarding again: ```bash nemo-deepagents policy-add ``` Refer to [`nemo-deepagents policy-add`](../reference/commands#nemo-deepagents-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. Refer to [`NEMOCLAW_POLICY_MODE`](../reference/commands#nemo-deepagents-onboard) for the full table. ## Update to the Maintained Version When a maintained NemoClaw release becomes available, update the host CLI and then check whether existing sandboxes need rebuilds. The standard installer follows the admin-promoted `lkg` release tag by default. ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash nemo-deepagents upgrade-sandboxes --check ``` If a support workflow asks you to pass the maintained tag explicitly, set `NEMOCLAW_INSTALL_TAG` on the `bash` side of the install pipeline. ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_INSTALL_TAG=lkg bash ``` Before upgrade work, the installer prepares the current NemoClaw CLI without replacing OpenShell and requires a fresh backup of every registered sandbox. If any sandbox is skipped or fails, the installer exits before it changes the gateway. After the host CLI and OpenShell update, the installer runs `nemo-deepagents upgrade-sandboxes --auto` to reconcile the existing sandboxes. If an existing sandbox is not Ready, the automatic path requires a validated latest backup whose sandbox and agent identity match the registry and positive evidence that NemoClaw managed the image. For a listed pre-fingerprint OpenClaw or Hermes registry entry, you can provide that evidence through the installer's explicit managed-image confirmation. In a non-interactive run, set `NEMOCLAW_CONFIRM_LEGACY_MANAGED_RECREATE` to the exact JSON array of names printed by the installer, such as `["my-assistant","preserve-hermes"]`, only after you verify every named sandbox used a managed image. Recorded custom-image evidence remains blocked from automatic recreation. The installer attempts every eligible recovery, exits with a nonzero status if any recovery fails, and skips generic onboarding after successful recovery. For manual upgrade flows, create a snapshot first and then run the update or rebuild command you need: ```bash nemo-deepagents snapshot create --name pre-upgrade nemo-deepagents update --yes nemo-deepagents upgrade-sandboxes --check ``` Each rebuild destroys the old container and creates a new one, while preserving the manifest-defined workspace or agent state that NemoClaw knows how to snapshot. `upgrade-sandboxes --check` can report a sandbox as stale because the running agent version is behind, because the managed NemoClaw image fingerprint differs from the current CLI, or both. Custom-image sandboxes created with `--from ` are not marked stale solely by image fingerprint, so an upgrade check does not accidentally replace them with the default image. Runtime changes outside those state paths, such as packages installed manually in the running container, are not preserved. Refer to [Backup and Restore](backup-restore) for the full state-preservation contract, snapshot restore behavior, and manual backup workflow. Refer to [`nemo-deepagents update`](../reference/commands#nemo-deepagents-update), [`nemo-deepagents upgrade-sandboxes`](../reference/commands#nemo-deepagents-upgrade-sandboxes), and [`nemo-deepagents rebuild`](../reference/commands#nemo-deepagents-name-rebuild) for command flags. ## Uninstall To remove NemoClaw and all resources created during setup, run the CLI's built-in uninstall command: ```bash nemo-deepagents uninstall ``` | Flag | Effect | | --------------------- | ----------------------------------------------------------------------------------- | | `--yes` | Skip the confirmation prompt. | | `--keep-openshell` | Leave OpenShell binaries installed. | | `--delete-models` | Also remove NemoClaw-pulled Ollama models. | | `--destroy-user-data` | Also remove preserved user data (`rebuild-backups/`, `backups/`, `sandboxes.json`). | | `--gateway ` | Override the gateway name to remove (default: `nemoclaw`). | The uninstall command preserves `~/.nemoclaw/rebuild-backups/` (host-side snapshots written by snapshot and `backup-all` commands), `~/.nemoclaw/backups/` (workspace backups written by `scripts/backup-workspace.sh`), 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), pass `--destroy-user-data` (or set `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1`) to acknowledge data loss and remove the preserved entries as well. `--yes` stays non-destructive by design. It only acknowledges the global confirmation prompt and never purges preserved user data on its own. Full purge always requires an explicit `--destroy-user-data` or the matching env var, so existing automation using `--yes` retains its safe behaviour. For a full host-side file reference, see [Host Files and State](../reference/host-files-and-state). Refer to the [Commands reference](../reference/commands#nemo-deepagents-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`, `--delete-models`, `--destroy-user-data`, and `--gateway` 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 ``` Refer to [`nemo-deepagents uninstall` vs. the hosted `uninstall.sh`](../reference/commands#nemo-deepagents-uninstall-vs-the-hosted-uninstallsh) for a full comparison of what the two forms fetch, what they trust, and when to prefer each. ## Related Topics * [Workspace Files](workspace-files) for Deep Agents state, skills, memory, and managed config files. * [Backup and Restore](backup-restore) for snapshot and restore workflows. * [Set Up MCP Servers](set-up-mcp-servers) for managed MCP configuration. * [Commands reference](../reference/commands) for lifecycle command flags.