Back Up and Restore Workspace Files — NVIDIA NemoClaw Developer Guide
Backup and Restore Workspace Files #
Workspace files define your agent’s personality, memory, and user context.
They persist across sandbox restarts but are permanently deleted when you run nemoclaw <name> destroy.
This guide covers snapshot commands, manual backup with CLI commands, and an automated script.
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>/.
$ nemoclaw my-assistant snapshot create
$ nemoclaw my-assistant snapshot list
$ nemoclaw my-assistant snapshot restore
Copy to clipboard
snapshot list prints a table of version, name, timestamp, and path. Versions (v1, v2, …, vN) are computed from the timestamp order, so vN is always the newest snapshot.
To tag a snapshot with a human-readable label, pass --name:
$ nemoclaw my-assistant snapshot create --name before-upgrade
Copy to clipboard
To restore a specific snapshot instead of the latest, pass a version, name, or timestamp prefix:
$ nemoclaw my-assistant snapshot restore v3
$ nemoclaw my-assistant snapshot restore before-upgrade
$ nemoclaw my-assistant snapshot restore 2026-04-14T
Copy to clipboard
The nemoclaw <name> rebuild command uses the same snapshot mechanism automatically.
Snapshot restore accepts symlinks that resolve to NemoClaw-managed sandbox data paths such as /sandbox/.openclaw-data/.
Symlinks that point outside the known sandbox data paths are still rejected during extraction.
For full details, see the Commands reference.
Manual Backup #
Use openshell sandbox download to copy files from the sandbox to your host.
$ SANDBOX=my-assistant
$ BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S)
$ mkdir -p "$BACKUP_DIR"
$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/SOUL.md "$BACKUP_DIR/"
$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/USER.md "$BACKUP_DIR/"
$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/IDENTITY.md "$BACKUP_DIR/"
$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/AGENTS.md "$BACKUP_DIR/"
$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/MEMORY.md "$BACKUP_DIR/"
$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/memory/ "$BACKUP_DIR/memory/"
Copy to clipboard
Manual Restore #
Use openshell sandbox upload to push files back into a sandbox.
$ SANDBOX=my-assistant
$ BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp
$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/.openclaw/workspace/
$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/USER.md" /sandbox/.openclaw/workspace/
$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/IDENTITY.md" /sandbox/.openclaw/workspace/
$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/AGENTS.md" /sandbox/.openclaw/workspace/
$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/MEMORY.md" /sandbox/.openclaw/workspace/
$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/memory/" /sandbox/.openclaw/workspace/memory/
Copy to clipboard
Using the Backup Script #
The repository includes a convenience script at scripts/backup-workspace.sh.
Backup #
$ ./scripts/backup-workspace.sh backup my-assistant
Backing up workspace from sandbox 'my-assistant'...
Backup saved to /home/user/.nemoclaw/backups/20260320-120000/ (6 items)
Copy to clipboard
Restore #
Restore from the most recent backup:
$ ./scripts/backup-workspace.sh restore my-assistant
Copy to clipboard
Restore from a specific timestamp:
$ ./scripts/backup-workspace.sh restore my-assistant 20260320-120000
Copy to clipboard
Verifying a Backup #
List backed-up files to confirm completeness:
$ ls -la ~/.nemoclaw/backups/20260320-120000/
AGENTS.md
IDENTITY.md
MEMORY.md
SOUL.md
USER.md
memory/
Copy to clipboard
Multi-Agent Deployments #
When OpenClaw is configured with multiple named agents, each agent has its own
workspace directory (workspace-main/, workspace-support/, workspace-ops/,
and so on — see 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/. snapshot restore re-applies the full
per-agent set. No manual per-workspace backup pattern is needed.
The sandbox entrypoint ensures every per-agent workspace is backed by the
persistent .openclaw-data/ tree (via a symlink from
.openclaw/workspace-<name>/) 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; changes in one don’t propagate. Operators that
need this either copy the shared files explicitly to each workspace after
editing, or maintain a host-side sync layer. Tracking shared-file tooling
(shared mount, workspaces list command) in
#1260.
Next Steps #
-
Workspace Files overview to learn what each file does