Recover and Rebuild Sandboxes

Use the lightest recovery operation that repairs the sandbox while preserving its supported state.

Upgrade from a Release That Used Shields

Shields has been retired from NemoClaw. The current CLI has no Shields commands, status, timers, or supported locked posture. After an upgrade, NemoClaw prints a retirement notice while it still finds legacy Shields state and identifies the affected sandbox records when possible.

If the sandbox has only an inert legacy state record, create an independent trusted backup. Then rebuild the affected sandbox before running further mutations.

If NemoClaw blocks an operation because it found an old timer, transition, policy snapshot, authority-bearing runtime-provider recovery artifact, or ambiguous recovery state, do not onboard or mutate any sandbox yet. These files can represent detached mutation authority that the current CLI deliberately does not interpret. A different requested sandbox name does not make onboarding safe.

A notice-only provider intent recorded before mutation authority was granted is preserved for review but does not by itself block lifecycle operations. The retirement notice prints each exact absolute notice-only path and labels it nonblocking. A notice-only path is not part of the quarantine inventory unless a later blocking error explicitly lists that same path.

Use the active state directory and exact blocking paths printed in the error as the complete quarantine inventory. A provider path can name a whole lifecycle transaction directory; treat the whole printed path as one unit.

1. Record the active state directory and every printed blocking path.
2. Reboot the host. Before continuing, ensure that no older NemoClaw binary restarts. Stopping selected processes without a reboot is not sufficient authority-stop proof.
3. Create trusted backup storage and a quarantine directory outside the printed active state directory. Back up each listed path, then move the original whole path into that outside quarantine. Do not delete, edit, or interpret any artifact, and do not move only selected files from a printed transaction directory.
4. Confirm that none of the printed paths remains in the active state directory. Only then retry the current-version rebuild or recreate flow. For recreation, use the manual transfer workflow to copy only trusted user data.

If you cannot complete the reboot, backup, or full quarantine, leave every artifact untouched. NemoClaw continues to block ordinary mutations while any listed path remains in active state.

The current CLI does not expose cross-sandbox recovery-backup restore. It deliberately does not interpret, resume, or delete ambiguous legacy recovery state.

Restart a Stopped Sandbox

If NemoClaw reports that a standard sandbox is stopped, ask OpenShell to restart that exact sandbox:

nemohermes <sandbox-name> start

This path preserves the sandbox workspace and leaves lifecycle ownership with OpenShell. start and recover resolve a sandbox from the local registry that owns it, even when another local OpenShell gateway is active. They reconcile a sandbox that OpenShell still reports as Stopped, including when its provider container is already running. Neither command directly restarts or unpauses the provider container. If the container is paused, follow the printed provider guidance instead.

Before destructive replacement, run nemohermes <sandbox-name> status. If the owning gateway reports the registered sandbox missing, NemoClaw leaves any provider container and registry entry untouched. Retry after the gateway reconnects. If the sandbox was intentionally deleted, preserve any separate backup and use nemohermes <sandbox-name> destroy --yes to retire the stale entry when the command can prove the OpenShell resource absent. Then onboard a clean replacement and use the manual transfer workflow to copy only reviewed, credential-free user data from an independently maintained backup. Rebuild cannot recover a workspace or live OpenShell policy that no longer exists.

The start command repairs the agent runtime and host-side port forwards. It returns success only after it authenticates the recovered agent runtime, OpenShell reports the sandbox ready, and host-side port forwards pass their checks. If a check fails, the command exits nonzero, identifies the failure, and prints recovery guidance before you retry start.

Recover the Agent Runtime

recover can start an existing stopped standard sandbox before it repairs the agent runtime. It submits that lifecycle mutation through OpenShell and waits for OpenShell to advance the sandbox out of the Stopped phase. If OpenShell cannot start the sandbox, recovery reports the failure; it does not fall back to direct provider-container lifecycle actions.

