Backup and Restore Workspace Files
Workspace and state files define your agent’s personality, memory, user context, and durable runtime state. They persist across sandbox restarts, but destroying the sandbox permanently deletes them.
This guide covers snapshot commands, all-sandbox backups, and manual backup with CLI commands.
When to Back Up
- Before running
nemoclaw <name> destroy - Before major NemoClaw version upgrades
- Periodically, if you’ve invested time customizing your agent
Snapshot Commands
The fastest way to back up and restore sandbox state is with the built-in snapshot commands.
Snapshots capture all workspace state directories defined in the agent manifest and store them in ~/.nemoclaw/rebuild-backups/<name>/.
Agent manifests can also declare durable top-level state files.
For Hermes, snapshots include SOUL.md and the SQLite database behind .hermes/state.db using SQLite’s online backup API, then restore that database through SQLite instead of copying a live raw database file.
Treat snapshot directories as private local data: the Hermes database can contain session metadata and message history needed for a faithful restore.
Snapshots also preserve sandbox registry metadata that affects rebuild behavior, including custom policy presets applied with policy-add --from-file or policy-add --from-dir.
When you restore a snapshot, NemoClaw replays those recorded custom presets with their stored YAML content, so you do not need the original preset files on disk for the restored sandbox to keep the same policy state.
snapshot list prints a table of version, name, timestamp, and path.
NemoClaw computes versions (v1, v2, …, vN) from timestamp order, so vN is always the newest snapshot.
To tag a snapshot with a human-readable label, pass --name:
To restore a specific snapshot instead of the latest, pass a version, name, or timestamp prefix:
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:
The nemoclaw <name> rebuild command uses the same snapshot mechanism automatically.
Snapshot restore performs a targeted repair for legacy .openclaw-data symlinks that older images created.
NemoClaw rejects unsafe symlinks and hard links inside sandbox state during backup creation before they can enter a snapshot.
Snapshots also preserve user-owned openclaw.json settings.
During rebuild or restore, NemoClaw merges those restored settings with the freshly generated runtime config so current provider placeholders, messaging enablement, and gateway state win over stale snapshot values.
If the restored config cannot be parsed or applied safely, NemoClaw stops the restore instead of replacing the generated config with an unsafe fallback.
For full details, see the Commands reference.
Manual Backup
Use openshell sandbox download to copy files from the sandbox to your host.
Manual Restore
Use openshell sandbox upload to push files back into a sandbox.
Back Up All Running Sandboxes
To back up every registered, running sandbox in one step, run nemoclaw backup-all.
This is the recommended host-installed command before broad maintenance such as nemoclaw update, nemoclaw upgrade-sandboxes, or an OpenShell gateway migration.
backup-all walks the sandboxes registered on the host, creates a snapshot for each running sandbox, and stores the snapshot bundles under ~/.nemoclaw/rebuild-backups/<name>/.
Use nemoclaw <name> snapshot list and nemoclaw <name> snapshot restore to inspect or restore one sandbox’s bundles later.
Using the Backup Script
Source-tree helper script
The scripts/backup-workspace.sh helper exists only in the NemoClaw source repository for engineering workflows.
It is not installed by the standard curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash installer, so host installs should use nemoclaw backup-all or the snapshot commands above.
Backup
Expected output:
Restore
Restore from the most recent backup:
Restore from a specific timestamp:
Verifying a Backup
List backed-up files to confirm completeness:
Expected output:
Multi-Agent Deployments
When you configure OpenClaw with multiple named agents, each agent has its own workspace directory (workspace-main/, workspace-support/, workspace-ops/, and so on).
Refer to Multi-Agent Deployments.
nemoclaw <name> snapshot create automatically discovers every workspace-*/ directory under the sandbox state tree and includes it in the snapshot bundle alongside the default workspace/.
nemoclaw <name> snapshot restore reapplies the full per-agent set.
You do not need a manual per-workspace backup pattern.
The sandbox entrypoint ensures every per-agent workspace lives directly under the persistent .openclaw/ tree, so state also survives openshell sandbox restart.
Shared files across agents
Files that operators typically want consistent across every per-agent workspace
(AGENTS.md, shared skills, common templates) are not synced automatically.
Each workspace is independent, and changes in one do not propagate.
Operators that need this either copy the shared files explicitly to each workspace after editing or maintain a host-side sync layer.
NVIDIA tracks shared-file tooling (shared mount, workspaces list command) in #1260.
Next Steps
- Workspace Files overview to learn what each file does.
- Commands reference