Manage Sandbox Lifecycle
Use this guide after you finish the OpenClaw quickstart.
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 nemoclaw and openshell.
List Sandboxes
List every sandbox registered on this host:
The list shows each sandbox’s model, provider, policy presets, and active SSH session indicator. It also shows the dashboard URL when NemoClaw records a dashboard port. Use JSON output for scripts:
Check Sandbox Health
Check a specific sandbox’s health, inference route, active connections, live policy, and update status: For messaging agents, the command also reports messaging-channel overlap warnings.
Use the host-level status command when you want the sandbox inventory plus host auxiliary service state, such as cloudflared:
Inspect Logs
View recent sandbox logs:
Stream logs while you reproduce a problem:
The log command reads both OpenClaw gateway output and OpenShell audit events, so policy denials appear beside gateway logs.
Collect Diagnostics
Collect diagnostics for bug reports or support handoff:
Use --quick for a smaller local summary:
The debug command gathers system information, Docker state, sandbox logs, and sandbox status.
Manage Dashboard Ports
If the forward stopped, or the installer reported that no active forward was found and the URL does not load, restart the forward manually with the port from the install summary.
To list active forwards across all sandboxes, run the following command.
Run Multiple Sandboxes
Each sandbox needs its own dashboard port because openshell forward refuses to bind a port that another sandbox already uses.
When the default port is already held by another sandbox, nemoclaw onboard scans ports 18789 through 18799 and uses the next free port.
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 and dashboard cleanup is scoped by sandbox name and port.
A later onboarding run that uses a different NEMOCLAW_GATEWAY_PORT or --control-ui-port does not tear down the first sandbox’s gateway or dashboard forward.
To choose a specific port, pass --control-ui-port:
You can also set CHAT_UI_URL or NEMOCLAW_DASHBOARD_PORT before onboarding:
For full details on port conflicts and overrides, refer to Port already in use.
Reconfigure or Recover
Recover from a misconfigured sandbox without re-running the full onboard wizard or destroying workspace state.
Change Inference Model or API
Change the active model or provider at runtime without rebuilding the sandbox:
Refer to Switch Inference Providers for provider-specific model IDs and API compatibility notes.
Restart the Gateway and Port Forward
If nemoclaw <name> status reports the sandbox is alive but the gateway is not running, run the recover command instead of opening a shell.
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.
For built-in OpenClaw sandboxes, recovery sends an authenticated request through registry-scoped privileged direct-container control.
The request reaches either the root PID 1 supervisor in a direct root-entrypoint container or the installed root controller in an OpenShell-managed container.
It does not fall back to ordinary openshell sandbox exec or a manual relaunch inside the sandbox.
Refer to nemoclaw <name> recover for details.
Use gateway restart when you intentionally need a supported OpenClaw gateway to reload runtime configuration or plugins.
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> gateway restart for details.
In the direct root-entrypoint topology, the gateway uses a separate gateway UID and restart receives the root-only seal.
In the OpenShell-managed topology, OpenShell is PID 1 and nonroot nemoclaw-start, the gateway, and the agent use the same sandbox UID.
The installed root controller validates the stable process shape, targets the exact observed child with a pidfd, preflights config, and proves replacement health.
That managed proof prevents PID reuse but cannot establish provenance against a malicious same-UID process, and mutable config retains managed cold-start trust and time-of-check/time-of-use limits.
Arbitrary nonroot entrypoints that do not match the supported OpenShell-managed process shape fail closed with privileged control unavailable.
Kubernetes and other deployments without a matching direct container also fail closed with privileged control unavailable.
If a direct-container sandbox uses an older image without the matching supervisor or managed controller helper, rebuild it before retrying:
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:
Refer to nemoclaw credentials reset <PROVIDER> for full command details.
Rebuild a Sandbox While Preserving Workspace 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:
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 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:
Refer to nemoclaw <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.
If a support workflow asks you to pass the maintained tag explicitly, set NEMOCLAW_INSTALL_TAG on the bash side of the install pipeline.
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 nemoclaw 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.
Legacy managed-image confirmation never overrides recorded custom-image evidence.
A custom OpenClaw sandbox can be recovered only when the selected validated backup independently carries complete authoritative image-plugin provenance; otherwise recovery stops before deletion.
The installer attempts every eligible recovery, exits with a nonzero status if any recovery fails, and skips generic onboarding after successful recovery.
A third outcome exists: when a recorded sandbox is not observed in any phase on its own recorded gateway (typically because a prior uninstall removed the gateway and Docker image while preserving sandboxes.json), the recovery pass exits 0 but reports the sandbox as not found rather than recovered, and the installer finishes with Installation completed with warnings plus remediation guidance (nemoclaw <name> destroy, then nemoclaw onboard) instead of claiming success.
For manual upgrade flows, create a snapshot first and then run the update or rebuild command you need:
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 nemoclaw update, nemoclaw upgrade-sandboxes, and nemoclaw <name> rebuild for command flags.
Uninstall
To remove NemoClaw and all resources created during setup, run the CLI’s built-in uninstall command:
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.
Preserving sandboxes.json does not preserve the gateway registration, provider registrations, or Docker image its recorded sandboxes depend on; uninstall warns that those records cannot be recovered automatically on reinstall, and the remediation is nemoclaw <name> destroy followed by nemoclaw onboard.
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:
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 --.
Refer to nemoclaw uninstall vs. the hosted uninstall.sh for a full comparison of what the two forms fetch, what they trust, and when to prefer each.
Related Topics
- Set Up Messaging Channels to connect Telegram, Discord, or Slack.
- Workspace Files for persistent OpenClaw files inside the sandbox.
- Backup and Restore for snapshot and restore workflows.
- Monitor Sandbox Activity for observability tools.