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

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

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

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/"

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/

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)

Restore#

Restore from the most recent backup:

$ ./scripts/backup-workspace.sh restore my-assistant

Restore from a specific timestamp:

$ ./scripts/backup-workspace.sh restore my-assistant 20260320-120000

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/

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#