Create and Restore Snapshots
NemoClaw snapshots preserve manifest-defined sandbox state before destructive or state-changing operations. They are the preferred backup and restore path.
When to Create a Snapshot
- Before running
nemohermes <name> destroy. - Before major NemoClaw version upgrades.
- Periodically, if you have invested time customizing your agent or paired messaging channels.
Understand Snapshot Contents
Snapshots capture the manifest-declared snapshot state directories and store them in ~/.nemoclaw/rebuild-backups/<name>/. Agent manifests can also declare durable top-level state files. Treat snapshot directories as private local data.
Before NemoClaw marks a snapshot complete, it strips recognized credential values from copied JSON, YAML, and .env files. It preserves recognized dependency lockfiles byte for byte when they contain only dependency metadata. This behavior includes installed npm .package-lock.json files. It omits a recognized lockfile when the file is invalid or contains any of these values:
- A credential field.
- A provider-shaped secret outside a dependency URL.
- URL user information.
- A credential-bearing query parameter.
Dependency names in lockfile maps do not count as credential fields. NemoClaw also preserves valid, credential-free node_modules/**/package.json manifests byte for byte because dependency names can match credential field names. It omits an installed package manifest when the file contains invalid JSON, a credential or authentication field, a provider-shaped secret, or a credential-bearing URL. It continues to sanitize configuration and .env files inside installed dependency trees. It preserves OpenShell credential placeholders so rebuild can reattach the host-side provider. If NemoClaw cannot sanitize a copied configuration or environment file, it omits that file from the snapshot. If it cannot remove the unsafe file, snapshot creation returns an error. It deletes the incomplete backup when cleanup succeeds and reports when the backup remains. This sanitization uses an isolated python3 helper on POSIX hosts to keep reads, replacements, and removals anchored to opened directory descriptors. If a copied file or parent directory changes identity during the operation, snapshot creation fails closed instead of following the changed path.
A previous release sanitized dependency lockfiles and installed package manifests.
It replaced package versions in the Hermes WhatsApp bridge with the [STRIPPED_BY_MIGRATION] marker and left a tree that npm install rejects.
A sandbox rebuilt on such a release reports whatsapp failed to connect on every gateway start.
Destroy that sandbox with nemohermes <sandbox> destroy --yes.
Then onboard again.
A rebuild does not repair the damaged tree, because each rebuild restores the tree it backed up.
Hermes snapshots include SOUL.md, the Web Dashboard profile under .hermes/profiles/dashboard-home/, the SQLite database behind .hermes/state.db, and the default kanban board in .hermes/kanban.db.
On the first startup after this layout change, NemoClaw moves an existing .hermes/dashboard-home/ directory when the canonical profile is absent or empty and the legacy path is not a symlink.
Startup sets the canonical dashboard profile directory to mode 0700, whether it migrates legacy state or reuses an existing destination.
During normal startup, NemoClaw refuses unsafe paths and does not merge two populated profile directories.
The default-profile snapshot also includes cron execution history in .hermes/runtime/cron-executions.db and Discord replay state in .hermes/gateway/discord_message_recovery.db.
NemoClaw captures cron job definitions from .hermes/cron and user-authored cron scripts from .hermes/scripts as directory state.
NemoClaw uses SQLite’s online backup API and restores these databases through SQLite instead of copying live raw database files.
After it replaces a database, NemoClaw opens a write transaction against the result and fails the restore when the database cannot be written.
Named-profile cron and Discord databases under .hermes/profiles/<name>/ use raw directory capture and can be inconsistent if a write overlaps the snapshot.
Kanban backup is limited to the backward-compatible default board in kanban.db. Named boards, attachments, worker logs, scratch workspaces under .hermes/kanban/, and external directory or worktree targets are not included; back up that state separately.
The dashboard profile includes MEMORY.md and USER.md. The Hermes state database can contain session metadata and message history needed for a faithful restore.
Snapshot clone reads the source sandbox policy from OpenShell and passes it to destination creation through a private temporary handoff. If the policy contains a literal credential value, NemoClaw stops before it writes the handoff or changes the destination. Replace literal credentials with supported OpenShell credential bindings or resolver placeholders, then rerun the restore. The snapshot manifest and registry contain no custom-preset copy, baseline-exclusion record, or desired-policy replay state.
The target sandbox’s current agent manifest remains authoritative for directory and state-file restore behavior. NemoClaw rejects the restore when the snapshot’s agent, config directory, any snapshot directory, state-file path, or state-file strategy conflicts with that manifest. Restore limits directory cleanup to state directories authorized by both the snapshot and the current manifest. It preserves target-only directories and directories whose backup failed.
For managed images, NemoClaw applies the current manifest’s managed config merge rules by default and does not fall back to whole-file replacement. For Deep Agents targets, whole-file config replacement is limited to sandboxes created from a custom Dockerfile.
Create and List Snapshots
snapshot list prints a table of version, name, timestamp, and path. NemoClaw computes versions (v1, v2, through vN) from timestamp order, so vN is always the newest snapshot.
Snapshot creation and restore use the per-sandbox mutation lock so another host operation cannot change the same sandbox state concurrently.
Tag a snapshot with a human-readable label:
When a directory or state file cannot be captured, snapshot create reports the failed items, attempts to remove the incomplete snapshot, and exits nonzero.
When cleanup succeeds, the command removes the incomplete snapshot.
When cleanup fails, the command reports the retained snapshot path.
The retained incomplete snapshot remains excluded from snapshot list and restore selection.
The retained incomplete snapshot may contain unsanitized credentials.
Do not restore, copy, share, or edit it.
Repair access to the original sandbox state, then rerun snapshot create.
Remove the retained directory only after you verify that the original sandbox or a complete snapshot contains every required state item.
For a legacy snapshot whose manifest lacks a completion marker, NemoClaw excludes it from snapshot list and restore selection when any manifest-declared state file is absent from the snapshot directory.
The state-file-presence check does not exclude an otherwise complete legacy snapshot when every declared state file is present or when its manifest declares no state files.
Restore a Snapshot
Restore the latest snapshot:
Pass an exact version, name, or timestamp to select a specific snapshot. Use the exact timestamp from snapshot list; a timestamp prefix does not select a snapshot.
In-place restore does not mutate the OpenShell policy. Cross-sandbox clone reads the source live policy and uses it only as the destination creation handoff.
A running Hermes gateway keeps serving its pre-restore state databases until it reopens them.
After a restore that includes Hermes state databases, the CLI prints a reminder to restart the gateway.
Run nemohermes <name> gateway restart to make the gateway open the restored databases.
--to is not available for a snapshot of a sandbox that uses a NemoClaw-managed image.
NemoClaw reports that the restore is not available and stops before it creates, deletes, or changes the destination sandbox.
Restore that snapshot into its source sandbox without --to.
To clone a snapshot into a different sandbox name, pass --to <name>. If the destination sandbox already exists, NemoClaw refuses to overwrite it unless you pass --force:
Cross-sandbox restore from a stopped source is available for Docker- and VM-driver sandboxes. For a stopped source, its registry entry must record both the sandbox image and a complete inference route; NemoClaw creates the destination from the recorded image. NemoClaw stops before creating or replacing the destination when either record is missing, and directs you to run nemohermes onboard when no image is recorded. For a Kubernetes-driver source, the pod image must remain resolvable through its gateway.
For a new destination, NemoClaw waits for the owning gateway to report the sandbox as Ready with a valid live identity. It checks that identity again immediately before registration. NemoClaw assigns the destination a new lifecycle generation instead of copying the source sandbox’s generation.
If NemoClaw cannot securely remove the temporary clone policy after destination creation, it leaves the destination as a pending clone and does not restore snapshot state. Inspect and remove the task-owned file identified by the error, then rerun the same restore without --force so NemoClaw can reconcile the destination without deleting or recreating it.
If the destination is not Ready with the same valid identity, the restore exits nonzero before registration or state restore. The OpenShell sandbox remains created but unregistered, so --force cannot select it for deletion. Run the exact owner-scoped deletion command printed by the failure:
After OpenShell deletes the destination, rerun the original snapshot restore --to command.
For dashboard-enabled agents, NemoClaw allocates the destination sandbox its own dashboard port instead of reusing the source port. If no port is available, restore stops before deleting an existing --force destination.
NemoClaw also allocates the destination sandbox its own OpenAI-compatible API port from 8642
through 8652 instead of reusing the source port. If no port in that range is free, restore stops
before deleting an existing --force destination. Run openshell forward list to read the
destination sandbox’s API port.
The force-overwrite path revalidates the exact destination before deletion and creates the same-name replacement only after deletion succeeds.
Restore Agent Configuration Safely
The nemohermes <name> rebuild command uses the same snapshot mechanism automatically. NemoClaw rejects unsafe symlinks and special files inside sandbox state during backup creation. It records multiply-linked regular files and archives each path as a separate regular file.
Credential-bearing Hermes files such as auth.json are intentionally excluded from snapshots.
NemoClaw-regenerated Hermes config files, including config.yaml and .env, are also excluded.
NemoClaw recreates model, provider, and messaging credentials from host-side onboarding and OpenShell provider state during rebuild.
If a Hermes rebuild cannot validate or release its NemoClaw cron restore gate, NemoClaw preserves the state backup. If the rebuild already accepted the replacement sandbox, it also preserves the replacement journal. New Hermes turns and cron dispatch remain blocked while the gate exists.
Do not manually remove the root-owned cron restore marker.
Removing it bypasses validation of the restored cron jobs and scripts.
Correct the reported restore problem, then run nemohermes <sandbox-name> recover.
Recovery validates the restored cron tree before it clears the NemoClaw gate.
If an independent Hermes operator drain exists, recovery leaves it active.
After recovery succeeds, rerun rebuild with the same replacement settings so NemoClaw can retire the replacement journal.
After a rebuild restores dashboard-home or profiles, NemoClaw reruns the dashboard state migration before it reports the restore as complete. During rebuild restore, NemoClaw moves disjoint top-level entries from the legacy dashboard directory without replacing entries in the canonical profile. If an entry collides or migration otherwise fails, NemoClaw marks the restore incomplete instead of reporting success.
Back Up Every Registered Sandbox
Run nemohermes backup-all before broad maintenance such as nemohermes update, nemohermes upgrade-sandboxes, or an OpenShell gateway migration.
backup-all walks the sandboxes registered on the host, creates a snapshot for each eligible running or temporarily started sandbox, and stores the snapshot bundles under ~/.nemoclaw/rebuild-backups/<name>/. If a registered docker-driver sandbox’s container is stopped, backup-all starts the container for the duration of the backup and returns it to its stopped state afterward. If the container cannot be returned to the stopped state, the backup run fails and reports that the container was left running. If a sandbox is not running and its container cannot be started this way, start the sandbox or its container and rerun nemohermes backup-all.
For each eligible sandbox, backup-all holds one lifecycle transaction through the complete backup.
Within that transaction, it starts a stopped container when required, copies sandbox state, and returns any container it started to the stopped state.
A backup failure marks that sandbox as failed, and backup-all continues with the next sandbox.
When a backup fails, NemoClaw identifies the affected state item and reports permission denied, tar read error, or absent after extraction when available. Use nemohermes <name> snapshot list and nemohermes <name> snapshot restore to inspect or restore one sandbox’s bundles later.
Related Topics
- Understand Sandbox State for the files each agent persists.
- Transfer State Manually when you need specific files instead of a managed snapshot.
- Recover and Rebuild Sandboxes for automatic snapshot-backed rebuilds.
- Commands reference for snapshot and backup flags.