Manage SandboxesOperate Sandboxes

Update Sandboxes

View as Markdown

Update the host CLI first, then check whether existing sandboxes need rebuilds. The standard installer follows the admin-promoted lkg release tag by default.

Understand Agent Version Pins

NemoClaw pins the selected agent version into the sandbox image at build time rather than updating it at runtime. Existing sandboxes do not auto-upgrade when a newer NemoClaw release ships a newer agent version. Run nemoclaw <name> status to see the agent version currently running in a sandbox. After updating the host CLI, run nemoclaw <name> rebuild to recreate the sandbox with the newer pin while preserving the agent state that NemoClaw manages.

The OpenClaw runtime build target is declared by OPENCLAW_VERSION in the NemoClaw Dockerfiles. The min_openclaw_version field in nemoclaw-blueprint/blueprint.yaml is the compatibility floor for direct blueprint consumers, so it can be lower than the Dockerfile target.

$curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
$nemoclaw upgrade-sandboxes --check

If a support workflow asks you to pass the maintained tag explicitly, clear any inherited NEMOCLAW_INSTALL_REF and set NEMOCLAW_INSTALL_TAG on the bash side of the install pipeline.

$curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_INSTALL_REF= 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 backup, the installer requires any existing OpenShell executable it will use to report a version, then compares that version with the supported range declared by the prepared current source. It retires the running gateway before replacing an out-of-range OpenShell installation, keeps the gateway when the installed version is supported, and stops without retiring it when the installed version or supported range cannot be validated. If the installed OpenShell release cannot retire its gateway through a supported lifecycle command or the verified NemoClaw-owned gateway PID, the installer also stops after backup with the sandbox backups preserved.

After the host CLI and OpenShell update, the installer runs nemoclaw 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.

Legacy managed-image confirmation never overrides recorded custom-image evidence.

A custom OpenClaw sandbox can be recovered only when the selected validated backup independently carries complete authoritative image-plugin provenance; otherwise recovery stops before deletion.

The installer attempts every eligible recovery, exits with a nonzero status if any recovery fails, and skips generic onboarding after successful recovery.

When a recorded sandbox is not observed in any phase on its recorded gateway, the recovery pass exits 0 but reports the sandbox as not found rather than recovered. This usually means a prior uninstall removed the gateway and Docker image while preserving sandboxes.json.

The installer finishes with Installation completed with warnings and tells you to run nemoclaw <name> destroy, then nemoclaw onboard, instead of claiming recovery succeeded.

For a manual update flow, create a snapshot first:

$nemoclaw <sandbox-name> snapshot create --name pre-upgrade
$nemoclaw update --yes
$nemoclaw upgrade-sandboxes --check

Use nemoclaw upgrade-sandboxes --check to read sandbox state without starting, recovering, or selecting a gateway. When all your registered sandboxes resolve to one recorded gateway, the command queries that gateway instead of the gateway for your current NEMOCLAW_GATEWAY_PORT.

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 the manifest-defined state paths, such as packages installed manually in the running container, are not preserved.