Manage SandboxesState and Backups

Create and Restore Snapshots

View as Markdown

NemoClaw snapshots preserve manifest-defined sandbox state before destructive or state-changing operations. They are the preferred backup and restore path.

When to Create a Snapshot

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

Understand Snapshot Contents

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. Treat snapshot directories as private local data.

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.

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

The target sandbox’s current agent manifest remains authoritative for state-file restore behavior. NemoClaw rejects the restore when the snapshot’s agent, config directory, state-file path, or state-file strategy conflicts with that manifest.

For managed images, NemoClaw applies the current manifest’s managed config merge rules by default and does not fall back to whole-file replacement. For Deep Agents targets, whole-file config replacement is limited to sandboxes created from a custom Dockerfile.

Create and List Snapshots

$nemo-deepagents my-assistant snapshot create
$nemo-deepagents my-assistant snapshot list

snapshot list prints a table of version, name, timestamp, and path. NemoClaw computes versions (v1, v2, through 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.

Tag a snapshot with a human-readable label:

$nemo-deepagents my-assistant snapshot create --name before-upgrade

Restore a Snapshot

Restore the latest snapshot:

$nemo-deepagents my-assistant snapshot restore

Pass a version, name, or timestamp prefix to select a specific snapshot:

$nemo-deepagents my-assistant snapshot restore v3
$nemo-deepagents my-assistant snapshot restore before-upgrade
$nemo-deepagents 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:

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

For dashboard-enabled agents, NemoClaw allocates the destination sandbox its own dashboard port instead of reusing the source port. If no port is available, restore stops before deleting an existing --force destination.

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.

Restore Agent Configuration Safely

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.

Excluded Deep Agents State

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 excluded because NemoClaw reconstructs managed MCP state and disables executable Deep Agents Code hooks in the managed harness. NemoClaw recreates the current inference route headers, models and update tables, managed MCP projection state, and provider credentials from host-side onboarding and OpenShell provider state during rebuild.

Restore Managed Deep Agents Configuration

For a NemoClaw-managed Deep Agents image, NemoClaw restores only the allowlisted ui.show_scrollbar, ui.show_url_open_toast, threads.relative_time, and threads.sort_order preferences from the previous config.toml when their values pass validation. Unknown, runtime-controlled, executable, and security-sensitive backup keys are dropped instead of replacing freshly generated settings on that managed path.

A Deep Agents target created from a custom Dockerfile restores config.toml as a whole file because the custom image owns its config schema. On the managed key-level restore path, malformed config, missing managed data, an unsafe link, or an unsafe file replacement fails the restore without falling back to a whole-file copy.

Validate Before Replacement

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.

Back Up Every Registered Sandbox

Run nemo-deepagents backup-all before broad maintenance such as nemo-deepagents update, nemo-deepagents upgrade-sandboxes, or an OpenShell gateway migration.

$nemo-deepagents backup-all

backup-all walks the sandboxes registered on the host, creates a snapshot for each eligible running or temporarily started sandbox, and stores the snapshot bundles under ~/.nemoclaw/rebuild-backups/<name>/. If a registered docker-driver sandbox’s container is stopped, backup-all starts the container for the duration of the backup and returns it to its stopped state afterward. If the container cannot be returned to the stopped state, the backup run fails and reports that the container was left running. If a sandbox is not running and its container cannot be started this way, start the sandbox or its container and rerun nemo-deepagents backup-all.

When a backup fails, NemoClaw identifies the affected state item and reports permission denied, tar read error, or absent after extraction when available. Use nemo-deepagents <name> snapshot list and nemo-deepagents <name> snapshot restore to inspect or restore one sandbox’s bundles later.