> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemoclaw/llms.txt. > For full documentation content, see https://docs.nvidia.com/nemoclaw/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemoclaw/_mcp/server. # Backup and Restore Workspace Files > How to back up and restore OpenClaw workspace files before destructive operations. Workspace and state files define your agent's personality, memory, user context, and durable runtime state. They persist across sandbox restarts but are **permanently deleted** when you destroy the sandbox. This guide covers snapshot commands, manual backup with CLI commands, and an automated script. ## When to Back Up * Before running `nemoclaw 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//`. 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. ```bash nemoclaw my-assistant snapshot create nemoclaw my-assistant snapshot list nemoclaw my-assistant snapshot restore ``` `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`: ```bash nemoclaw my-assistant snapshot create --name before-upgrade ``` To restore a specific snapshot instead of the latest, pass a version, name, or timestamp prefix: ```bash nemoclaw my-assistant snapshot restore v3 nemoclaw my-assistant snapshot restore before-upgrade nemoclaw my-assistant snapshot restore 2026-04-14T ``` To clone a snapshot into a different sandbox name, pass `--to `. If the destination sandbox already exists, NemoClaw refuses to overwrite it unless you pass `--force`: ```bash nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes ``` The `nemoclaw 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. For full details, see the [Commands reference](../reference/commands). ## Manual Backup Use `openshell sandbox download` to copy files from the sandbox to your host. ```bash 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/" ``` ## Manual Restore Use `openshell sandbox upload` to push files back into a sandbox. ```bash 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/ ``` ## Using the Backup Script The repository includes a convenience script at `scripts/backup-workspace.sh`. ### Backup ```console $ ./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) ``` ### Restore Restore from the most recent backup: ```bash ./scripts/backup-workspace.sh restore my-assistant ``` Restore from a specific timestamp: ```bash ./scripts/backup-workspace.sh restore my-assistant 20260320-120000 ``` ## Verifying a Backup List backed-up files to confirm completeness: ```console $ ls -la ~/.nemoclaw/backups/20260320-120000/ AGENTS.md IDENTITY.md MEMORY.md SOUL.md USER.md memory/ ``` ## 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](workspace-files#multi-agent-deployments). `nemoclaw 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` 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](https://github.com/NVIDIA/NemoClaw/issues/1260). ## Next Steps * [Workspace Files overview](workspace-files) to learn what each file does. * [Commands reference](../reference/commands)