> 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 AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemoclaw/_mcp/server.

# Recover and Rebuild Sandboxes

> Recover a stopped agent runtime or rebuild a sandbox while preserving supported state.

Use the lightest recovery operation that repairs the sandbox while preserving its supported state.

## Recover the Agent Runtime

If `nemoclaw <name> status` reports the sandbox is alive but the gateway is not running, run the recover command instead of opening a shell.

```bash
nemoclaw <sandbox-name> recover
```

The command repairs a stopped in-sandbox gateway and re-establishes the dashboard port-forward in one step.
It is idempotent and safe to script.
If the gateway is already healthy, `recover` exits after the probe and does not restart it.

Use `gateway restart` when you intentionally need a supported OpenClaw gateway to reload runtime configuration or plugins.

```bash
nemoclaw <sandbox-name> gateway restart
```

The restart command asks the topology-specific controller to stop the tracked gateway child, wait for the entrypoint to launch a replacement, and prove listener and HTTP health.
The host then checks or recovers host-side dashboard, messaging, and agent forwards.
Refer to [`nemoclaw <name> recover`](../../reference/commands#nemoclaw-name-recover) and [`nemoclaw <name> gateway restart`](../../reference/commands#nemoclaw-name-gateway-restart) for details.

Recovery uses registry-scoped privileged direct-container control and does not fall back to ordinary `openshell sandbox exec` or a manual in-sandbox relaunch.
For a local Docker-driver sandbox whose container still uses the legacy keepalive startup, `recover` can transactionally recreate the registered container with a credential-free managed startup command.

NemoClaw keeps the previous container available until the managed controller proves the supervisor topology, gateway health, and settle check, and attempts to restore it if that proof fails.
The recreation preserves mounted sandbox state, but a committed swap does not retain changes stored only in the previous container's writable layer.

For the controller topology, trust boundary, and fail-closed conditions, refer to [Understand Gateway Lifecycle Control](../configure-sandboxes/understand-gateway-lifecycle-control).
If recovery cannot repair a sandbox that needs credentials or a current controller contract, rebuild it.

## Rebuild While Preserving State

If you changed the underlying Dockerfile, upgraded OpenClaw, or want to pick up a new base image without losing your sandbox's workspace files, use `rebuild` instead of destroying and recreating.

```bash
nemoclaw <sandbox-name> rebuild
```

The rebuild command preserves the mounted workspace and registered policies while recreating the container.

If an archive command produces some usable entries, NemoClaw preserves those entries and reports the manifest-defined paths that could not be archived.
If backup fails before producing any usable entry, NemoClaw stops before deleting the original sandbox unless you explicitly pass `--force`.

`rebuild --force` can continue after a total backup failure by recreating the sandbox from recorded registry metadata without restoring prior sandbox state.
Use this recovery path only when losing uncommitted or otherwise unsnapshotted state is acceptable.

When rebuild starts with shields up, NemoClaw opens a 30-minute shields-down window for backup and recreation.
A detached auto-lock timer remains the recovery authority until NemoClaw commits a successful shields-up state, including when the host rebuild process exits unexpectedly.

Refer to [`nemoclaw <name> rebuild`](../../reference/commands#nemoclaw-name-rebuild) for flag details.

## Use the Canonical Configuration Workflows

* Use [Switch Inference Providers](../../inference/manage-inference/switch-providers) to change a model or provider.
* Use [Credential Rotation](../../security/credential-rotation) to reset or replace a stored provider credential.
* Use [Customize the Network Policy](../../network-policy/customize-network-policy) to add or remove policy presets.

## Related Topics

* [Create and Restore Snapshots](../state-and-backups/create-and-restore-snapshots) for the state-preservation contract.
* [Troubleshooting](../../reference/troubleshooting) for `privileged control unavailable`, stopped sandboxes, and failed rebuilds.