Manage Sandboxes

Manage Sandbox Lifecycle

View as Markdown

Use this guide after you finish Quickstart with Deep Agents. It covers ongoing sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling.

When a workflow uses the lower-level OpenShell CLI, refer to CLI Selection Guide for the boundary between nemo-deepagents, nemo-deepagents, and openshell.

List Sandboxes

List every sandbox registered on this host:

$nemo-deepagents list

The list shows each sandbox’s model, provider, policy presets, and active SSH session indicator. Use JSON output for scripts:

$nemo-deepagents list --json

Check Sandbox Health

Check a specific sandbox’s health, inference route, active connections, live policy, and update status:

$nemo-deepagents my-assistant status

Use the host-level status command when you want the sandbox inventory plus host auxiliary service state, such as cloudflared:

$nemo-deepagents status

Inspect Logs

View recent sandbox logs:

$nemo-deepagents my-assistant logs

Stream logs while you reproduce a problem:

$nemo-deepagents my-assistant logs --follow

The log command reads Deep Agents sandbox output and OpenShell audit events, so policy denials appear beside terminal-runtime logs.

Collect Diagnostics

Collect diagnostics for bug reports or support handoff:

$nemo-deepagents debug --sandbox my-assistant --output nemoclaw-debug.tar.gz

Use --quick for a smaller local summary:

$nemo-deepagents debug --quick --sandbox my-assistant

The debug command gathers system information, Docker state, sandbox logs, and sandbox status.

Run Multiple Sandboxes

Deep Agents sandboxes do not expose a dashboard port. The first nemo-deepagents onboard run can use the default sandbox name from the wizard. When you create another Deep Agents sandbox, choose a distinct sandbox name in the wizard or pass --name in scripted runs.

If you intentionally run separate OpenShell gateways on the same host, set a different NEMOCLAW_GATEWAY_PORT before each onboarding run. NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another. Gateway cleanup is scoped by sandbox name and port.

$nemo-deepagents onboard
$# For an additional named sandbox:
$nemo-deepagents onboard --name <sandbox-name>

Reconfigure or Recover

Recover from a misconfigured sandbox without re-running the full onboard wizard or destroying workspace state.

Change Inference Model or API

For Deep Agents, recreate the sandbox when you change the provider or model so /sandbox/.deepagents/config.toml and the OpenShell route stay aligned:

$nemo-deepagents onboard --fresh --name <sandbox-name> --recreate-sandbox

Refer to Switch Inference Providers for provider-specific model IDs and API compatibility notes.

Restart the Gateway and Port Forward

Deep Agents sandboxes are terminal runtimes and do not expose an OpenClaw or Hermes in-sandbox gateway. Use nemo-deepagents <sandbox-name> status, logs, connect, and rebuild for recovery. If the terminal runtime reports degraded health, rebuild the sandbox instead of using recover or gateway restart.

Reset a Stored Credential

If you entered a provider credential incorrectly during onboarding, clear the gateway-registered value and re-enter it on the next onboard run:

$nemo-deepagents credentials list                # see which providers are registered
$nemo-deepagents credentials reset <PROVIDER>    # clear a single provider, for example nvidia-prod
$nemo-deepagents onboard                         # re-run to re-enter the cleared provider

Refer to nemo-deepagents credentials reset <PROVIDER> for full command details.

Rebuild a Sandbox While Preserving Workspace State

If you changed the underlying Dockerfile, upgraded Deep Agents Code, enabled Tavily Search, or want to pick up a new base image without losing manifest-defined Deep Agents state, use rebuild instead of destroying and recreating:

$nemo-deepagents <sandbox-name> rebuild

The rebuild command preserves manifest-defined Deep Agents state, regenerates config.toml, reconstructs managed MCP projection state, and reapplies registered policies while recreating the container. If NemoClaw cannot archive any requested state path, it reports the backup failure and stops before deleting the original sandbox. 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 nemo-deepagents <name> rebuild for flag details.

Add a Network Preset After Onboarding

Apply an additional preset, such as Telegram or GitHub, to a running sandbox without running onboarding again:

$nemo-deepagents <sandbox-name> policy-add

Refer to nemo-deepagents <name> policy-add for usage details and flags.

Non-interactive re-onboards in the default suggested policy mode preserve presets added this way. To make a re-onboard authoritative, set NEMOCLAW_POLICY_MODE=custom and provide NEMOCLAW_POLICY_PRESETS with the exact list to apply; onboarding removes anything else. Refer to NEMOCLAW_POLICY_MODE for the full table.