If nemohermes <name> status reports Phase: Stopped after an intentional stop, run nemohermes <name> start. If status reports sandbox_container_stopped or an unhealthy Hermes gateway, run the recover command instead of opening a shell. For a missing sandbox, follow the replacement procedure under Restart a Stopped Sandbox.

nemohermes <sandbox-name> recover

The command verifies the native gateway and re-establishes the dashboard port forward. If the gateway is stopped, recover reports it and does not relaunch it. Run gateway restart to request a native restart. If the host forward is already active, recovery accepts it only after OpenShell ownership is reconciled and the local endpoint is reachable. If a listener that NemoClaw cannot attribute to the sandbox’s OpenShell forward holds the port, recover reports it and leaves it running. It then exits nonzero and does not restore the forward. Legacy SSH forward records do not establish ownership. Stop the owning OpenShell gateway or service to release the listener before retrying recovery.

The nemoclaw-acp adapter uses only the exact OpenShell gateway recorded for its managed Hermes sandbox. It can select and, when required, start only that exact gateway when it is missing, unhealthy, or unreachable, or when a different gateway is connected. A conflicting or ambiguous gateway identity, authentication, schema, timeout, or other observation failure stops the adapter before gateway startup or session creation.

Before it verifies the gateway, recover checks for a NemoClaw cron restore gate or release recovery record left by an interrupted rebuild. The gate continues to block new Hermes turns and cron dispatch across gateway and sandbox restarts. If release rollback could not restore the gate, recover uses the root-owned recovery record to reacquire it before validation can resume dispatch. After gateway verification, recover waits for active agent work to finish and validates the restored cron jobs and scripts. It clears NemoClaw-owned gate and release recovery state only after validation succeeds. If no independent operator drain exists, successful recovery prints Hermes cron dispatch resumed after restored jobs and scripts were validated. If an operator drain exists, recovery prints Hermes cron restore gate cleared; the independent operator drain remains active. The command does not own or clear the Hermes operator drain, so new Hermes turns and cron dispatch remain blocked while that drain is active. If gate reacquisition or cron validation fails, recover exits nonzero and retains the recovery state for another attempt.

Use gateway restart when you intentionally need a supported Hermes gateway to reload runtime configuration or plugins.

nemohermes <sandbox-name> gateway restart

The restart command invokes Hermes’ native lifecycle command through the selected OpenShell sandbox. If that command closes the OpenShell exec relay before it returns status, NemoClaw waits for the sandbox control plane to become ready again. NemoClaw then verifies gateway health and checks or recovers host-side dashboard, messaging, and agent forwards.

When the gateway exits cleanly or with exit status 79, the supervisor waits up to 120 seconds for the authenticated gated recovery request. If the request does not arrive, the supervisor exits nonzero and leaves the gateway stopped. Follow the printed recovery guidance by running nemohermes <sandbox-name> stop, then nemohermes <sandbox-name> start.

For Hermes, the entrypoint supervisor owns the gateway, dashboard process, internal API relay, dashboard relay, and gateway log stream. The nonroot managed supervisor repairs those processes continuously and stops an alive but deaf gateway after four consecutive failed health checks. A fifth status-75 service-managed restart request within 60 seconds starts a cooldown. The supervisor waits until the rolling window permits another restart, then relaunches the gateway automatically. If the requests recur, inspect the gateway logs and correct the action or configuration that requests each restart. Rebuild only if the sandbox still cannot start.

The host does not start the in-sandbox processes independently. Refer to nemohermes <name> recover and nemohermes <name> gateway restart for details.

Recovery repairs supported agent processes and host forwards inside the registered sandbox. When the sandbox itself is stopped, start submits that lifecycle mutation to OpenShell; recovery does not take independent ownership of the provider container. If the native supervisor remains absent after bounded recovery, NemoClaw leaves the sandbox unchanged and directs you to rebuild or re-onboard.

