nemoclaw-user-manage-sandboxes

What this skill does

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Manage Sandbox Lifecycle

Use this guide after you finish the OpenClaw quickstart (use the `nemoclaw-user-get-started` skill).
It covers day-two sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling.
When a workflow uses the lower-level OpenShell CLI, see CLI Selection Guide (use the `nemoclaw-user-reference` skill) for the boundary between `nemoclaw` and `openshell`.

## List Sandboxes

List every sandbox registered on this host:

```console
$ nemoclaw list
```

The list shows each sandbox's model, provider, policy presets, active SSH session indicator, and dashboard URL when a dashboard port is recorded.
Use JSON output for scripts:

```console
$ nemoclaw list --json
```

## Check Sandbox Health

Check a specific sandbox's health, inference route, active connections, live policy, update status, and messaging-channel overlap warnings:

```console
$ nemoclaw my-assistant status
```

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

```console
$ nemoclaw status
```

## Inspect Logs

View recent sandbox logs:

```console
$ nemoclaw my-assistant logs
```

Stream logs while you reproduce a problem:

```console
$ nemoclaw my-assistant logs --follow
```

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:

```console
$ nemoclaw debug --sandbox my-assistant --output nemoclaw-debug.tar.gz
```

Use `--quick` for a smaller local summary:

```console
$ nemoclaw debug --quick --sandbox my-assistant
```

The debug command gathers system information, Docker state, gateway 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 it manually with the port from the install summary.

```console
$ openshell forward start --background <dashboard-port> my-gpt-claw
```

To list active forwards across all sandboxes, run the following command.

```console
$ openshell forward list
```

## Run Multiple Sandboxes

Each sandbox needs its own dashboard port, since `openshell forward` refuses to bind a port that another sandbox is already using.
When the default port is already held by another sandbox, `nemoclaw onboard` scans ports `18789` through `18799` and uses the next free port.

```console
$ nemoclaw onboard                                      # first sandbox uses 18789
$ nemoclaw onboard                                      # second sandbox uses the next free port, such as 18790
```

To choose a specific port, pass `--control-ui-port`:

```console
$ nemoclaw onboard --control-ui-port 19000
```

You can also set `CHAT_UI_URL` or `NEMOCLAW_DASHBOARD_PORT` before onboarding:

```console
$ CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard
$ NEMOCLAW_DASHBOARD_PORT=19000 nemoclaw onboard
```

For full details on port conflicts and overrides, refer to Port already in use (use the `nemoclaw-user-reference` skill).

## 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:

```console
$ nemoclaw inference set --model <model> --provider <provider>
```

Refer to Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) 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.

```console
$ nemoclaw <sandbox-name> recover
```

The command restarts the in-sandbox gateway and re-establishes the dashboard port-forward in one step.
It is idempotent and safe to script.
Refer to `nemoclaw <name> recover` (use the `nemoclaw-user-reference` skill) for details.

### Reset a Stored Credential

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

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

The credentials command is documented in full at `nemoclaw credentials reset <PROVIDER>` (use the `nemoclaw-user-reference` skill).

### 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:

```console
$ nemoclaw <sandbox-name> rebuild
```

Rebuild preserves the mounted workspace and 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.
Refer to `nemoclaw <name> rebuild` (use the `nemoclaw-user-reference` skill) for flag details.

### Add a Network Preset After Onboarding

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

```console
$ nemoclaw <sandbox-name> policy-add
```

Refer to `nemoclaw <name> policy-add` (use the `nemoclaw-user-reference` skill) 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.
See `NEMOCLAW_POLICY_MODE` (use the `nemoclaw-user-reference` skill) for the full table.

## Update to the Latest Version

When a new NemoClaw release becomes available, update the `nemoclaw` CLI on your host and check existing sandboxes for stale agent/runtime versions.

### Update the NemoClaw CLI

Re-run the installer.
Before it onboards anything, the installer calls `nemoclaw backup-all` (use the `nemoclaw-user-reference` skill) automatically, storing a snapshot of each running sandbox in `~/.nemoclaw/rebuild-backups/` as a safety net.
If your existing gateway is from OpenShell earlier than `0.0.37`, the installer prompts before it runs the new automatic gateway upgrade path.
The automatic path is offered only when the existing `nemoclaw` CLI supports `backup-all`; older installs must preserve sandbox state manually before retiring the gateway.
For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemoclaw backup-all` and `openshell gateway destroy -g nemoclaw || openshell gateway destroy` before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`.

```console
$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
```

### Upgrade Sandboxes with Stale Agent and Runtime Versions

The installer checks registered sandboxes after onboarding succeeds and runs `nemoclaw upgrade-sandboxes --auto` for stale running sandboxes.
Use `upgrade-sandboxes` directly to verify the result, rebuild when you skipped the installer or onboarding step, or handle sandboxes that were stopped or could not be version-checked.
The upgrade flow is non-destructive by default because NemoClaw preserves manifest-defined workspace state, but a manual snapshot before any major upgrade gives you a state restore point.

```console
$ nemoclaw <sandbox-name> snapshot create --name pre-upgrade   # optional, recommended
$ nemoclaw update --yes