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

## 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.

```bash
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.

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

```bash
nemohermes my-assistant snapshot create --name before-upgrade
```

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

```bash
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`:

```bash
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 `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 (`config.yaml` and
`.env`) are also excluded; model/provider and messaging credentials are
recreated from host-side onboarding and OpenShell provider state during rebuild.
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-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.

```bash
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/
```

## 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](workspace-files) for the Hermes state layout.

## Next Steps

* [Workspace Files overview](workspace-files) to learn what each file does.
* [Commands reference](../reference/commands)