For the lifecycle trust boundary and fail-closed conditions, refer to Understand Gateway Lifecycle Control. If recovery cannot verify a sandbox that needs current credentials or native lifecycle support, rebuild it.

Understand Launch Readiness Leases

A successful complete preflight for nemohermes launch <sandbox-name> can publish a credential-free launch-readiness lease on Linux. Linux infrastructure can publish the same evidence with nemohermes <sandbox-name> connect --probe-only. The lease has a fixed 24-hour lifetime that repeated launches do not extend. Leaving the agent with /exit does not revoke it, and users do not refresh it manually.

During the lease, launch still verifies the owning OpenShell gateway, exact live sandbox identity, registry and agent configuration, effective policy, inference route, required forwards, and semantic runtime health.

Every configured route must serve a valid response to a bounded request for the recorded model before NemoClaw accepts or publishes launch readiness. Shared-route providers use inference.local. Their models probe must return HTTP 2xx, except that openrouter-api can return HTTP 404 for GET /v1/models when the bounded model request succeeds. NVIDIA Endpoints verifies its sandbox-attached provider at integrate.api.nvidia.com and runs the bounded model request without the shared-route models probe. A failed required probe or model request rejects launch readiness. This check is stricter than the HTTP 200–499 reachability diagnostic used by ordinary connect. Hermes and LangChain Deep Agents Code retain their existing session setup on the lease-accepted path. When those checks pass, it can skip duplicate recovery, readiness polling, and inference-route repair. The lease is not a health guarantee or repair authority.

For missing, unsafe, malformed, expired, mismatched, changed, or unhealthy evidence, NemoClaw fences any prior acceptable evidence before it runs the complete preflight. Ordinary launch continues only when NemoClaw proves that no old authority or evidence can exist, or durably rotates the runtime epoch. If an old epoch might exist and cannot be durably rotated, launch and connect --probe-only stop before complete preflight or recovery. Their redacted guidance asks you to repair the current user’s secure OS runtime authority and NemoClaw state permissions, then retry. If NemoClaw securely proves that both the authority and receipt are absent but cannot create new authority, ordinary launch can run the complete preflight without optimization; on Linux, connect --probe-only exits nonzero because it could not publish evidence. If that preflight succeeds before the lease expires, replacement evidence keeps the original start and expiry time. After expiry, a successful complete preflight starts a new 24-hour lease only when publication succeeds.

Before the first mutation in the complete preflight, the producer revalidates its sandbox-global runtime epoch under the sandbox lifecycle lock followed by the owning gateway lock. It holds both locks through all mutations in the complete preflight, final state capture, and publication. A stale producer makes no changes and re-inspects the newer lease.

If unsafe or malformed authority history makes the prior lease timeline untrustworthy, NemoClaw durably invalidates the old epoch and starts one conservative 24-hour quarantine. Publication remains disabled until both wall time and monotonic uptime span the full quarantine. Repeated attempts do not extend it. After it elapses, the next successful complete preflight can publish a new fixed 24-hour lease.

Lease acceptance and publication are currently Linux-only and require a secure, independently writable OS per-user runtime authority under /run/user/<numeric-uid>. It never uses caller-provided environment variables to select this authority.

On macOS, launch runs the complete preflight every time and does not publish a launch-readiness lease. connect --probe-only also runs the complete preflight, including recovery and probes. After a successful probe and recovery, it prints a note that launch-readiness evidence is unavailable on this platform and exits zero. On Linux, unsafe launch-readiness diagnostics can report the affected path, owner UID, permissions, a bounded error code, and repair guidance. They exclude receipt contents, environment values, and raw OS error messages.