Update to the Maintained Version

When a maintained NemoClaw release becomes available, update the host CLI and then check whether existing sandboxes need rebuilds. The standard installer follows the admin-promoted lkg release tag by default.

$curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
$nemo-deepagents upgrade-sandboxes --check

If a support workflow asks you to pass the maintained tag explicitly, set NEMOCLAW_INSTALL_TAG on the bash side of the install pipeline.

$curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_INSTALL_TAG=lkg bash

Before upgrade work, the installer prepares the current NemoClaw CLI without replacing OpenShell and requires a fresh backup of every registered sandbox. If any sandbox is skipped or fails, the installer exits before it changes the gateway. After the host CLI and OpenShell update, the installer runs nemo-deepagents upgrade-sandboxes --auto to reconcile the existing sandboxes. If an existing sandbox is not Ready, the automatic path requires a validated latest backup whose sandbox and agent identity match the registry and positive evidence that NemoClaw managed the image. For a listed pre-fingerprint OpenClaw or Hermes registry entry, you can provide that evidence through the installer’s explicit managed-image confirmation. In a non-interactive run, set NEMOCLAW_CONFIRM_LEGACY_MANAGED_RECREATE to the exact JSON array of names printed by the installer, such as ["my-assistant","preserve-hermes"], only after you verify every named sandbox used a managed image. Recorded custom-image evidence remains blocked from automatic recreation. The installer attempts every eligible recovery, exits with a nonzero status if any recovery fails, and skips generic onboarding after successful recovery. For manual upgrade flows, create a snapshot first and then run the update or rebuild command you need:

$nemo-deepagents <sandbox-name> snapshot create --name pre-upgrade
$nemo-deepagents update --yes
$nemo-deepagents upgrade-sandboxes --check

Each rebuild destroys the old container and creates a new one, while preserving the manifest-defined workspace or agent state that NemoClaw knows how to snapshot. upgrade-sandboxes --check can report a sandbox as stale because the running agent version is behind, because the managed NemoClaw image fingerprint differs from the current CLI, or both. Custom-image sandboxes created with --from <Dockerfile> are not marked stale solely by image fingerprint, so an upgrade check does not accidentally replace them with the default image. Runtime changes outside those state paths, such as packages installed manually in the running container, are not preserved. Refer to Backup and Restore for the full state-preservation contract, snapshot restore behavior, and manual backup workflow. Refer to nemo-deepagents update, nemo-deepagents upgrade-sandboxes, and nemo-deepagents <name> rebuild for command flags.

Uninstall

To remove NemoClaw and all resources created during setup, run the CLI’s built-in uninstall command:

$nemo-deepagents uninstall
FlagEffect
--yesSkip the confirmation prompt.
--keep-openshellLeave OpenShell binaries installed.
--delete-modelsAlso remove NemoClaw-pulled Ollama models.
--destroy-user-dataAlso remove preserved user data (rebuild-backups/, backups/, sandboxes.json).
--gateway <name>Override the gateway name to remove (default: nemoclaw).

The uninstall command preserves ~/.nemoclaw/rebuild-backups/ (host-side snapshots written by snapshot and backup-all commands), ~/.nemoclaw/backups/ (workspace backups written by scripts/backup-workspace.sh), and ~/.nemoclaw/sandboxes.json (the sandbox registry) by default. Uninstall removes every other entry under ~/.nemoclaw/. Interactive runs prompt before they remove the preserved entries; the default answer keeps them. For non-interactive runs (--yes, NEMOCLAW_NON_INTERACTIVE=1, or a non-TTY shell), pass --destroy-user-data (or set NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1) to acknowledge data loss and remove the preserved entries as well. --yes stays non-destructive by design. It only acknowledges the global confirmation prompt and never purges preserved user data on its own. Full purge always requires an explicit --destroy-user-data or the matching env var, so existing automation using --yes retains its safe behaviour. For a full host-side file reference, see Host Files and State. Refer to the Commands reference for the full preservation contract.

The CLI uninstall command runs the version-pinned uninstall.sh that shipped with your installed CLI, so it does not fetch anything over the network at uninstall time.

If the CLI is missing or broken, fall back to the hosted script:

$curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash

The same --yes, --keep-openshell, --delete-models, --destroy-user-data, and --gateway flags listed above also apply to the hosted script. Pass them after bash -s --.

$curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash -s -- --yes --delete-models

Refer to nemo-deepagents uninstall vs. the hosted uninstall.sh for a full comparison of what the two forms fetch, what they trust, and when to prefer each.