Manage Sandbox Lifecycle | NVIDIA NemoClaw

Use 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 Sandboxes

List every sandbox registered on this host:

$ nemohermes list

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:

$ 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:

$ nemohermes my-assistant status

Use the host-level status command when you want the sandbox inventory plus host auxiliary service state, such as cloudflared:

$ nemohermes status

Inspect Logs

View recent sandbox logs:

$ nemohermes my-assistant logs

Stream logs while you reproduce a problem:

$ nemohermes my-assistant logs --follow

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:

$ nemohermes debug --sandbox my-assistant --output nemoclaw-debug.tar.gz

Use --quick for a smaller local summary:

$ 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.

$ openshell forward start --background <dashboard-port> my-gpt-claw

To list active forwards across all sandboxes, run the following command.

$ 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 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. Gateway and dashboard cleanup is scoped by sandbox name and port. A later onboarding run that uses a different NEMOCLAW_GATEWAY_PORT or --control-ui-port does not tear down the first sandbox’s gateway or dashboard forward.

$ 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:

$ nemohermes onboard --control-ui-port 19000

You can also set CHAT_UI_URL or NEMOCLAW_DASHBOARD_PORT before onboarding:

$ 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.

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:

$ nemohermes inference set --model <model> --provider <provider>

Refer to Switch Inference Providers for provider-specific model IDs and API compatibility notes.

Restart the Gateway and Port Forward

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.

$ nemohermes <sandbox-name> 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 nemohermes <name> recover for details.

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:

$ nemohermes credentials list                # see which providers are registered
$ nemohermes credentials reset <PROVIDER>    # clear a single provider, for example nvidia-prod
$ nemohermes onboard                         # re-run to re-enter the cleared provider

The command reference documents nemohermes credentials reset <PROVIDER> in full.

Rebuild a Sandbox While Preserving Workspace State

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:

$ nemohermes <sandbox-name> 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 nemohermes <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 re-onboarding:

$ nemohermes <sandbox-name> policy-add

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.

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. If you need a specific release, set NEMOCLAW_INSTALL_TAG on the bash side of the install pipeline.

$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_INSTALL_TAG=v0.0.63 bash
$ nemohermes upgrade-sandboxes --check

Before upgrade work, the installer runs nemohermes backup-all when the installed CLI supports it. For manual upgrade flows, create a snapshot first and then run the update or rebuild command you need:

$ nemohermes <sandbox-name> snapshot create --name pre-upgrade
$ nemohermes update --yes
$ nemohermes 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 <Dockerfile> 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. For the full state-preservation contract, snapshot restore behavior, and manual backup workflow, refer to Backup and Restore. For command flags, refer to nemohermes update, nemohermes upgrade-sandboxes, and nemohermes <name> rebuild.

Uninstall

To remove NemoClaw and all resources created during setup, run the CLI’s built-in uninstall command:

$ 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 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:

$ 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 --.

$ 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, refer to nemohermes uninstall vs. the hosted uninstall.sh.

Set Up Messaging Channels to connect Telegram, Discord, or Slack.
Workspace Files for persistent OpenClaw files inside the sandbox.
Backup and Restore for snapshot and restore workflows.
Monitor Sandbox Activity for observability tools.