Infrastructure must run connect --probe-only as the same final numeric user that later runs launch. Run it after the final durable home and state volume is mounted and after policy and network provisioning is complete. On completion, connect --probe-only writes one credential-free Probe timing: line with elapsed milliseconds for readiness, authority, lifecycle, gateway, processes, forward, inference, pairing, and publication stages. The line also reports the lifecycle and forward actions, the result, and the failed stage when the probe fails. Timing output is diagnostic only and does not change probe success or failure. NemoClaw rejects evidence after a bound sandbox, configuration, policy, or network identity changes. Deployment ordering remains responsible for external changes that OpenShell and NemoClaw cannot observe. Refer to the probe timing reference for observation counts and readiness decisions.

Host OpenShell Gateway Versus In-Sandbox Agent Recovery

recover and start repair the in-sandbox agent gateway and the host-side port forwards for one named sandbox. connect --probe-only waits for that sandbox to become ready, rechecks it on its recorded gateway, and then verifies or repairs the same sandbox-scoped processes and forwards. These commands do not restart, replace, or reap the shared host OpenShell gateway process. If the host gateway RPC returns an error while these sandbox-scoped commands run, they surface the error with explicit next-step guidance and exit rather than swapping the shared gateway out from under other sandboxes.

The OpenShell CLI has no command that starts a gateway, and openshell status only reports the gateway state. If NemoClaw starts the gateway on your host, run nemohermes onboard again to repair the host gateway itself. If a deployment outside NemoClaw owns the gateway process, start the gateway with that deployment, then run openshell gateway select <gateway>. NemoClaw prints the applicable recovery guidance when a sandbox-scoped command reports that the host gateway is down. Other workflows, including onboarding, rebuild, and doctor --fix, can explicitly recover the named host gateway when their operation requires it. nemohermes <name> gateway restart instead restarts only the supported agent gateway inside the named sandbox.

Rebuild While Preserving 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

On WSL with Docker Desktop, a generated replacement image build uses a temporary credential-free Docker configuration when the configured Docker Desktop credential helper is unavailable. NemoClaw removes the temporary configuration after the build and does not modify your Docker configuration. An explicit custom Dockerfile continues to use your configured Docker credentials because its base image or build steps might require a private registry. If that custom rebuild cannot reach the credential helper, restore the Docker Desktop session or credential-helper access before retrying.

Generated-image rebuilds use the base image selected during preflight, even when the source sandbox records an older base-image hint. Custom Dockerfile rebuilds use the recorded Dockerfile source.

A sandbox created with --from-image rebuilds from its recorded digest instead. Before backup or deletion, NemoClaw makes that digest available in its selected Docker or rootless Podman runtime and validates its platform, runtime metadata, tool disclosure mode, and immutable local content identity. If a pull or validation fails, rebuild keeps the existing sandbox and stops before replacement.

If replacement onboarding returns a nonzero status, rebuild stops before post-create state restoration and preserves the backup and registry recovery state. It does not report a successful rebuild.

When NemoClaw can identify the exact stopped Docker container and prove its immutable runtime authority, rebuild captures the complete native root through the Docker provider without starting or executing inside the source. This recovery path supports stopped OpenClaw and Deep Agents Code sandboxes.

When that provider-owned capture is not available, rebuild asks OpenShell to start the exact stopped sandbox for the duration of the pre-recreate state backup and asks OpenShell to return it to Stopped afterward, the same lifecycle path nemohermes backup-all uses. If OpenShell cannot start the sandbox, or the retried backup still fails, rebuild aborts without recreating the sandbox; it reports an incomplete-backup notice only when a partial backup was retained. If the backup succeeds but OpenShell cannot return the sandbox to Stopped, rebuild also aborts and reports the failed transition. If neither path can establish stopped-source authority, repair the OpenShell lifecycle state or recover the data manually before retrying; NemoClaw does not fall back to a selective directory copy.

If OpenShell still reports the sandbox in Phase: Error but its Docker-driver container is missing, rebuild cannot back up its live workspace and stops before replacement. Recover the workspace from an independently maintained backup before creating a clean replacement.

