Backup and Restore Workspace Files
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
nemo-deepagents <name> destroy. - Before major NemoClaw version upgrades.
- Periodically, if you have invested time customizing Deep Agents skills, memory, or managed MCP state.
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 Deep Agents, snapshots include manifest-declared state under /sandbox/.deepagents, including skills and runtime state, while omitting credential-bearing user files.
NemoClaw refuses to create a snapshot when it detects an active dcode task or cannot verify that the Deep Agents state tree is idle.
Wait for active dcode work to finish before running nemo-deepagents <name> snapshot create.
Treat snapshot directories as private local data.
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.
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:
To restore a specific snapshot instead of the latest, pass a version, name, or timestamp prefix:
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:
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 nemo-deepagents <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 Deep Agents files such as .deepagents/.env and user-authored .deepagents/.mcp.json are intentionally excluded from snapshots.
Deep Agents auth state files such as .deepagents/.state/auth.json and .deepagents/.state/chatgpt-auth.json are also excluded because the managed launcher refuses to start when upstream credential state is present.
The managed .deepagents/.nemoclaw-mcp.json projection and hooks.json are also excluded because NemoClaw reconstructs managed MCP state and disables executable Deep Agents Code hooks in the managed harness.
NemoClaw recreates generated config.toml, managed MCP projection state, and provider credentials from host-side onboarding and OpenShell provider state during rebuild.
Before a Deep Agents rebuild changes the sandbox, NemoClaw verifies the recorded inference route, provider, model, reasoning settings, web search selection, base image, and policy inputs.
If a late check fails, NemoClaw restores the previous MCP state and keeps the existing sandbox intact.
For Deep Agents, the quickstart summarizes the managed state layout and the snapshot commands shown above cover normal backup and restore workflows.
Manual Backup
Use openshell sandbox download to copy files from the sandbox to your host.
Do not recursively download /sandbox/.deepagents/.state/.
That directory can contain upstream credential state such as auth.json and chatgpt-auth.json, which can copy secrets to the host and restore state that the managed launcher refuses.
Use nemo-deepagents <name> snapshot create when you need NemoClaw’s built-in sanitizer for Deep Agents runtime state.
Manual Restore
Use openshell sandbox upload to push files back into a sandbox.
Do not upload saved .deepagents/.state contents during manual restore.
Restore safe Deep Agents files only, then run the managed rebuild or onboarding flow so NemoClaw regenerates route metadata, managed MCP projection state, and credential handling from host-side state.
Back Up All Running Sandboxes
To back up every registered, running sandbox in one step, run nemo-deepagents backup-all.
Use this host-installed command before broad maintenance such as nemo-deepagents update, nemo-deepagents upgrade-sandboxes, or an OpenShell gateway migration.
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 nemo-deepagents <name> snapshot list and nemo-deepagents <name> snapshot restore to inspect or restore one sandbox’s bundles later.
Using the Backup Script
For Deep Agents, prefer the built-in snapshot commands for normal rebuild and restore workflows.
Use manual openshell sandbox download / openshell sandbox upload only when you need to inspect or transfer a specific safe file or directory.
Treat downloaded config.toml as inspection context.
Do not upload an old config.toml over a rebuilt sandbox unless you are intentionally replacing NemoClaw’s generated route metadata.
Never manually back up or restore .deepagents/.state/auth.json or .deepagents/.state/chatgpt-auth.json.
Deep Agents State
Deep Agents does not use OpenClaw per-agent workspace directories.
NemoClaw snapshots preserve the Deep Agents manifest-defined state tree under /sandbox/.deepagents.
Generated config and credential-bearing user files are handled by the managed rebuild path rather than ordinary snapshot restore.
If you rely on upstream memory files such as /sandbox/.deepagents/agent/AGENTS.md or /sandbox/.deepagents/agent/memories/, verify that your release includes them in the manifest-backed state set or copy them manually before destroying the sandbox.
Next Steps
- Set Up MCP Servers explains managed MCP configuration for Deep Agents sandboxes.
- Workspace Files explains the managed Deep Agents state layout.