Manage Sandboxes

Backup and Restore Workspace Files

View as Markdown

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 nemohermes <name> destroy.
  • Before major NemoClaw version upgrades.
  • Periodically, if you have invested time customizing your agent or paired messaging channels.

Snapshot Commands

Use the built-in snapshot commands for the fastest backup and restore path. 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.

$nemohermes my-assistant snapshot create
$nemohermes my-assistant snapshot list
$nemohermes 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. snapshot create requires shields to be down. Snapshot creation and restore share the per-sandbox transition lock with the shields auto-restore timer. If a timed shields-down window expires during snapshot work, auto-restore can interrupt the operation and restore lockdown instead of allowing state or policy changes to continue past the deadline. Retry the snapshot in a new shields-down window if the deadline interrupts it.

To tag a snapshot with a human-readable label, pass --name:

$nemohermes my-assistant snapshot create --name before-upgrade

To restore a specific snapshot instead of the latest, pass a version, name, or timestamp prefix:

$nemohermes my-assistant snapshot restore v3
$nemohermes my-assistant snapshot restore before-upgrade
$nemohermes my-assistant snapshot restore 2026-04-14T

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:

$nemohermes my-assistant snapshot restore before-upgrade --to my-assistant-clone
$nemohermes my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes

The force-overwrite path restores and verifies lockdown on a destination with an active shields timer, then revokes that timer before it deletes the destination. It clears the remaining local shields state only after deletion succeeds, before a same-name replacement is created.

The nemohermes <name> rebuild command uses the same snapshot mechanism automatically. NemoClaw rejects unsafe symlinks and hard links inside sandbox state during backup creation before they can enter a snapshot. 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.

For full details, refer to the Commands reference.

Manual Backup

Use openshell sandbox download to copy files from the sandbox to your host.

$SANDBOX=my-hermes
$BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S)
$mkdir -p "$BACKUP_DIR"
$
$openshell sandbox download "$SANDBOX" /sandbox/SOUL.md "$BACKUP_DIR/"
$openshell sandbox download "$SANDBOX" /sandbox/.hermes/state.db "$BACKUP_DIR/"
$openshell sandbox download "$SANDBOX" /sandbox/.hermes/platforms/ "$BACKUP_DIR/platforms/"

Manual Restore

Use openshell sandbox upload to push files back into a sandbox.

$SANDBOX=my-hermes
$BACKUP_DIR=~/.nemoclaw/backups/20260320-120000  # pick a timestamp
$
$openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/
$openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/state.db" /sandbox/.hermes/
$openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/platforms/" /sandbox/.hermes/platforms/

Back Up All Running Sandboxes

To back up every registered, running sandbox in one step, run nemohermes backup-all. Use this host-installed command before broad maintenance such as nemohermes update, nemohermes upgrade-sandboxes, or an OpenShell gateway migration.

$nemohermes backup-all

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 nemohermes <name> snapshot list and nemohermes <name> snapshot restore to inspect or restore one sandbox’s bundles later.

Using the Backup Script

For Hermes, prefer the built-in snapshot commands for faithful restore of state.db. Use manual openshell sandbox download / openshell sandbox upload only when you need to inspect or transfer a specific file.

Hermes State

Hermes does not use OpenClaw per-agent workspace directories. NemoClaw snapshots preserve the Hermes manifest-defined state tree and durable top-level files instead. Refer to Workspace Files for the Hermes state layout.

Next Steps