For a legacy Hermes sandbox with no base-image hint or NEMOCLAW_HERMES_SANDBOX_BASE_IMAGE_REF override, rebuild requires the release-pinned immutable Hermes base image. Remote overrides must use the official repository and resolve to a trusted immutable digest. During rebuild, NemoClaw accepts a caller-supplied local alias only when Docker proves that the alias and the tracked official image have the same image ID, operating system, architecture, and official repository digest; other local aliases are rejected. On Linux, accepted images must pass the OpenShell ABI check. On every platform, they must pass the required MCP and ACP runtime and immutable security package inventory checks described in the NemoClaw CLI Commands Reference. If NemoClaw cannot resolve and validate that image, rebuild stops before it changes the sandbox or its registry.

When the target manifest declares an agent version, NemoClaw runs a fresh live version probe after state restoration. It records the replacement version and reports success only when the observed version matches the rebuild target. An unavailable or different version ends the rebuild with a nonzero status instead of recording the target version as observed.

Resolve Rebuild Preflight Stops

Before it backs up or deletes the existing sandbox, rebuild validates the recorded sandbox, gateway, inference route, policy, MCP, agent, and operation-lock state. When one of these checks fails, NemoClaw prints Rebuild preflight failed, explains how to recover, and ends with Aborting rebuild. At this boundary, the existing sandbox is unchanged and no sandbox data has been removed.

For a remote inference provider other than Hermes Provider, preflight checks the selected credential’s non-secret expiration metadata from OpenShell. For these providers, a provider that no longer exposes the recorded credential key, an expired credential, or expiration metadata that NemoClaw cannot verify stops rebuild before backup or deletion, including with --force. A provider that exposes the recorded credential key without an expiration entry is treated as non-expiring. That credential or one with a future expiration continues through the remaining preflight checks. Hermes Provider uses its separate authentication and credential-binding checks; this expiration-metadata guard does not apply to it.

For remote providers other than Hermes Provider and Amazon Bedrock, preflight validates a nonempty API key supplied through the host environment. NemoClaw checks that key against the provider endpoint before replacement-image preparation or backup. It validates the key again immediately before sandbox deletion. When validation fails, rebuild stops without deleting the existing sandbox, including with --force. A valid credential stored in OpenShell does not bypass validation of a supplied host key.

Use the recovery guidance that matches the reported check:

• Verify the sandbox name when its registry entry is missing.

• Follow the printed OpenShell gateway recovery steps when the gateway schema is incompatible.

• Correct the exported API key when rebuild reports the host inference credential could not be validated. To reuse a credential already stored in OpenShell, unset its host environment variable instead. For NVIDIA Endpoints, this variable is NVIDIA_INFERENCE_API_KEY. Confirm that the provider endpoint is reachable. Then retry rebuild.

• Refresh the named OpenShell credential or rerun nemohermes onboard when rebuild reports an expired provider credential.

• Re-register the provider or rerun nemohermes onboard with the correct credential when the provider no longer exposes the recorded credential key, then retry rebuild.

• Restore gateway connectivity and authentication when rebuild cannot verify the recorded provider.

• Restore access to the current OpenShell policy when rebuild reports that the live policy cannot be read, then rerun rebuild. NemoClaw does not reconstruct policy from registry state.

• Replace literal policy credentials with supported OpenShell credential bindings or resolver placeholders when rebuild refuses the policy handoff. NemoClaw stops before it creates the handoff or changes sandbox resources.

• Resolve an incomplete MCP destroy transaction before retrying.

• Back up the sandbox state and recreate it with nemohermes onboard when the record contains multiple agents. Transactional multi-agent rebuild is not supported.

• Wait for another onboarding or rebuild operation to finish before retrying. If verified stale-lock cleanup is still in progress, wait briefly and rerun the command. Do not delete the lock manually.

• Set the live OpenShell inference route to the sandbox’s recorded provider and model when rebuild reports route drift.

  Prepared backup recovery reuses its digest-verified pre-upgrade policy handoff at the deletion boundary. It does not recapture the live policy, and it stops before deletion if the handoff is missing or changed.

A gateway that reports no live inference route does not stop the rebuild. Replacement onboarding configures and verifies the recorded route before it recreates the sandbox.

The rebuild command transfers the complete Hermes native home, the complete current OpenShell policy, and managed MCP configuration while recreating the container. The opaque native-home transfer includes configuration values written through nemohermes <name> config set; NemoClaw does not select or merge individual configuration dotpaths. A capture failure stops before deletion; a restore or verification failure exits nonzero and preserves recovery state. For that one replacement create, NemoClaw adds baseline fields required by the current replacement image when they are absent from the live policy. Existing values, network keys, and same-name live network entries win, so host changes are not overwritten. NemoClaw does not save a desired-policy copy or enforce that handoff after OpenShell creates the sandbox. It reuses a messaging provider only when its type, credential keys, and checked-in OpenShell profile contract match the recorded channel binding. A stopped channel remains inactive and contributes no token upsert, rendered runtime configuration, channel startup effect, or inactive built-in messaging preset. Custom and host-edited policy entries are preserved as part of that one OpenShell policy handoff, not by a separate replay system. A policy-required provider attachment is the narrow exception: when a preserved custom policy still credential-binds stopped Hermes Discord, rebuild attaches its exact validated static provider without starting Discord. If that required provider is missing or incompatible, restore or re-add the channel credentials, then rerun the rebuild. A rebuild creates a new sandbox home and a new Hermes API bearer token. After the rebuild succeeds, retrieve the replacement token before reconnecting API clients:

nemohermes <sandbox-name> gateway-token --quiet

Before post-restore repairs, NemoClaw verifies that the recreated sandbox still identifies as Hermes and exits nonzero if its identity does not match the rebuild target. After state restore, NemoClaw restarts the Hermes gateway so it reads the restored durable state, then restores managed MCP configuration through the normal lifecycle. MCP restoration performs an acknowledged gateway reload, so NemoClaw finishes by verifying the final running gateway and its managed MCP state without replacing that verified process again. The gateway starts during recreation and reads its durable state before the restore replaces it, which is why the first post-restore restart must happen before managed MCP restoration. rebuild exits nonzero instead of reporting success when it cannot verify final gateway health or managed MCP state. Follow the printed recovery guidance. Run nemohermes <sandbox-name> gateway restart first to request a native gateway restart. After gateway health returns, run nemohermes <sandbox-name> recover only to reconcile host-side forwards or cron restore state. If gateway health does not return, run nemohermes <sandbox-name> stop, then nemohermes <sandbox-name> start. Run nemohermes <sandbox-name> rebuild only if the sandbox still cannot start. Run nemohermes <sandbox-name> mcp restart for incomplete managed MCP restoration.

When the rebuild backup contains active Hermes cron jobs that reference scripts, NemoClaw validates those script references before it deletes the existing sandbox. The check covers the default profile and named profiles. Each referenced script must exist, be readable, be a regular file, and remain inside its profile’s scripts directory. Disabled and paused jobs do not require their referenced scripts. If this validation fails, the rebuild keeps the existing sandbox and reports the preserved backup path.

After NemoClaw creates the replacement, it acquires an independent root-owned gate that blocks new Hermes turns and cron dispatch. The gate remains active across gateway and container restarts in the replacement sandbox. NemoClaw waits for active agent work to finish before restoring state. It validates the restored jobs and scripts before the gateway replacement. NemoClaw keeps dispatch blocked while it restarts and verifies that replacement. It records the replacement process identity around managed health verification. NemoClaw clears the gate only if that same live process completes the final cron validation. If an operator already drained the gateway, NemoClaw clears its gate and release recovery record while leaving the operator drain active.

If state restore, managed MCP restoration, gateway replacement, agent-version verification, or cron validation fails after gate acquisition, rebuild exits nonzero and preserves the backup. rebuild keeps the NemoClaw gate active after these failures unless release rollback cannot restore the drain marker. Failures before gate acquisition do not create a new gate.

If managed MCP restoration failed, correct the reported cause and run nemohermes <sandbox-name> mcp restart first. Then run nemohermes <sandbox-name> recover to repair the gateway, validate the restored cron tree, and clear NemoClaw-owned recovery state.

When NemoClaw is ready to reopen dispatch and no operator drain remains, its root-owned controller reschedules only enabled one-shot jobs that became due at or after the NemoClaw gate was acquired, have never run, and carry no dispatch or fire claim. It persists that update before removing the gate. If the update fails, rebuild or recovery exits nonzero and leaves the gate active.

Continue an Interrupted Replacement

Before rebuild deletes the existing sandbox, NemoClaw records a replacement journal in the active onboarding session. The journal binds the operation to the sandbox name, recorded OpenShell gateway, source identity, and replacement settings. It stores fingerprints instead of credential values or raw OpenShell sandbox IDs.

Rebuilding another sandbox can retain this session in .onboard-rebuild-<sandbox>.json under the selected NemoClaw state directory. Rerunning the affected sandbox’s rebuild restores its retained session automatically. For a non-default gateway port, these files reside under ~/.nemoclaw/gateways/<port>/. Resume or clear an unfinished ordinary onboarding session before retrying retained rebuild recovery. To discard that ordinary onboarding attempt and start over, run nemohermes onboard --fresh as described in Previous onboarding session failed.

If rebuild stops after recording the journal, rerun the command with the same replacement settings. The rerun takes one of these actions:

• It continues deletion when the live sandbox still has the journaled source identity.
• It continues creation when the recorded OpenShell gateway explicitly reports the source sandbox as absent.
• It accepts an existing replacement only after its live identity and sandbox registry generation match the journal and it completes or verifies the recorded final handoff.
• It starts a new replacement when the journaled replacement provably never took effect.

An older recovery marker can lack an MCP handoff, as can an interruption before NemoClaw records the handoff. NemoClaw reads MCP state again only when the source still exists and the matching journal remains in the planned or deleting phase. If either check fails, the rerun stops without another delete attempt.

NemoClaw treats a journaled replacement as void when the sandbox registry row and the live same-name sandbox report the same OpenShell identity on the journaled gateway, and that identity is not the journaled replacement. A registry row or a live sandbox on any other gateway leaves the journal in place, because that journal may still own an unregistered replacement on its own gateway. The rerun atomically replaces the void journal with a fresh journal against that live source, without leaving an unjournaled interval. It then reports Replaced the void replacement journal for '<name>'; its source sandbox is registered and live. A journal whose replacement never took therefore stops blocking rebuild for the rest of the session.

The journal binds the durable source registry row and normally does not resume after a command rewrites that row. For an older N1x Docker managed-vLLM journal, recovery can continue only while the row contains the matching active route reservation. Other changes to the fingerprinted source row remain fail-closed. Messaging channel state is exempt: channels add, channels stop, channels start, and channels remove rewrite the recorded messaging plan, and the journal ignores that field.

openshell gateway select <recorded-gateway>
openshell status
nemohermes <sandbox-name> destroy --yes

BACKUP=<printed-backup-path>
RECOVERY_DIR="$(mktemp -d "${TMPDIR:-/tmp}/nemoclaw-native-recovery.XXXXXX")"
chmod 700 "$RECOVERY_DIR"
EXPECTED_SHA256="$(node -e 'const m=require(process.argv[1]); process.stdout.write(m.nativeState.sha256)' "$BACKUP/rebuild-manifest.json")"
ACTUAL_SHA256="$(node -e 'const c=require("node:crypto"),f=require("node:fs"),h=c.createHash("sha256"),s=f.createReadStream(process.argv[1]); s.on("data",d=>h.update(d)); s.on("end",()=>process.stdout.write(h.digest("hex"))); s.on("error",e=>{console.error(e.message);process.exitCode=1})' "$BACKUP/native-home.tar")"
test "$ACTUAL_SHA256" = "$EXPECTED_SHA256"
tar --no-same-owner -xf "$BACKUP/native-home.tar" -C "$RECOVERY_DIR"
find "$RECOVERY_DIR" -mindepth 1 -maxdepth 3 -print

nemohermes <new-sandbox-name> upload "$RECOVERY_DIR/<relative-path>" "/sandbox/<destination>"

rm -rf -- "$RECOVERY_DIR"

nemohermes <failed-sandbox-name> rebuild --retire-recovery <transaction-id> --yes

A mount-free journal written before NemoClaw bound host-mount identity remains resumable. An older journal for a rebuild with one or more host mounts stops as incompatible, even when the visible mount settings are unchanged, because it cannot prove the original host source identity. Preserve the live sandbox, onboarding session, printed backup, exact error, and the sandbox name, gateway, and journal phase from the Journaled replacement diagnostic. Do not change the target settings, edit the session, or delete the same-name sandbox. Ask a NemoClaw maintainer to review that retained recovery state before taking another recovery action.

An accepted replacement is not deleted again.

A rerun that accepts a journaled Hermes replacement checks for any retained NemoClaw gate before it retires the replacement journal. When the gate exists, the rerun validates the restored cron tree and releases the gate first. If validation or gate release fails, NemoClaw preserves the accepted replacement, state backup, and replacement journal. New Hermes turns and cron dispatch remain blocked. Correct the reported restore problem, then run nemohermes <name> recover. After recovery succeeds, rerun rebuild with the same replacement settings so NemoClaw can retire the journal. The command reports Sandbox '<name>' already holds the replacement from the interrupted rebuild. and preserves the state backup path when one exists. Pass --verbose to include the replacement identifier, OpenShell gateway, and journal phase in rebuild diagnostics.

After the sandbox registry proves the journaled replacement identity and generation, NemoClaw removes an obsolete source image that it owns. It retains the image when the source is shared or the registered replacement reuses it. If image removal fails, NemoClaw keeps the accepted replacement and tells you to run nemohermes gc for cleanup.

NemoClaw fails closed when the selected gateway, replacement settings, durable source registry fields, or live source or target identity no longer matches the journal. The error names the sandbox and the mismatch that stopped recovery. Do not delete a same-name sandbox to bypass this check. Inspect the named OpenShell gateway and sandbox, correct the reported drift, and rerun the original command. Visible settings cannot correct the legacy host-mount journal case described above.

A same-name recreation started by nemohermes onboard uses the same replacement journal. If that recreation is interrupted after the Journaled replacement message, rerun the original onboarding command with the same target settings. The active replacement can continue without adding --resume. Use --resume for interrupted onboarding steps that occur before a replacement journal exists.

If the complete native home/workspace cannot be archived, NemoClaw reports the transfer failure and stops before deleting the original sandbox. This fail-closed behavior also applies to rebuild --force; NemoClaw never publishes a partial native-home archive as a restore source. NemoClaw removes failed native-state captures when cleanup succeeds instead of retaining them as incomplete recovery archives. If that cleanup also fails, NemoClaw reports and retains the incomplete backup path. Preserve that path while investigating the reported failure, or remove it only after the failure is resolved and you have confirmed that the original sandbox remains intact. Repair source access, free backup-disk space, or remove credential-bearing content identified by the error, then rerun the rebuild while the original sandbox remains intact.

Refer to nemohermes <name> rebuild for flag details.

Use the Canonical Configuration Workflows

• Use Switch Inference Providers to change a model or provider.

• Use Credential Rotation to reset or replace a stored provider credential.

• Use Customize the Network Policy to add or remove policy presets.

Related Topics

• Persist Sandbox State for the state-preservation contract.
• Troubleshooting for privileged control unavailable, stopped sandboxes, and failed rebuilds.