commands.mdx

---
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
title: "NemoClaw CLI Commands Reference"
sidebar-title: "Commands"
description: "Full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands."
description-agent: "Includes the full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands. Use when looking up a specific `$$nemoclaw`, `nemohermes`, `nemo-deepagents`, `dcode`, or `/nemoclaw` subcommand, flag, argument, or exit code."
keywords: ["nemoclaw cli commands", "nemoclaw command reference", "nemo-deepagents commands", "dcode commands"]
content:
  type: "reference"
---
<AgentOnly variant="openclaw">

The `$$nemoclaw` CLI is the primary interface for managing NemoClaw sandboxes.
It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`).
For guidance on when to use `$$nemoclaw` versus the underlying `openshell` CLI, refer to [CLI Selection Guide](cli-selection-guide).

</AgentOnly>
<AgentOnly variant="hermes">

The `nemohermes` alias is the primary interface for managing Hermes sandboxes through NemoClaw.
It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes bash`).
Most commands in this reference use the same arguments and subcommands across agent variants.
Use `nemohermes` when you want Hermes selected by default.
For guidance on choosing between the agent CLIs and the underlying `openshell` CLI, refer to [CLI Selection Guide](cli-selection-guide).

</AgentOnly>
<AgentOnly variant="deepagents">

The `nemo-deepagents` alias is the primary interface for managing Deep Agents sandboxes through NemoClaw.
It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=langchain-deepagents-code bash`).
Most commands in this reference use the same arguments and subcommands across agent variants.
Use `nemo-deepagents` when you want Deep Agents selected by default.
For guidance on choosing between the agent CLIs and the underlying `openshell` CLI, refer to [CLI Selection Guide](cli-selection-guide).

</AgentOnly>

## Agent Selection

<AgentOnly variant="openclaw">

Use `$$nemoclaw` for the OpenClaw variant.
OpenClaw is the default agent for `$$nemoclaw onboard` unless you select another installed agent with `--agent <name>` or set `NEMOCLAW_AGENT=<name>`.
Run `$$nemoclaw agents list` to see the installed agent names; for example, use `hermes` for Hermes or `langchain-deepagents-code` for LangChain Deep Agents Code.
OpenClaw-specific sections below describe the `/nemoclaw` slash command, the OpenClaw dashboard URL, the OpenClaw gateway token, and OpenClaw config paths under `/sandbox/.openclaw`.

</AgentOnly>
<AgentOnly variant="hermes">

Use `nemohermes` for the Hermes variant.
It selects Hermes by default during onboarding and for other commands.
Use `--agent hermes` during onboarding or set `NEMOCLAW_AGENT=hermes` when you need the same selection through another entry point.
Hermes-specific sections below describe the built-in Hermes dashboard, the separate OpenAI-compatible API endpoint, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`.

```bash
nemohermes onboard              # selects Hermes by default
nemohermes my-sandbox connect   # connects to a Hermes sandbox
```

</AgentOnly>
<AgentOnly variant="deepagents">

Use `nemo-deepagents` for the Deep Agents variant.
It selects `langchain-deepagents-code` by default during onboarding and for other commands.
Use `--agent langchain-deepagents-code`, `--agent dcode`, or `NEMOCLAW_AGENT=langchain-deepagents-code` when you need the same selection through another entry point.
Deep Agents-specific sections below describe the `dcode` terminal runtime, managed `/sandbox/.deepagents` config, and commands that launch the interactive TUI or headless runner.

```bash
nemo-deepagents onboard              # selects Deep Agents by default
nemo-deepagents my-sandbox connect   # connects to a Deep Agents sandbox
```

</AgentOnly>

## In-Sandbox Commands

<AgentOnly variant="openclaw">

The `/nemoclaw` slash command is available inside the OpenClaw chat interface for quick actions:

| Subcommand | Description |
|---|---|
| `/nemoclaw` | Show slash-command help and host CLI pointers |
| `/nemoclaw status` | Show sandbox and inference state |
| `/nemoclaw shields [status]` | Explain that shields status is unavailable inside the sandbox and point to `$$nemoclaw <name> shields status` on the host |
| `/nemoclaw onboard` | Show onboarding status and reconfiguration guidance |
| `/nemoclaw eject` | Show rollback instructions for returning to the host installation |

Use host-side `$$nemoclaw <sandbox> shields status|up|down` commands to inspect or change shields posture.

</AgentOnly>
<AgentOnly variant="hermes">

Hermes does not use the OpenClaw chat slash command.
Use the host-side `nemohermes` commands for lifecycle, status, policy, and inference operations.
The in-sandbox Hermes integration installs the NemoClaw Hermes plugin, which exposes tools for status, environment information, and skill reload support, plus an `on_session_start` hook.

</AgentOnly>
<AgentOnly variant="deepagents">

Deep Agents does not use the OpenClaw chat slash command.
Use the host-side `nemo-deepagents` commands for lifecycle, status, policy, and inference operations.
Inside the sandbox, use `dcode` for the interactive TUI and `dcode -n` for explicit headless automation.
Add `--json` when automation needs the managed, versioned result envelope.

```bash
dcode
dcode -n "Summarize this repository"
dcode -n "Summarize this repository" --json
dcode status
```

For the JSON schema, status and exit behavior, and 1 MiB output limit, refer to [Run Deep Agents Code](/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code).

</AgentOnly>

## Hosted Installer Options

The hosted installer accepts options after `bash -s --`.
These options control installation and the onboarding run that follows it.

### `--local-model-runtime=vllm`

Enable the fixed vLLM local model profile.
The flag accepts only `vllm`.
It makes the remaining onboarding non-interactive and disables Express profile selection.

```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | \
<AgentOnly variant="openclaw">
  NEMOCLAW_AGENT=openclaw \
</AgentOnly>
<AgentOnly variant="hermes">
  NEMOCLAW_AGENT=hermes \
</AgentOnly>
<AgentOnly variant="deepagents">
  NEMOCLAW_AGENT=langchain-deepagents-code \
</AgentOnly>
  NEMOCLAW_SANDBOX_NAME=my-assistant \
  NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 \
  bash -s -- --local-model-runtime=vllm
```

The profile selects a fixed catalog model and serving command from the managed-inference catalog.
The hosted installer rejects `NEMOCLAW_PROVIDER`, `NEMOCLAW_MODEL`, and a vLLM `NEMOCLAW_VLLM_PORT` override before onboarding.
The dedicated vLLM onboarder rejects `NEMOCLAW_VLLM_MODEL`, `NEMOCLAW_VLLM_PORT`, and `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` before it installs vLLM.

The hosted installer's equivalent environment-variable form requires both `NEMOCLAW_ENABLE_LOCAL_MODEL_PROFILE=1` and `NEMOCLAW_LOCAL_MODEL_RUNTIME`.
Use the installer flag unless an automation boundary cannot pass installer arguments.
For prerequisites, effects, verification, and recovery, refer to [Choose a Local Inference Server](../inference/local-inference/choose-local-inference-server#install-a-fixed-vllm-profile).

## Hosted Installer Exit Statuses

The hosted installer reports how a run stopped through its exit status.
When you interrupt it at a prompt, it exits `130`, the same status that `$$nemoclaw onboard` reports for that interrupt.
An interrupted onboarding run still prints `[ERROR] Onboarding did not complete successfully.` before it exits, so read the exit status rather than that line.
The installer preserves no other signal status, and a progress step stopped by `SIGTERM` also exits `130`, so a script that stops the installer itself cannot read `130` as a deliberate interrupt.
DGX Station host preparation exits `10` when it requires a reboot and `11` when it requires a new login session, and prints the command that resumes the install.
Treat every other non-zero status as a failure.

## Standalone Host Commands

The CLI handles host-side operations that run outside the selected agent runtime.

### `$$nemoclaw help`, `$$nemoclaw --help`, `$$nemoclaw -h`

Show the top-level usage summary and command groups.
Running `$$nemoclaw` with no arguments shows the same help output.

```bash
$$nemoclaw help
```

### `$$nemoclaw --version`, `$$nemoclaw -v`

Print the installed NemoClaw CLI version.

```bash
$$nemoclaw --version
```

### `$$nemoclaw completion`

Generate a tab-completion script for Bash, Zsh, or Fish from the commands and flags available in the installed CLI.
The script completes public global commands, the sandbox-first `$$nemoclaw <name> ...` grammar, flags, shell choices, and locally registered sandbox names.
If you omit the shell name, `$$nemoclaw completion` detects the target from `$SHELL` and defaults to Bash when it cannot identify Zsh or Fish.
The generated script is bound to the CLI name that created it, so install a separate script for each CLI alias you use.
It loads sandbox names from the local registry the first time completion runs and caches them for the rest of that shell session.

For Bash, source the generated script and add the same line to `~/.bashrc` for future sessions.

```bash
source <($$nemoclaw completion bash)
```

For Zsh, source the generated script and add the same line to `~/.zshrc` for future sessions.

```zsh
source <($$nemoclaw completion zsh)
```

For Fish, write the generated script to Fish's completions directory.

```fish
mkdir -p ~/.config/fish/completions
$$nemoclaw completion fish > ~/.config/fish/completions/$$nemoclaw.fish
```

Start a new shell session to refresh the cached sandbox names after creating or removing a sandbox.

### `$$nemoclaw resources`

Display host hardware inventory and configured sandbox resource profiles.
Use `--json` for machine-readable CPU, memory, GPU, Kubernetes allocatable-capacity, and profile data.

```bash
$$nemoclaw resources [--json]
```

If the gateway is not running, Kubernetes allocatable fields are omitted and host CPU/RAM totals are still shown.

### `$$nemoclaw host probe`

Inspect host capabilities and gateway authority before onboarding without changing host, Docker, gateway, credential, policy, or sandbox state.
Use `--json` for the schema-versioned report.
The command exits with `0` for `supported`, `2` for `incompatible`, and `3` for `inconclusive`.

```bash
$$nemoclaw host probe [--json]
```

For capability IDs, evidence bounds, and compatibility guidance, refer to [System Readiness](system-readiness).

### `$$nemoclaw agents list`

List the installed agent runtimes that can be selected with `$$nemoclaw onboard --agent <name>`.
Use this global command when you need valid runtime names before creating or recreating a sandbox.
It lists runtime names with the descriptions from their installed manifests.

```bash
$$nemoclaw agents list
```

Expected output:

```text
openclaw                   Gateway-based AI agent with plugin ecosystem (openclaw.ai)
hermes                     Self-improving AI agent with learning loop (Nous Research)
langchain-deepagents-code  Terminal coding agent built on the Deep Agents SDK
```

### `$$nemoclaw profiles list`

List the serving profiles installed with NemoClaw and evaluate them against the current host.
The command reports each profile's stable ID, display name, inference backend, model, topology, selection mode, support state, estimated downloads, and incompatibility reason.
It reads the serving catalog and host readiness state without downloading a model or changing host, gateway, inference, or sandbox resources.

```bash
$$nemoclaw profiles list
```

Use `--json` for machine-readable output with the same profile fields.

```bash
$$nemoclaw profiles list --json
```

Use the stable `id` value with `$$nemoclaw onboard --profile <name>`.
Display names are accepted when they identify exactly one profile, but stable IDs are suitable for scripts and automation.

### `$$nemoclaw onboard`

Run the interactive setup wizard (recommended for new installs).
The wizard creates an OpenShell gateway, registers inference providers, builds the sandbox image, and creates the sandbox.
Use this command for new installs and for recreating a sandbox after changes to policy or configuration.

```bash
$$nemoclaw onboard [--profile <name>] [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from <Dockerfile>] [--name <sandbox>] [--host-mount <host:/sandbox/path>] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device <device>] [--agent <name>] [--agents <agents.yaml>] [--tool-disclosure <progressive|direct>] [--observability | --no-observability] [--control-ui-port <N>] [--events=jsonl] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software]
```

<AgentOnly variant="hermes">

For Hermes, use the alias or pass the agent explicitly:

```bash
nemohermes onboard [options]
nemoclaw onboard --agent hermes [options]
```

</AgentOnly>
<AgentOnly variant="deepagents">

For Deep Agents, use the alias or pass the agent explicitly:

```bash
nemo-deepagents onboard [options]
nemoclaw onboard --agent langchain-deepagents-code [options]
```

</AgentOnly>

`--agent` accepts the canonical manifest names from `$$nemoclaw agents list` plus common aliases.
For example, `nemohermes` resolves to `hermes`, while `dcode`, `deepagents`, `deepagents-code`, and `langchain` resolve to `langchain-deepagents-code`.

#### `--profile <name>`

Select one serving profile from `$$nemoclaw profiles list` for interactive or non-interactive onboarding.
The flag is generic and does not add a model-specific command or flag.
NemoClaw maps a unique display name to its stable catalog ID and passes that ID to the managed inference path.

```bash
$$nemoclaw onboard --profile <profile-id>
```

NemoClaw rejects an unknown, ambiguous, disabled, or incompatible profile before image or model downloads begin.
It also rejects `--profile` when you combine it with `NEMOCLAW_PROVIDER`, `NEMOCLAW_MODEL`, `NEMOCLAW_VLLM_MODEL`, `NEMOCLAW_MANAGED_CLUSTER_PEERS`, or `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` overrides.
If `NEMOCLAW_SERVING_PRESET` is already set, it must select the same stable profile ID; a different ID conflicts with `--profile`.
Run `$$nemoclaw profiles list` to inspect an incompatibility reason before onboarding.

If you omit `--profile`, onboarding uses the same provider and model defaults as an installation without this feature.
The onboarding review screen identifies the resolved profile, recipe, model, runtime image, support state, and download estimates before confirmation.
After creation, human status shows the profile, recipe, and catalog digest; JSON status includes the complete secret-free `servingProfileProvenance` record for diagnostics and automation.

#### `--host-mount`

On Linux and Windows Subsystem for Linux 2 (WSL2), repeat `--host-mount <absolute-host-directory:/sandbox/directory>` to expose existing host directories read-only inside the sandbox.
The option requires a NemoClaw-managed Docker-driver gateway and does not provide a read-write mode.
Refer to [Mount a Host Directory for Read-Only Access](../manage-sandboxes/state-and-backups/understand-sandbox-state#mount-a-host-directory-for-read-only-access) for validation rules, security considerations, persistence, and verification.

#### `--events=jsonl`

Emit a read-only stream of canonical onboarding FSM events as JSON Lines on stdout.
Each line is one JSON object with the version 1 envelope:

```json
{"schemaVersion":1,"session":"<session-id>","type":"state.entered","timestamp":"2026-07-13T12:34:56.789Z","payload":{"state":"inference","step":"inference","context":{"agent":"openclaw","sandboxName":"alpha","provider":"nvidia-prod","model":"nvidia/test-model","endpointOrigin":"https://integrate.api.nvidia.com","credentialEnv":"NVIDIA_API_KEY"},"error":null,"metadata":{}}}
```

In this mode, human progress remains available on stderr so stdout stays valid JSONL.
Payloads contain only the existing bounded, redacted machine-event context: credential environment variable names may appear, but credential values and secret-bearing URL components are redacted.
For a `compatible-endpoint` route that uses `openai-completions`, the context includes `reasoningEffort` as `low`, `medium`, `high`, or `endpoint-default`.
Other provider and API-family routes omit this field.
Treat new event `type` values and new payload fields as additive changes.
A breaking envelope or field-semantics change increments `schemaVersion`.

This surface observes the canonical onboarding session and does not accept input, cancel onboarding, or create another state machine.
It does not provide event history, reconnect, or replay; use the existing `--resume` behavior after an interrupted onboarding process.
Closing the output pipe or applying sustained backpressure disables observation without cancelling, rolling back, or otherwise changing onboarding.
Without `--events=jsonl`, terminal output and behavior are unchanged.

#### `--resume` and `--fresh`

NemoClaw records onboarding progress so interrupted runs can continue.
Use `--resume` to continue a resumable onboarding session with the provider, model, sandbox name, agent, observability choice, custom Dockerfile path, read-only host-mount declarations, and any explicitly selected serving-profile provenance recorded by the original run.
For a profile-backed session, resume requires the same catalog, preset, and recipe digests and exits before effects if the installed definition changed.
Omit `--profile` to reuse that recorded selection, or pass the same profile explicitly; use `--fresh` to adopt a changed catalog definition.
Sessions without a serving-profile provenance record can resume when their checkpoint uses schema 4, but they cannot acquire a new `--profile` selection during resume.

Checkpoint schema 4 records whether onboarding uses the default profile or the portable experimental profile.
For the portable profile, it also records the current user's canonical home reported by the operating system, that home's exact `.config` directory, the runtime root, rootless Podman endpoint path, and runtime ownership.
It does not record ambient Docker or Podman runtime selector values.
The runtime authority record contains no credentials.
A plain `--resume` restores the recorded profile.
You can also run `$$nemoclaw onboard --experimental-profile portable --resume` when the recorded profile is portable.
NemoClaw rejects an explicit profile that conflicts with the checkpoint before it changes portable configuration, activates the user-scoped Podman socket, or changes gateway and sandbox resources.

Portable resume derives `DOCKER_HOST`, `CONTAINERS_CONF`, and `NETAVARK_FW` again while it holds the onboarding lock.
It ignores ambient Docker and Podman runtime selectors during that derivation.
NemoClaw scopes the derived values to onboarding and restores the process environment after success or failure.
It verifies the current user, canonical roots, socket path and ownership, Podman identity and version, and required configuration before a resumed onboarding step changes resources.
Resume stops before writes or activation if an existing socket or configuration path is a symlink, has the wrong owner, or has an unsafe type or mode.
NemoClaw can create missing descendants beneath a validated current-user root and reconcile content drift in its own portable configuration files.
A missing user-scoped socket after a host reboot can be activated and verified at the recorded path.
A new socket inode or a supported Podman upgrade does not invalidate the checkpoint.
Portable onboarding always uses the `.config` directory beneath the canonical home reported by the operating system.
`HOME` and `XDG_CONFIG_HOME` never select or override this authority.
NemoClaw ignores ambient `XDG_CONFIG_HOME` during onboarding and restores its exact prior presence and value afterward.
Resume rejects a checkpoint that records another configuration root.
It also rejects stored authority or filesystem ownership drift without falling back to Docker.

<Warning title="Checkpoint Resume Compatibility">
An active onboarding session with checkpoint schema 1, 2, or 3 cannot resume because those schemas did not record the default or portable profile authority.
NemoClaw preserves the older session and exits before portable configuration, socket activation, or resource changes.
Run `$$nemoclaw onboard --fresh` to discard the active session and start fresh onboarding.
If you intend to use the portable experimental profile, run `$$nemoclaw onboard --experimental-profile portable --fresh`.
This compatibility restriction does not prevent NemoClaw from reading a completed older session during status inspection.
</Warning>

Before the configuration review, NemoClaw records the sandbox name and the selected provider and model as an incomplete choice.
If onboarding stops at the review prompt, an interactive `--resume` run shows the prompt again.
A non-interactive `--resume` run reuses the recorded choice and continues to inference setup.
After you choose **Apply configuration**, NemoClaw records the choice before inference setup starts.
If inference setup fails, `--resume` reuses the accepted provider, model, and sandbox name.
If you choose **Exit onboarding**, onboarding exits with a nonzero status and clears those recorded choices.
Run `$$nemoclaw onboard` to make new choices after exit.
During a resume without terminal input, `--yes` or `NEMOCLAW_YES=1` also selects non-interactive resume behavior.
For a new or fresh session, `--yes` and `NEMOCLAW_YES=1` accept supported confirmations but do not replace `--non-interactive`.
If onboarding returns without reaching the final `complete` state, the command exits with status `1`.
When that result is resumable, NemoClaw keeps the session `in_progress` at its last checkpoint instead of marking it failed, so correct the reported condition and run `$$nemoclaw onboard --resume`.

<AgentOnly variant="openclaw">

OpenClaw sessions also record the web search selection, messaging selection and non-secret settings, and resource profile.
When the saved session includes prompt checkpoints, resume skips each completed group and continues at the first incomplete choice.
Legacy sessions without those checkpoints may repeat choices whose completion cannot be proven.
Raw web search and messaging credentials are never written to the onboarding session.
Resume skips their secret prompts when the same session recorded a successful OpenShell provider registration and OpenShell still reports the exact expected name, type, and credential keys.
If the session lacks that registration receipt, the provider is missing, or its binding does not match, interactive resume requests the credential again; non-interactive resume preserves the completed choice, reports the required environment variable, and exits so you can export it before retrying.

</AgentOnly>

Completed onboarding sessions are not resumable.
Use `--resume` only for resumable interrupted or failed sessions, not to change provider, model, agent, or sandbox recreation settings after onboarding has completed.
During resume, NemoClaw reruns preflight, gateway, provider, and sandbox repair checks even when the saved session has already reached a later nonterminal onboarding phase.
If the recorded session conflicts with flags you pass on the recovery run, NemoClaw exits and tells you to either rerun with the original settings or start over.

An active same-name replacement is separate from ordinary onboarding-step resume.
If onboarding printed `Journaled replacement` before it stopped, rerun the original onboarding command with the same target settings.
The replacement can continue without an explicit `--resume` flag.
Refer to [Continue an Interrupted Replacement](../manage-sandboxes/operate-sandboxes/recover-and-rebuild-sandboxes#continue-an-interrupted-replacement) for the identity checks and failure conditions.

Use `--fresh` to discard the saved onboarding session and start the wizard from the beginning.
This clears stale or failed session state before NemoClaw creates a new session record.
It also bypasses locally recorded sandbox base-image resolution metadata and reruns normal candidate resolution.
`--fresh` takes precedence over a base-image hint carried from a rebuild, so NemoClaw does not use that recorded hint.
The installer also accepts `--fresh` and forwards it to `$$nemoclaw onboard`, which skips automatic resume detection.
`--resume` and `--fresh` are mutually exclusive.
For an existing completed sandbox, use `--fresh --name <sandbox-name> --recreate-sandbox` when you intentionally want onboarding to replace that sandbox with a new provider, model, agent, or build-time setting.
Use `$$nemoclaw <sandbox-name> rebuild` when you want NemoClaw to recreate the sandbox from its recorded registry metadata without changing those selections.

#### `--tool-disclosure <progressive|direct>`

Choose how the selected agent presents its session-authorized tools to the model.
`progressive` is the default: OpenClaw and Hermes use their native Tool Search implementations, while Deep Agents Code initially shows its core tools plus `search_tools` after at least one MCP tool loads successfully.
`direct` restores the previous behavior and presents all registered tools directly.
This setting changes model context only; it does not bypass OpenShell policy, credentials, approvals, hooks, or sandbox controls.

The flag takes precedence over `NEMOCLAW_TOOL_DISCLOSURE`.
A new sandbox defaults to `progressive` when neither is set.
NemoClaw records the selected value with the onboarding session and sandbox so rebuilds preserve it and ambient shell variables cannot silently change an internal rebuild.
Model-specific compatibility safeguards may downgrade a selected `progressive` mode to direct exposure for that model without changing the recorded preference.
To change an existing sandbox, recreate it explicitly:

```bash
$$nemoclaw onboard --name my-assistant --recreate-sandbox --tool-disclosure direct
```

Without an explicit flag or environment value, recreation preserves the recorded setting and only falls back to `progressive` for legacy state.
Resuming an interrupted session with a different explicit setting fails with a conflict instead of changing behavior mid-session.

<AgentOnly variant="deepagents">

#### `--observability` and `--no-observability`

Enable backend-neutral trace export for a LangChain Deep Agents Code sandbox.
During initial onboarding, pass `--observability` with the Deep Agents alias.
When you use the generic `nemoclaw` entry point, combine it with `--agent langchain-deepagents-code`.
NemoClaw rejects the positive flag for OpenClaw and Hermes sandboxes.
Use `--no-observability` when you need to clear a recorded Deep Agents Code choice before switching the resumed session to another agent.

```bash
$$nemoclaw onboard --observability
nemoclaw onboard --agent langchain-deepagents-code --observability
```

The flag is off by default.
When enabled, NemoClaw records the choice with the onboarding session and sandbox, adds the `observability-otlp-local` policy preset on supported policy tiers, and preserves the choice across resume and rebuild operations.
An explicit `--observability` or `--no-observability` choice updates a resumed onboarding session.
The Restricted tier suppresses automatic application of the preset.
An operator can add it manually after reviewing the additional egress, but the next Restricted onboarding or rebuild reconciliation removes it.

The explicit opt-in can export bounded prompts, responses, tool arguments, tool results, and operational metadata.
Treat trace payloads as sensitive application data.
The managed capture applies size, depth, item-count, recognized-key, and exception-text safeguards, but it does not detect secrets embedded in ordinary content values.
Deep Agents Code sends OTLP/HTTP protobuf traces to the fixed local endpoint `http://host.openshell.internal:4318/v1/traces`.
The OTLP library adds standard transport headers, but the sandbox cannot configure operator-supplied custom or authentication headers, a remote endpoint, backend credentials, or a backend.

Changing this setting on an existing sandbox requires a new sandbox process so the startup environment matches the recorded choice.
Use the transactional rebuild flags so NemoClaw backs up declared agent state, preserves managed MCP providers and adapter state, recreates the sandbox, and restores the backup.

```bash
$$nemoclaw my-dcode rebuild --observability --yes
$$nemoclaw my-dcode rebuild --no-observability --yes
```

Removing the `observability-otlp-local` policy stops delivery immediately but does not clear the recorded opt-in.
A later rebuild restores the preset on Balanced and Open tiers, while Restricted continues to suppress it.
For policy recovery and the host-side LangSmith exporter example, refer to [Set Up Deep Agents Trace Export](/user-guide/deepagents/monitoring/set-up-deepagents-trace-export).
Review [Understand Deep Agents Trace Export](/user-guide/deepagents/monitoring/understand-deepagents-trace-export) for the privacy boundary, [Verify Deep Agents Trace Export](/user-guide/deepagents/monitoring/verify-deepagents-trace-export) for delivery checks, and [Manage Deep Agents Trace Export](/user-guide/deepagents/monitoring/manage-deepagents-trace-export) for lifecycle operations.

</AgentOnly>

When Docker exposes the required identity metadata, NemoClaw records the base-image resolution on managed sandbox images.
During a warm recreate or rebuild, it validates the local image identity and platform, plus the exact repository digest for a published image and any active OpenShell ABI requirement, before reusing it.
A valid match avoids candidate discovery and a network pull.
Set `NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1` to bypass the recorded hint without changing onboarding session handling:

```bash
NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1 $$nemoclaw onboard --recreate-sandbox
NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1 $$nemoclaw <sandbox-name> rebuild
```

Base-image selection follows this precedence:

1. `--fresh` or `NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1` bypasses recorded metadata and reruns normal candidate resolution. These controls are equivalent for base-image selection.
2. Without a bypass, NemoClaw validates and reuses the recorded hint when possible.
3. When the hint is absent or no longer valid, NemoClaw performs normal resolution.

After a cache miss, source checkouts require a fresh local build before candidate selection when base-image inputs have dirty or staged changes, or Git cannot inspect the worktree safely.
For a clean release checkout or versioned install, NemoClaw first accepts the exact release-version image.
If that tag exists locally but fails compatibility validation, NemoClaw refreshes the same tag from the registry once and validates it again.
If the release-version image is missing or still incompatible, NemoClaw builds a compatible local base instead of falling back to mutable `:latest`.
For clean unversioned development checkouts, NemoClaw first tries the image tagged with the exact source commit.
If that image is unavailable and committed base-image inputs differ from `main`, NemoClaw requires a compatible local build.
When committed base-image inputs match `main`, NemoClaw tries the image tagged with the newest reachable release version from `origin` and only uses `:latest` when no version tag is discoverable.
When a stable tag and a prerelease tag share the same version, NemoClaw prefers the stable tag.
If `origin` tag lookup is unavailable, NemoClaw uses the newest reachable local release tag as a fallback.
If that nearest release-version image is missing or incompatible, NemoClaw builds a compatible local base instead of falling back to mutable `:latest`.
The required-build path does not reuse an older local tag.
If local builds are disabled or the build fails, resolution stops instead of selecting a stale image.
When the OpenShell sandbox ABI is required, NemoClaw also rejects a built image that does not report a compatible glibc version.

Explicit base-image overrides are exact: NemoClaw validates the requested ref and fails closed when it cannot be pulled or does not satisfy required ABI, agent runtime, or dependency checks.
Otherwise, normal resolution checks compatible images in Docker's local image store before attempting to pull a missing published candidate.
For warm-hint reuse and unversioned development resolution, NemoClaw can reuse another validated local fallback when published candidates are unavailable or incompatible.
When the OpenShell sandbox ABI is required, that local fallback must be ABI-compatible.
An offline warm recreate or rebuild can therefore continue when the recorded image or another compatible candidate is available locally.
When source inputs require a fresh local build, NemoClaw fails the operation if that build cannot be produced and validated instead of substituting an older local tag.
When the OpenShell sandbox ABI is required, resolution also fails if no ABI-compatible image can be resolved instead of falling back to an unvalidated cached `:latest` image.

<AgentOnly variant="hermes">

For Hermes, warm-hint and candidate validation reruns a container probe for the MCP SDK and native Streamable HTTP integration.
During normal resolution, NemoClaw tries the exact published digest declared by the final Hermes Dockerfile before release-version and source-commit candidates.
The digest must also pass any active OpenShell ABI requirement, and a validated result can be recorded for warm-hint reuse.
The final Hermes image accepts only the official published digest tracked by its Dockerfile or a repository-built local base, so an otherwise reachable or ABI-compatible image is not sufficient.

</AgentOnly>

Bypassing the recorded hint does not clear Docker's local image store or require a network pull.
Only `--fresh` also discards the saved onboarding session; the refresh environment variable affects base-image selection only.

<Warning>
For NemoClaw-managed environments, use `$$nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox.
Avoid `openshell self-update`, `npm update -g openshell`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `$$nemoclaw onboard`.
</Warning>

Use `--fresh` to ignore any saved onboarding session and restart the wizard from scratch. This is useful after an interrupted `$$nemoclaw onboard` run when you want to discard saved state instead of continuing it with `--resume`.

The installer detects existing sandbox sessions before onboarding and prints a warning if any are found.
To make the installer abort instead of continuing, set `NEMOCLAW_SINGLE_SESSION=1`:

```bash
NEMOCLAW_SINGLE_SESSION=1 curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
```

When existing sandboxes were created with OpenShell earlier than `0.0.37`, the installer prompts before running the automatic gateway upgrade path.
For scripted installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1` to allow the automatic path to prepare the current CLI without replacing OpenShell, back up every registered sandbox with the current state manifest, retire an installed gateway whose OpenShell version is outside the current release's supported range, install the supported OpenShell release, and recover the existing sandboxes.
The installer reads that supported range from the prepared current source and stops without retiring the gateway if the installed version is unknown or the range is missing or invalid.
When the installed OpenShell version is already supported, the installer keeps the running gateway through the host update.
On Linux, if installed OpenShell lifecycle commands cannot retire the gateway, the installer checks a verified NemoClaw-managed gateway PID file for any configured gateway port.
For the default gateway on port `8080`, the installer first checks a verified active `nemoclaw-openshell-gateway.service`, then checks the PID file.
After either fallback confirms the gateway process is stopped, the installer tries to remove the selected OpenShell registration and warns if onboarding must replace a stale registration.
If neither fallback can verify and stop the process, the installer stops after backup with every sandbox backup preserved.
If any registered sandbox cannot be backed up, the installer aborts before it changes the gateway.
After the automatic path retires an out-of-range gateway, it forces installation of the OpenShell version pinned by the prepared source before recovery.
This mandatory installation applies to source and managed install modes and cannot remain deferred after gateway retirement.
If the forced installation fails, the installer does not stage a gateway service or start recovery, preserves the backups, and tells you to rerun with `NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1`.
When the registry contains a pre-fingerprint OpenClaw or Hermes entry with no recorded custom-image evidence, an interactive install asks you to confirm that the listed sandbox used a NemoClaw-managed image.
For a non-interactive install, 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 verifying every named sandbox used a managed image.
The confirmation permits those legacy entries to recover onto the current managed image, but it does not override recorded custom-image evidence.
After successful recovery, the installer skips generic onboarding.
For any registered-sandbox upgrade that you already prepared manually, set `NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1` only after backing up every registered sandbox and retiring the old gateway.
This environment variable asserts that those steps are complete, so the installer skips the repeated backup and gateway-retirement phase before it checks whether OpenShell is installed or whether its version is in range.
For a non-default gateway, preserve the selected port on the `bash` side of the install pipeline.

```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_GATEWAY_PORT=<selected-port> NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash
```

It reuses the latest backups, forces the pinned OpenShell installation, and starts recovery only after that installation succeeds.
If the installation fails, rerun the same install-pipeline command to preserve `NEMOCLAW_GATEWAY_PORT` and `NEMOCLAW_OPENSHELL_UPGRADE_PREPARED`.

<Warning title="Legacy Upgrade Recovery Scope">
Prepared backup recovery for a legacy sandbox restores only the managed state directory recorded in its validated manifest, such as `/sandbox/.openclaw` or `/sandbox/.hermes`.
Files outside that recorded path, including `/sandbox/user-data`, are not preserved when the installer recreates the sandbox.
Back up those paths outside the sandbox before you continue.
</Warning>

The wizard prompts for a provider first, then collects the provider credential if needed.
Supported non-experimental choices include NVIDIA Endpoints, OpenRouter, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints.
Credentials are registered with the OpenShell gateway and never persisted to host disk.
Refer to [Credential Storage](../security/credential-storage) for details on inspection, rotation, and migration from earlier releases.
The legacy `$$nemoclaw setup` command is deprecated; use `$$nemoclaw onboard` instead.

On a qualified DGX Spark, the provider menu lists compatible experimental managed llama.cpp profiles in descending YAML priority order.
During interactive onboarding without an explicit provider request, the menu ignores `NEMOCLAW_LLAMACPP_RECIPE` and marks the unique highest-priority compatible profile as `(recommended)`.
The recommended profile appears as **Managed llama.cpp: Meta Muse Glimmer 30B on one DGX Spark (recommended)**.
The NVIDIA Nemotron profile appears next without the recommendation marker.
The selected menu entry determines the exact recipe even when `NEMOCLAW_LLAMACPP_RECIPE` names another recipe.
Select the same path non-interactively with the repository-owned recipe:

```bash
NEMOCLAW_PROVIDER=install-llama-cpp \
NEMOCLAW_LLAMACPP_RECIPE=llama-cpp.muse-glimmer-30b.spark-single.v1 \
NEMOCLAW_SANDBOX_NAME=my-assistant \
  $$nemoclaw onboard --non-interactive --yes-i-accept-third-party-software
```

Use `llama-cpp.nemotron-3-nano-30b-a3b.spark-single.v1` to select the lower-priority NVIDIA Nemotron recipe explicitly.

Do not set `NEMOCLAW_MODEL` for the managed llama.cpp path.
For prerequisites, external traffic, verification, and recovery, refer to [Install Managed llama.cpp on DGX Spark](../inference/local-inference/choose-local-inference-server#install-managed-llamacpp-on-dgx-spark).

After provider selection, the wizard reviews the provider, model, credential state, and sandbox name before registering inference.
The interactive review offers these actions:

- **Apply configuration** continues to provider registration.
- **Edit inference provider or model** returns to provider and model selection.
- **Edit sandbox name** prompts for the sandbox name again.
- **Exit onboarding** stops onboarding before provider registration.

When you edit inference, NemoClaw clears the credential staged for the discarded selection.
NemoClaw preserves the sandbox name.
When you edit the sandbox name, NemoClaw preserves the inference selection.
The sandbox prompt shows the prior name as its default.
After you apply the configuration, routine editing ends.
If inference setup fails and offers a `back` recovery action, you can return to provider and model selection and then review the updated configuration again.
<AgentOnly variant="openclaw,hermes">
It then prompts for optional web search and messaging channels, builds and starts the sandbox, and asks for a **policy tier** that controls the default set of network policy presets applied to the sandbox.
</AgentOnly>
<AgentOnly variant="deepagents">
It then prompts for optional web search, builds and starts the sandbox, and asks for a **policy tier** that controls the default set of network policy presets applied to the sandbox.
</AgentOnly>
Four tiers are available:

| Tier | Description |
|------|-------------|
| Restricted | No tier defaults. Web search or other integrations selected earlier can still add their required presets; deselect them during policy review for baseline-only access. |
| Balanced (default) | Full dev tooling and a selected, supported web search provider. Package installs, model downloads, and inference. No messaging platform access by default. |
| Open | Broad access across third-party services including supported messaging and productivity presets. Agent-specific unsupported presets are filtered out. |
| Personal | Requires one broad web authority that lets every sandbox binary open TCP connections to public and private address ranges on destination ports 80 and 443. It replaces overlapping exact web endpoints while preserving non-web policy. Unspecified, loopback, and link-local ranges remain blocked. Intended only for trusted personal-use workloads. |

After selecting a tier, the wizard shows a combined preset and access-mode screen where you can include or exclude individual presets and toggle each between read and read-write access.
When Personal is selected or carried forward, `personal-open-internet` is mandatory for every agent and every onboarding entry point, including Portable.
The picker and policy modes control only additional presets; they cannot deselect, skip, or replace Personal's required web authority.
For details on tiers and the presets each includes, refer to [Network Policies](network-policies#policy-tiers).
When you finish the policy step, NemoClaw records the finalized built-in preset selection for that sandbox.
When onboarding creates or recreates a sandbox with presets, NemoClaw prints the exact finalized create-time policy scope before registering providers or creating the sandbox.
Later re-onboard runs seed from that finalized selection, so presets you intentionally removed stay removed unless you select them again or override the policy mode.

In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `balanced`):

```bash
NEMOCLAW_POLICY_TIER=restricted $$nemoclaw onboard --non-interactive --yes-i-accept-third-party-software
```

Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default.
In non-interactive mode, any non-blank value must be one of `restricted`, `balanced`, `open`, or `personal`; otherwise onboarding exits before preflight, gateway, or inference side effects with an error listing the valid options.
Interactive onboarding ignores an invalid environment value and shows the normal tier prompt.

`NEMOCLAW_POLICY_MODE` controls how non-interactive onboarding reconciles the tier-derived suggestions against the sandbox's currently-applied presets.
The default is `suggested`, which is *additive*.
Onboarding applies tier defaults and preserves any presets you previously added with [`$$nemoclaw <name> policy add`](#$$nemoclaw-name-policy-add) across re-onboards.
Use `custom` with `NEMOCLAW_POLICY_PRESETS` when you want the explicit list to be authoritative for optional presets.
Onboarding removes any optional preset that is not in the list.
`skip` does not add optional tier defaults and retains eligible optional presets already applied.
For Personal, all modes still apply or retain the mandatory `personal-open-internet` preset.
NemoClaw filters tier suggestions and resume selections by active agent support and the selected web search provider.
During automatic suggestion and resume reconciliation, it removes stale web-search selections when they conflict with the active agent or selected provider.
The Personal tier instead uses `personal-open-internet` for web transport and does not select Brave Search or Tavily Search merely to enable ordinary web fetches.
This makes keyless fetches available to any sandbox binary, but it does not add a provider-free `web_search` implementation.
<AgentOnly variant="hermes">
For Hermes, this includes replacing stale `nous-web` when Tavily is selected.
</AgentOnly>
An explicit `custom` preset list or interactive manual selection remains operator-controlled for additional presets.

<AgentOnly variant="hermes">

Hermes managed-tool gateway selections add matching Hermes-specific policy presets, such as `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`, without applying unsupported OpenClaw-only presets.
When Tavily Search is selected, it replaces `nous-web` as the Hermes web search and extract backend while the other selected Nous tools remain enabled.

</AgentOnly>

| Value | Behaviour |
|-------|-----------|
| `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`. |
| `custom` | Apply exactly the optional presets in `NEMOCLAW_POLICY_PRESETS`. Previously-applied optional presets not in the list are removed. Personal still requires `personal-open-internet`. Alias: `list`. |
| `skip` | Do not add optional tier defaults; retain eligible optional presets already applied. Personal still applies or retains `personal-open-internet`. Aliases: `none`, `no`. |

<AgentOnly variant="openclaw">

OpenClaw onboarding supports Brave Search and Tavily Search.
NemoClaw registers a sandbox-scoped OpenShell provider and keeps `openclaw.json` on an OpenShell credential placeholder.
At egress, OpenShell rewrites Brave's `X-Subscription-Token` header with `BRAVE_API_KEY` or Tavily's `Authorization` header with `TAVILY_API_KEY`.
Treat web search as an explicit opt-in and use a dedicated low-privilege key.

</AgentOnly>
<AgentOnly variant="deepagents">

Deep Agents onboarding supports the maintained Tavily Search path.
NemoClaw registers the Tavily credential with the OpenShell gateway, applies the `tavily` policy preset when you opt in, and rebuilds the sandbox so the provider attaches to the managed Python runtime.
Do not place `TAVILY_API_KEY` in `/sandbox/.deepagents/.env`, `.state/auth.json`, or other Deep Agents Code state.

For non-interactive onboarding, export the Tavily key only in the host shell that runs onboarding:

```bash
export TAVILY_API_KEY=tvly-...
NEMOCLAW_AGENT=langchain-deepagents-code NEMOCLAW_WEB_SEARCH_PROVIDER=tavily $$nemoclaw onboard --non-interactive --yes-i-accept-third-party-software
unset TAVILY_API_KEY
```

</AgentOnly>
For non-interactive onboarding, you must explicitly accept the third-party software notice:

```bash
$$nemoclaw onboard --non-interactive --yes-i-accept-third-party-software
```

or:

```bash
NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 $$nemoclaw onboard --non-interactive
```

For scripted installer runs, pass explicit acceptance to the `bash` side of the installer pipe:

```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash
```

If the installer cannot prompt for the notice in a terminal and no explicit acceptance is set, it exits before installing Node.js or the NemoClaw CLI.

<AgentOnly variant="openclaw">

To enable Tavily Search in non-interactive mode, set the provider and matching key.

```bash
NEMOCLAW_WEB_SEARCH_PROVIDER=tavily \
TAVILY_API_KEY=... \
  $$nemoclaw onboard --non-interactive
```

Use `NEMOCLAW_WEB_SEARCH_PROVIDER=brave` with `BRAVE_API_KEY` for Brave Search, or set the provider to `none` to disable web search explicitly.
When the provider selector is unset, NemoClaw chooses Brave Search when `BRAVE_API_KEY` is available, then Tavily Search when only `TAVILY_API_KEY` is available.
Brave Search wins when both keys are available to preserve the historical non-interactive behavior.
An explicit provider with no matching key exits before sandbox creation.
A provider key that fails validation prints a warning, disables web search for that run, and lets the rest of onboarding continue.
After fixing the key, rerun onboarding so NemoClaw can validate it, register the selected provider, and apply the matching policy preset.
Changing or disabling the selected provider recreates the sandbox because the plugin configuration and credential attachment are part of the image.
Accept the recreate prompt or pass `--recreate-sandbox`.

</AgentOnly>
<AgentOnly variant="hermes">

Hermes supports Tavily Search through NemoClaw onboarding and does not support Brave Search.
To enable Tavily in non-interactive mode, set the provider and matching key.

```bash
NEMOCLAW_WEB_SEARCH_PROVIDER=tavily \
TAVILY_API_KEY=... \
  $$nemoclaw onboard --non-interactive
```

Set `NEMOCLAW_WEB_SEARCH_PROVIDER=none` to disable web search explicitly.
When the selector is unset, NemoClaw enables Tavily when `TAVILY_API_KEY` is available and ignores `BRAVE_API_KEY` for Hermes.
An explicit Tavily selection with no key exits before sandbox creation.
A Tavily key that fails validation prints a warning, disables web search for that run, and lets the rest of onboarding continue.
Changing or disabling Tavily recreates the sandbox because the Hermes backend, environment placeholder, and credential attachment are part of the image.
If you also select the Nous-managed web gateway through Nous Portal OAuth, Tavily replaces `nous-web` while other selected Nous tools remain enabled.
API-key mode is inference-only and does not enable managed Nous tool gateways.

</AgentOnly>

The wizard prompts for a sandbox name.
Names must contain 1 to 19 characters.
They must be lowercase, start with a letter, contain only letters, numbers, and single internal hyphens, and end with a letter or number.
Consecutive hyphens (`--`) are not allowed.
The CLI rejects names that do not match these rules.
It also prints a `Try: <suggested-slug>` recovery line whenever it can derive a valid lowercase, hyphen-separated form from the input, so passing `--name MyAssistant` reports `Try: myassistant`.
Names that match global CLI commands (`status`, `list`, `debug`, etc.) are rejected to avoid routing conflicts.
Use `--agent <name>` to target a specific installed agent profile during onboarding.
The `$$nemoclaw onboard --help` output lists installed runtime names inline, and `$$nemoclaw agents list` shows the same runtimes with manifest descriptions.

<AgentOnly variant="openclaw">

Use `--agents <agents.yaml>` to declare secondary OpenClaw agents, `agents.defaults`, and main-agent overrides in a checked-in manifest that NemoClaw bakes into the sandbox image at build time.
Refer to [Declarative Multi-Agent Manifest](../configure-agents/declarative-agents-manifest) for the schema and OpenClaw-native sub-agent field semantics.

</AgentOnly>

<AgentOnly variant="openclaw,hermes">

Use `--control-ui-port <N>` to choose the host dashboard port for a sandbox.
The value must be an integer from `1024` through `65535`.
This flag takes precedence over `CHAT_UI_URL`, `NEMOCLAW_DASHBOARD_PORT`, the previous registry value, and the default port.

Do not use a port from `8642` through `8652` for any agent.
NemoClaw allocates each Hermes sandbox's OpenAI-compatible API port from that range, so it rejects every port in the range as a dashboard port before sandbox creation.

If you enable Slack during onboarding, the wizard collects both the Bot Token (`SLACK_BOT_TOKEN`) and the App-Level Token (`SLACK_APP_TOKEN`).
Socket Mode requires both tokens.
The app-level token is stored in a dedicated `slack-app` OpenShell provider and forwarded to the sandbox alongside the bot token.
The wizard also accepts optional `SLACK_ALLOWED_USERS` and `SLACK_ALLOWED_CHANNELS` values so you can restrict Slack DMs, channel `@mention` users, and channel IDs before the sandbox image is built.

If you enable Discord during onboarding, the wizard can also prompt for a Discord Server ID, whether the bot should reply only to `@mentions` or to all messages in that server, and an optional Discord User ID.
NemoClaw bakes those values into the sandbox image as Discord guild workspace config so the bot can respond in the selected server, not just in DMs.
If you leave the Discord User ID blank, the guild config omits the user allowlist and any member of the configured server can message the bot.
Guild responses remain mention-gated by default unless you opt into all-message replies.
If `DISCORD_SERVER_ID` is set and `DISCORD_REQUIRE_MENTION` is unset, NemoClaw records the existing mention-only default (`DISCORD_REQUIRE_MENTION=1`).

If you enable Telegram during onboarding, the wizard can also prompt for whether group chats should reply only to `@mentions` or to all group messages.
Mention-only group replies are the default.
Set `TELEGRAM_REQUIRE_MENTION=0` for non-interactive onboarding when you want all group messages to trigger replies.
For OpenClaw, Telegram group access defaults to `TELEGRAM_GROUP_POLICY=open`; set `TELEGRAM_GROUP_POLICY=allowlist` or `TELEGRAM_GROUP_POLICY=disabled` before non-interactive onboarding when you want stricter group access.
Hermes does not have an equivalent disable-groups policy; `TELEGRAM_ALLOWED_IDS` maps to Hermes `TELEGRAM_ALLOWED_USERS`, which authorizes those users across DMs, groups, and forums.
Pairing and `TELEGRAM_ALLOWED_IDS` still govern direct messages.

</AgentOnly>

If you cancel a brand-new onboarding run at the policy preset step, NemoClaw rolls back the sandbox, registry entry, and onboarding session instead of leaving a default sandbox with unfinished policy state.
Existing live sandboxes are not deleted by this cancel rollback path.

If you run onboarding again with the same sandbox name and choose a different inference provider or model, NemoClaw detects the drift and recreates the sandbox so the running agent config matches your selection.
In interactive mode, the wizard asks for confirmation before delete and recreate.
In non-interactive mode, NemoClaw recreates automatically when the stored selection is readable and differs.
For managed Deep Agents Code sandboxes, NemoClaw also recreates when the live `dcode identity` selection is unreadable; other agent paths continue to reuse by default when their stored selection cannot be read.
Set `NEMOCLAW_RECREATE_SANDBOX=1` to force recreation even when no drift is detected.

Before deleting an existing sandbox during recreation, NemoClaw backs up the workspace state declared by the selected agent profile and restores it into the new sandbox once it is live.
This applies whether the existing sandbox is ready or marked not-ready, so cross-version upgrades that pass `NEMOCLAW_RECREATE_SANDBOX=1` no longer drop user files from the selected agent workspace.
The behaviour matches `$$nemoclaw <name> rebuild --force`.
NemoClaw aborts the recreate when the backup cannot complete in full, including when individual state directories or files fail mid-backup, so failed entries are not silently dropped on delete.
Set `NEMOCLAW_RECREATE_WITHOUT_BACKUP=1` to skip the pre-recreate backup.
The destination sandbox starts with a fresh workspace.

Before deletion, onboarding prints a `Journaled replacement` diagnostic with the replacement identifier, recorded OpenShell gateway, and current phase.
If the process stops after this point, a later same-target onboarding run continues the active replacement without requiring `--resume`.
It accepts a ready same-name replacement only when the live identity and sandbox registry generation match the journal.
It fails closed if the gateway, source, target, durable source registry fields, or replacement settings changed.

<AgentOnly variant="openclaw">

For OpenClaw, the backed-up paths include agents, extensions, workspace, skills, hooks, identity, devices, canvas, cron, memory, telegram, wechat, credentials, and `/sandbox/.openclaw/workspace/`.

</AgentOnly>
<AgentOnly variant="hermes">

For Hermes, the backed-up paths come from `agents/hermes/manifest.yaml`, including `/sandbox/.hermes` state such as memories, sessions, skills, plugins, cron, scripts, logs, plans, workspace, messaging platform state, `runtime/state.db`, and the default kanban board in `kanban.db`.
Kanban backup does not include named boards, attachments, worker logs, scratch workspaces under `kanban/`, or external directory or worktree targets.

</AgentOnly>

Before creating the gateway, the wizard runs preflight checks.
It verifies that Docker is reachable and prints host remediation guidance when prerequisites are missing.
Standard onboarding rejects unsupported runtimes such as Podman.
The explicit portable experimental profile has one installer-preflight admission exception for the Podman unsupported-runtime finding.
It does not waive any other readiness blocker or make Podman generally supported.
The preflight also enforces the OpenShell version range declared in the blueprint (`min_openshell_version` and `max_openshell_version`).
If the installed OpenShell version falls outside this range, onboarding exits with an actionable error and a link to compatible releases.
For fresh OpenShell installs, NemoClaw queries published OpenShell releases and asks the installer to use a release that fits the blueprint range.
If release metadata is unavailable, the installer uses its bundled fallback pin and the post-install version gate still enforces the range.

When NemoClaw finds an existing gateway to reuse, it probes the host gateway HTTP endpoint before declaring the gateway reusable.
If the container is running but the upstream is still warming up (for example, immediately after a Docker daemon restart), NemoClaw rebuilds the gateway instead of trusting stale metadata.
On the Docker-driver gateway path, preflight stays read-only when it detects a stale gateway (for example, a Docker-driver runtime env hash drift).
It prints a `⚠ Gateway will be recreated when sandbox creation starts` notice and defers the actual teardown to step `[2/8] Starting OpenShell gateway`.
This means pressing `Ctrl+C` between preflight and step `[2/8]` leaves the running gateway and existing sandbox containers untouched, so `$$nemoclaw onboard` is safe to run just to check preflight output.
An interrupted run prints the resume command and exits with status `130` for `Ctrl+C` or `143` for `SIGTERM`.
For Linux Docker-driver gateways, onboarding also checks that a helper container on the OpenShell Docker network can reach `host.openshell.internal:<gateway-port>`.
If a host firewall blocks that sandbox path, onboarding exits with a `sudo ufw allow from <subnet> to <gateway-ip> port <gateway-port> proto tcp` command before it reports the gateway healthy.
Set `NEMOCLAW_AUTO_FIX_FIREWALL=1` to opt in to automatic UFW remediation for this specific failure: NemoClaw uses `sudo -n` only, validates the Docker bridge subnet/gateway/port, applies the narrow UFW rule only after a proven TCP reachability failure, and re-probes before continuing.
If passwordless sudo, UFW, or active UFW is unavailable, NemoClaw falls back to the manual guidance path without prompting for a password.

For the portable experimental profile, the helper maps `host.openshell.internal` to the OpenShell Podman host gateway instead of the inspected network gateway.
This path does not use Docker bridge UFW remediation.
After all portable TCP probe attempts fail, onboarding prints commands for the user-scoped Podman service and socket.

Onboarding prints the same commands when the portable probe cannot reach the user-scoped Podman service.
The printed rerun command keeps the portable experimental profile selected.
Portable commands reconstruct the current user's rootless Podman socket authority from NemoClaw state before they use the Docker-compatible API.
They do not select an endpoint from ambient Docker or Podman runtime variables or named connections.
When `podman.service` reports inactive and the recorded socket exists, NemoClaw first makes one 10-second API request through the guarded recorded authority.
A valid server version classifies the endpoint as warm and avoids starting another socket service.
A missing socket or a response without a valid server version enters bounded cold activation.
Any socket authority change during this precheck fails at the socket authority stage.
When the user-scoped socket-backed service needs activation, NemoClaw activates it and waits through a bounded startup period for a real Podman API response.
During cold activation, the first API probe can cause systemd to replace the socket inode.
NemoClaw requalifies one such replacement and repeats the probe only when the socket path, device, mode, owner, and complete directory authority remain unchanged.
Any other authority change or a second inode replacement fails the readiness check.
After cold activation succeeds, later API health checks use the fixed 10-second steady-state deadline.
Onboarding and portable sandbox lifecycle commands use this same readiness contract.
Failures identify socket authority, service activation, startup API health, or steady-state API health without reporting credentials.
NemoClaw does not fall back to Docker or report an absent or unreachable endpoint as healthy.
A successful cold path uses the `cold` timing label and reports activation, API, and total time in milliseconds.
A successful warm path uses the `warm` timing label and reports steady-state API and total time in milliseconds.
To tune the existing-gateway HTTP health poll, use `NEMOCLAW_REUSE_HEALTH_POLL_COUNT` (default `6`) and `NEMOCLAW_REUSE_HEALTH_POLL_INTERVAL` (default `5` seconds).
The poll count is clamped to a minimum of `1` so the health probe always runs at least once, and the interval is clamped to a minimum of `0` (no sleep between attempts).

#### `--from <Dockerfile>`

Build the sandbox image from a custom Dockerfile instead of the stock NemoClaw image.
The supplied Dockerfile defines the complete sandbox image, and NemoClaw does not layer it on top of the stock managed runtime.
The entire parent directory of the specified file is used as the Docker build context, so any files your Dockerfile references (scripts, config, etc.) must live alongside it.
When the supplied path is the selected agent's own managed Dockerfile (for example, `agents/hermes/Dockerfile` in the NemoClaw checkout the CLI runs from), NemoClaw applies one exception and stages the repository root as the build context, exactly as the managed build does, because that Dockerfile copies repository-root paths.
This lets you edit the managed Dockerfile in place (for example to add Python packages) and rebuild from it with `--from`.
For this managed exception, onboarding applies the `.dockerignore` from the repository root.
For every other `--from` path, onboarding applies a `.dockerignore` from the Dockerfile's parent directory while calculating the context size and staging files for Docker.
NemoClaw also applies additional secret-safety exclusions that override `.dockerignore` negation rules: credential-style files and directories such as `.env*`, `.ssh/`, `.aws/`, `.netrc`, `.npmrc`, `secrets/`, `*.pem`, and `*.key` are still skipped even if `.dockerignore` tries to include them.
Without a `.dockerignore`, onboarding still skips common large or local-only directories (`node_modules`, `.git`, `.venv`, and `__pycache__`) while staging this context.
Other build outputs such as `dist/`, `target/`, or `build/` are included unless your `.dockerignore` excludes them.
If the staged context is larger than 100 MB, onboarding prints a warning before the Docker build starts.
Move the Dockerfile into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context.
If the directory contains unreadable files (for example, Windows system files visible in WSL), onboarding exits with an error suggesting you move the Dockerfile to a dedicated directory.

<Note>
NemoClaw builds user-supplied `--from` contexts with the OpenShell gateway builder.
The host-side local BuildKit prebuild is limited to build contexts generated entirely by NemoClaw.
On a local Docker-driver gateway, a `Local BuildKit build skipped` notice is expected and onboarding continues with the custom image.
</Note>

```bash
$$nemoclaw onboard --from path/to/Dockerfile
```

The Dockerfile path must exist.
Missing paths fail during command parsing before preflight, gateway setup, inference setup, or sandbox creation starts.

<AgentOnly variant="openclaw">

If deployment verification cannot reach the gateway for a custom OpenClaw image, NemoClaw checks for `/tmp/gateway.log`, `/usr/local/bin/nemoclaw-start`, and `/sandbox/.openclaw/openclaw.json`.
When all three paths are absent, onboarding reports that the custom image lacks the managed runtime instead of treating repeated port-forward retries as the recovery path.
For the version-matched full-runtime plugin workflow, refer to [Install OpenClaw Plugins](../manage-sandboxes/install-openclaw-plugins).

</AgentOnly>

The file can have any name; if it is not already named `Dockerfile`, onboard copies it to `Dockerfile` inside the staged build context automatically.
To create an isolated build context, create a dedicated directory that contains only the Dockerfile and the files it needs:

```text
build-dir/
├── Dockerfile
└── files-used-by-COPY/
```

For faster custom builds, plan for Docker cache behavior:

- Treat the first build on a fresh host as a cold build.
  Cold builds download the base image and package indexes, so they take longer than later warm rebuilds even when NemoClaw is healthy.
- A warm rebuild reuses cached layers when the base image and earlier layers are unchanged, so it is much faster than the first build.
- Order Dockerfile instructions from least-changing to most-changing: base image, system packages, dependency manifests, dependency install, then application source.
  This lets warm rebuilds reuse cached dependency layers instead of reinstalling on every source change.
- Pin the base image to an explicit tag or digest so warm rebuilds resolve the same cached base instead of pulling a new one.

To diagnose where a slow build spends time, set `NEMOCLAW_TRACE=1` and read the phase timings in [Onboard Profiling Traces](#onboard-profiling-traces).
NemoClaw does not guarantee exact build timings.

All NemoClaw build arguments (`NEMOCLAW_MODEL`, `NEMOCLAW_INFERENCE_PROVIDER_ID`, `NEMOCLAW_INFERENCE_BASE_URL`, etc.) are injected as `ARG` overrides at build time, so declare them in your Dockerfile if you need to reference them.

`NEMOCLAW_INFERENCE_PROVIDER_ID` is a non-secret inference route identifier (for example `inference` for proxied providers, or a provider family such as `openai`), never a credential; provider credentials stay in OpenShell provider storage.
It replaces the former `NEMOCLAW_PROVIDER_KEY` image argument, whose secret-shaped name triggered a BuildKit `SecretsUsedInArgOrEnv` warning.
The host-side `NEMOCLAW_PROVIDER_KEY` credential alias is unchanged; this migration only renames the managed image route selector.
Custom Dockerfiles that declare either `ARG NEMOCLAW_INFERENCE_PROVIDER_ID` or the legacy `ARG NEMOCLAW_PROVIDER_KEY` continue working in v0.0.91.
NemoClaw updates whichever supported declaration is present, and runtime consumers read the legacy name as a fallback.
Rename the legacy `ARG`/`ENV` declaration to `NEMOCLAW_INFERENCE_PROVIDER_ID`; the legacy fallback is retained for compatibility in this release and may be removed in a future release.

Custom Dockerfiles must declare `ARG NEMOCLAW_TOOL_DISCLOSURE=progressive` exactly once in the final build stage and promote it into that stage's runtime environment.
The usual runtime contract is:

```dockerfile
ARG NEMOCLAW_TOOL_DISCLOSURE=progressive
ENV NEMOCLAW_TOOL_DISCLOSURE=${NEMOCLAW_TOOL_DISCLOSURE}
```

Onboarding and rebuild preflight reject a missing, duplicate, or unconsumed declaration before replacing an existing sandbox.

In non-interactive mode, the path can also be supplied via the `NEMOCLAW_FROM_DOCKERFILE` environment variable.
You must also supply a sandbox name via `--name <sandbox>` or `NEMOCLAW_SANDBOX_NAME` so a `--from` build cannot silently clobber the default `my-assistant` sandbox.

```bash
NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_FROM_DOCKERFILE=path/to/Dockerfile NEMOCLAW_SANDBOX_NAME=my-build $$nemoclaw onboard
```

If a `--resume` is attempted with a different `--from` path than the original session, onboarding exits with a conflict error rather than silently building from the wrong image.

#### `--name <sandbox>`

Set the sandbox name without going through the interactive prompt.
The same name format and reserved-name rules that the wizard enforces apply here too.
Names must contain 1 to 19 characters.
They must be lowercase, start with a letter, contain only letters, numbers, and single internal hyphens, and end with a letter or number.
Consecutive hyphens (`--`) are not allowed.
Names that match a NemoClaw CLI command (`status`, `list`, `debug`, etc.) are rejected up front.

```bash
$$nemoclaw onboard --non-interactive --name my-build --from path/to/Dockerfile
```

The flag wins over `NEMOCLAW_SANDBOX_NAME`.
When prompting is possible, `NEMOCLAW_SANDBOX_NAME` fills the interactive default so you can press Enter to accept it.
When prompting is impossible (no TTY or `--non-interactive`), the env var is also honoured so existing CI scripts keep working.
Combining `--from <Dockerfile>` with non-interactive onboarding requires one of `--name` or `NEMOCLAW_SANDBOX_NAME`; otherwise onboarding exits rather than silently defaulting to `my-assistant` and clobbering the default sandbox.

### `$$nemoclaw onboard --from`

Use a custom Dockerfile for the sandbox image.
This variant of `$$nemoclaw onboard` accepts a `--from <Dockerfile>` argument to build the sandbox from a user-supplied Dockerfile instead of the default NemoClaw image.
The user-supplied context uses the OpenShell gateway builder instead of NemoClaw's host-side local BuildKit prebuild.

```bash
$$nemoclaw onboard --from ./Dockerfile.custom
```

### GPU Passthrough

When `$$nemoclaw onboard` detects an NVIDIA GPU on the host, it enables OpenShell GPU passthrough at both the gateway and sandbox level by default.
The `nvidia-smi` probes require a successful result and reject placeholder `JMJWOA-Generic-*` GPU names unless NemoClaw can prove a supported NVIDIA platform or GPU execution.
NemoClaw treats a recognized NVIDIA product model from `/sys/class/dmi/id/product_name` or `/sys/firmware/devicetree/base/model`, or a known Tegra device node, as authoritative platform identity.
On eligible native or Docker Desktop-backed WSL ARM64 Linux hosts without that firmware evidence, one bounded Docker CUDA workload can prove GPU execution.
On those hosts, a single plausible, non-placeholder NVIDIA GPU name also requires that proof when the NVIDIA kernel-driver interface (`/proc/driver/nvidia`) is absent.
For Windows-on-Arm, this proof is a technical detection check and does not change the Unsupported product status or establish platform qualification.
Refer to [Platform Support and Launch Claims](platform-support#out-of-scope-and-not-supported) for the current support boundary.
For the proof command, timeout control, and failure recovery, refer to [GPU Setup Fails with a Placeholder GPU Name](troubleshooting#gpu-setup-fails-with-a-placeholder-gpu-name).
The names-only unified-memory fallback does not run this workload and rejects denylisted names.
Other non-firmware-vouched hosts also reject denylisted names.
Jetson/Tegra hosts that ship without `nvidia-smi` continue to be detected via the devicetree firmware fallback (`/sys/firmware/devicetree/base/model`) or the Tegra device-node fallback (`/dev/nvhost-gpu`, `/dev/nvhost-ctrl-gpu`, `/dev/nvhost-ctrl`, or `/dev/nvmap`); both bypass the trust-tier gate above.
Use `--no-gpu` to opt out when you want host-side inference providers only and do not need direct GPU access inside the sandbox.
Use `--gpu` to require GPU passthrough and fail fast if an NVIDIA GPU is not detected.
Use `--sandbox-gpu` or `--no-sandbox-gpu` to control only direct NVIDIA GPU access inside the sandbox.
Use `--sandbox-gpu --sandbox-gpu-device <device>` to pass a specific OpenShell GPU device selector to `openshell sandbox create`; device selectors require explicit sandbox GPU enablement.
On ordinary native Linux Docker-driver hosts, NemoClaw uses native OpenShell GPU injection by default and never broadens confinement automatically.

<AgentOnly variant="openclaw">

Portable OpenClaw onboarding also requires native OpenShell GPU injection.
It does not use `NEMOCLAW_DOCKER_GPU_PATCH` compatibility routing, so do not set `fallback`, `1`, or another legacy nonzero value for that profile.

</AgentOnly>

Set `NEMOCLAW_DOCKER_GPU_PATCH=fallback` to explicitly authorize one native attempt followed by one compatibility retry.
NemoClaw permits the retry only after it confirms either a trusted host-side GPU routing failure or an explicit driver proof plus exact-container host configuration showing that no GPU was attached.
It then saves redacted diagnostics and removes the incomplete sandbox before retrying.
Sandbox-reported CUDA output alone never authorizes the broader compatibility envelope, even when the operator enabled fallback.
That case fails closed and points to the explicit `NEMOCLAW_DOCKER_GPU_PATCH=1` compatibility-only control.
NemoClaw retries only after it verifies that no OpenShell-managed Docker container labeled for that sandbox remains; if cleanup cannot be proven safe, onboarding stops and prints cleanup guidance instead.
On Docker Desktop WSL and Jetson/Tegra, automatic GPU onboarding uses the compatibility path directly.
On ordinary native Linux, the compatibility path uses an available NVIDIA CDI spec before falling back to Docker `--gpus all` or the NVIDIA runtime.
On Docker Desktop WSL, the compatibility path skips CDI and tries Docker `--gpus all` before the NVIDIA runtime.
On Jetson/Tegra hosts, the compatibility path uses the NVIDIA runtime and adds eligible host group IDs for the supported GPU device nodes.
These include selected `/dev/nvmap`, `/dev/nvhost-*`, and `/dev/nvgpu/igpu0/*` nodes plus real `/dev/dri/renderD*` character devices.
After compatibility recreation starts, onboarding keeps the pre-patch container as a rollback backup until the replacement passes the Ready, GPU, and applicable local-inference checks.
If one of those checks fails before backup removal, onboarding prints failure diagnostics and attempts to restore the pre-patch container.
To commit the replacement, NemoClaw stops it, removes the rollback backup, starts the replacement as the final container lifecycle event, and verifies OpenShell supervisor readiness again.
If that final handoff cannot be confirmed, onboarding exits with the container diagnostics and cleanup guidance instead of reporting success.
If rollback fails, onboarding reports that the pre-patch container was not restored and prints container-cleanup guidance.
GPU-proof diagnostics are captured before rollback and can print that guidance before the final container state is known, so inspect the sandbox and its labeled Docker containers before running a deletion command.

Prerequisites:

- Ensure NVIDIA GPU drivers are installed and working.
  - On generic NVIDIA hosts, `nvidia-smi` must succeed.
  - On Jetson/Tegra hosts shipping without `nvidia-smi`, the devicetree firmware fallback substitutes.
- NVIDIA Container Toolkit configured for Docker.

When GPU passthrough is enabled and a gateway already exists without it, onboarding first checks whether replacing the CPU-only gateway is safe.
If no other registered sandbox depends on that gateway, or if `--recreate-sandbox` is recreating the only registered sandbox with the same name, onboarding cleans up the stale gateway and continues.
If other sandboxes depend on the gateway or Docker state is unclear, onboarding exits without cleanup and prints targeted destroy or gateway-removal guidance.
To add GPU to an existing sandbox, rerun with `--recreate-sandbox`.
Leave `NEMOCLAW_DOCKER_GPU_PATCH` unset or set it to `auto` for native-only GPU onboarding on ordinary native Linux.
Set `NEMOCLAW_DOCKER_GPU_PATCH=fallback` to explicitly opt into one bounded native-to-compatibility retry on ordinary native Linux.
Set `NEMOCLAW_DOCKER_GPU_PATCH=0` to require native OpenShell GPU injection on ordinary native Linux or Jetson/Tegra.
Set `NEMOCLAW_DOCKER_GPU_PATCH=1` to use only the compatibility path on ordinary native Linux.
Other legacy nonzero values keep that behavior through the `v0.0.x` release line and will be removed in `v0.1.0`.
Use `NEMOCLAW_DOCKER_GPU_PATCH=0` on Jetson/Tegra only for troubleshooting because it bypasses Tegra device-group propagation and CUDA may not initialize.
Docker Desktop WSL ignores `NEMOCLAW_DOCKER_GPU_PATCH=0` because GPU passthrough on that runtime requires the compatibility patch.
Use `--no-sandbox-gpu`, `--no-gpu`, or `NEMOCLAW_SANDBOX_GPU=0` when you want to disable sandbox GPU passthrough on Docker Desktop WSL.

### `$$nemoclaw list`

List all registered sandboxes with their model, provider, and policy presets.
Pass `--json` for machine-readable output that includes a `schemaVersion`, the default sandbox, recovery metadata, and the sandbox inventory.
Each sandbox row reports `activeSessionCount` as a nonnegative integer when the SSH-session probe is available and `null` when it is unavailable.
Each sandbox row reports `agent` as a string in both text and JSON output, never `null`.
The row reports `openclaw` when the registry records no agent for the sandbox.
The row reports `unknown` for a sandbox that `$$nemoclaw list` recovers from the live OpenShell gateway.
The gateway sandbox list does not expose the agent.
The row does not include the former derived `connected` boolean.
Sandboxes with an active SSH session are marked with a `●` indicator so you can tell at a glance which sandbox you are already connected to in another terminal.
<AgentOnly variant="openclaw,hermes">
When a sandbox has a recorded dashboard port, the output includes its local dashboard URL.
</AgentOnly>
The default sandbox in text and JSON output honors the same environment override order as host-level status and tunnel commands: `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default.

```bash
$$nemoclaw list [--json]
$$nemoclaw list --json
```

### `$$nemoclaw use <name>`

Promote a registered sandbox to the default.
This is the first-class replacement for hand-editing `~/.nemoclaw/sandboxes.json`; it updates the registry through the same atomic, lock-guarded path that `$$nemoclaw onboard` uses for the initial default.
Subsequent commands and the `NEMOCLAW_SANDBOX_NAME` resolution order then pick up the new default automatically.
Pass `--json` to receive a machine-readable result indicating whether the registry was updated, the sandbox was already the default, or the name is unknown.

`$$nemoclaw use` is a thin selector and never mutates the sandbox itself.
It fails with a non-zero exit and a known-sandbox list when the requested name is not registered, so scripts can branch safely on the outcome.

```bash
$$nemoclaw use <name>
$$nemoclaw use <name> --json
```

### `$$nemoclaw launch <name>`

Connect to a sandbox and start its agent in one host-side command.
Use it instead of running `$$nemoclaw <name> connect` and then typing the agent command inside the sandbox.

`launch` runs the complete preflight from [`$$nemoclaw <name> connect`](#$$nemoclaw-name-connect) when no launch-readiness lease is usable.
That path includes the readiness wait, in-sandbox agent process recovery, and inference-route reconciliation.
A successful complete preflight can publish a credential-free launch-readiness lease with a fixed 24-hour lifetime on Linux.
Lease acceptance and publication are currently Linux-only and require a secure, independently writable OS per-user runtime authority under `/run/user/<numeric-uid>`.
It never uses caller-provided environment variables to select this authority.
On macOS, `launch` runs the complete preflight every time and does not publish a launch-readiness lease.

During that lease, another `launch` still verifies these conditions:

- The owning OpenShell gateway reports the exact sandbox identity in the `Ready` or `Running` state.
- The sandbox registry, agent manifest, interactive command, policy intent, and effective parsed OpenShell network policy match the recorded identity.
- The recorded inference selection matches the live route, and `inference.local` returns HTTP 2xx from its semantic probe when inference is configured. This is stricter than the HTTP 200–499 reachability diagnostic used by ordinary `connect`.
- The agent runtime and its required host-side forwards pass their semantic health checks.

<AgentOnly variant="openclaw">

For OpenClaw, `connect --probe-only` also settles the existing allowlisted pairing flow before it publishes the lease.
The readiness evidence binds the OpenClaw version and trusted registry and agent manifest configuration.
Its credential-free pairing qualification binds the canonical CLI client, exact paired device identity, required operator role and scopes, owning OpenShell gateway, sandbox lifecycle identity, and fixed lease epoch.
Before accepting that evidence, `launch` makes a bounded, read-only observation of the current OpenClaw-owned pairing state through the owning OpenShell gateway.
It skips the complete pairing approval pass only when the evidence still matches exactly and no relevant allowlisted request is pending.
Missing, unreadable, malformed, ambiguous, or changed pairing evidence runs the complete pairing approval pass.
A relevant allowlisted pending request also runs that complete path, so late scope requests remain eligible for approval.

</AgentOnly>

Hermes and LangChain Deep Agents Code retain their existing session setup on the lease-accepted path.

After these checks pass, `launch` can skip duplicate recovery, readiness polling, and inference-route repair.
The lease does not replace a health check or authorize repair.
For missing, expired, malformed, inaccessible, mismatched, or unhealthy evidence, NemoClaw fences any prior acceptable evidence before it runs the complete preflight.
Ordinary launch continues only when NemoClaw proves that no old authority or evidence can exist, or durably rotates the runtime epoch.
If an old epoch might exist and cannot be durably rotated, `launch` stops before complete preflight or recovery.
Its redacted guidance asks you to repair the current user's secure OS runtime authority and NemoClaw state permissions, then retry.
A failed live check never becomes a successful launch because a lease exists.

Immediately before the first mutation in the complete preflight, the producer revalidates its sandbox-global runtime epoch while holding the sandbox lifecycle lock followed by the owning gateway lock.
It holds both locks through all mutations in the complete preflight, final state capture, and publication.
If another producer has replaced the epoch, the stale producer makes no changes and re-inspects the newer lease.

The 24-hour lifetime does not extend when you launch repeatedly.
Exiting the agent with `/exit` does not revoke the lease.
If state changes before expiry, NemoClaw fences the old evidence and runs the complete preflight.
A successful preflight in that interval keeps the original start and expiry time.
After expiry, a successful complete preflight starts a new 24-hour lease only when publication succeeds.

If unsafe or malformed authority history makes the prior lease timeline untrustworthy, NemoClaw durably invalidates the old epoch and starts one conservative 24-hour quarantine.
Both wall time and monotonic uptime must span the full quarantine, and publication remains disabled during it.
Repeated attempts do not extend the quarantine.
After it elapses, the next successful complete preflight can publish a new fixed 24-hour lease.
You do not create or refresh this lease manually, and `launch` has no lease-control flags.
After lease validation or the automatic fallback that runs the complete preflight, `launch` starts the sandbox's agent in your terminal instead of opening a sandbox shell.

The agent command comes from the sandbox's agent manifest.
If the sandbox registry names a non-OpenClaw agent without a readable local agent manifest, `launch` exits before starting an in-sandbox command.

| Agent | Command |
|---|---|
| OpenClaw | `openclaw tui` |
| Hermes | `hermes` |
| LangChain Deep Agents Code | `dcode` |

```bash
$$nemoclaw launch <name>
```

The sandbox name is required, and the command takes no flags.
The sandbox must already exist in the local NemoClaw state.
If it is not registered locally, `launch` exits before it runs an OpenShell command or readiness recovery and reports that the sandbox is not registered in the local NemoClaw state.
When the agent exits, you return to the host shell.

<AgentOnly variant="openclaw">

`launch` returns the agent's exit code when the post-command OpenClaw permission cleanup succeeds.
If that cleanup cannot inspect, restore, or verify the mutable config permission contract, `launch` fails closed with exit `1` and prints `OpenClaw permission cleanup failed (...)` to `stderr`.

</AgentOnly>
<AgentOnly variant="hermes,deepagents">

`launch` returns the agent's exit code.

</AgentOnly>

When you want a shell inside the sandbox rather than an agent session, use `$$nemoclaw <name> connect`.

### `$$nemoclaw deploy`

<Warning>
The `$$nemoclaw deploy` command is deprecated.
Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `$$nemoclaw onboard` on that host.
</Warning>

Deploy NemoClaw to a remote GPU instance through [Brev](https://brev.nvidia.com).
This command remains as a compatibility wrapper for the older Brev-specific bootstrap flow.
The Brev instance name is the positional argument.
The sandbox name comes from `NEMOCLAW_SANDBOX_NAME` and defaults to `my-assistant`; invalid sandbox names fail before Brev provisioning starts.

```bash
$$nemoclaw deploy <instance-name>
```

### `$$nemoclaw <name> connect`

Connect to a sandbox by name.
Bare `$$nemoclaw connect` (no sandbox name) connects to the registry default.
NemoClaw uses the stored default when it names a non-pending registered sandbox, then falls back to the first non-pending registration.
If only pending registrations remain, the command exits non-zero and tells you to wait for onboarding or remove the incomplete sandbox.
If the registry remains empty after recovery, it tells you to run `$$nemoclaw onboard`.
A registered sandbox literally named `connect` keeps the name-first reading.
If the sandbox is not yet in the `Ready` phase, `connect` polls `openshell sandbox list` every few seconds and prints the current phase. This gives you progress output right after onboarding, when the 2.4 GB image is still pulling, instead of a silent hang.
Control the wait budget with `NEMOCLAW_CONNECT_TIMEOUT` in integer seconds. An interactive connection defaults to `120` seconds, while `--probe-only` and [`$$nemoclaw <name> start`](#$$nemoclaw-name-start) default to `300` seconds so a scripted health check can wait through a cold sandbox start. When the deadline expires, `connect` exits non-zero with the last-seen phase.

On a TTY, a one-shot hint prints before dropping into the sandbox shell.
The hint is agent-aware. It names the correct TUI command for the sandbox's agent and reminds you to use `/exit` to leave the chat before `exit` returns you to the host shell.
Set `NEMOCLAW_NO_CONNECT_HINT=1` to suppress the hint in scripted workflows.
If the sandbox is running an outdated agent version, a non-blocking warning prints before connecting with a `$$nemoclaw <name> rebuild` hint.
If another terminal is already connected to the sandbox, `connect` prints a note with the number of existing sessions before proceeding. Multiple concurrent sessions are allowed.

Without `--probe-only`, `connect` does not pull a model itself, but it does inspect managed-vLLM install variables such as `NEMOCLAW_VLLM_MODEL` and `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` if you exported them in the same shell.
An unknown model slug, malformed extra-args JSON, or a gated model (for example `deepseek-r1-distill-70b`) with no `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN` exits non-zero with the same error the installer would emit, before any sandbox readiness probe or SSH attach.
Unset the managed-vLLM variable, or fix the value, before retrying a regular connection.
`connect --probe-only` skips this install preflight so stale managed-vLLM variables cannot block recovery.

<AgentOnly variant="openclaw">
For a portable experimental-profile sandbox with the recorded `ollama-local` provider, `connect --probe-only` probes `http://127.0.0.1:11434/api/tags` before it decides whether to start Ollama.
If the API is unhealthy and the ownership receipt is valid, it starts the fixed user-local Ollama executable with `serve`.
An installation made before the ownership receipt was introduced is not claimed automatically.
After you verify that `${HOME}/.local/bin/ollama` is the executable you intend NemoClaw to manage, run `NEMOCLAW_PORTABLE_OLLAMA_REENROLL=1 nemoclaw <name> recover` once to record it explicitly.
The command rejects a symlink or non-executable file before it records ownership.
It refuses to launch a duplicate when another `ollama` process exists but the API remains unhealthy.
After a launch, it waits up to 30 seconds for valid `/api/tags` JSON with a `models` array.
It then verifies the authenticated proxy and requires HTTP 2xx from the sandbox `inference.local/v1/models` route before it exits successfully.
If Ollama does not become healthy within 30 seconds, the command identifies the exact receipt-bound executable and its `serve` argument, then tells you to retry recovery.
The command does not take over a system service or an unrelated user-managed Ollama daemon.
</AgentOnly>

Before reading or changing the live OpenShell gateway inference route, `connect` verifies the shared provider and sandbox metadata.
When the live route differs and the metadata is compatible, `connect` warns and re-points the route to the target sandbox's recorded provider and model.
Refer to [Use Shared Gateway Routes](../inference/manage-inference/use-shared-gateway-routes) for provider-global identity, route drift, and hard-error recovery.
Use `$$nemoclaw inference set --provider <provider> --model <model>` to make an intentional compatible route change outside the connect flow.
Before it opens SSH, `connect` probes `https://inference.local/v1/models` from inside the sandbox with the selected agent's trusted CA and proxy context.
HTTP `200` through `499` confirms that the route is reachable.
When the probe returns a recognized broken result, `connect` attempts DNS or route repair and verifies the route again.
When the initial probe cannot return a trusted result, `connect` fails closed before health-driven repair and before opening SSH.
It prints a bounded, redacted last-probe detail and points you to `$$nemoclaw <name> doctor`.
If the sandbox is registered locally but missing from a healthy gateway, `connect` preserves the registry entry and points you to `rebuild --yes`, `onboard`, or `destroy` instead of deleting the metadata needed for recovery.

After a host reboot, the OpenShell gateway rotates its SSH host keys.
`connect` detects the resulting identity drift, prunes stale `openshell-*` entries from `~/.ssh/known_hosts`, and retries automatically.
You no longer need to re-run `$$nemoclaw onboard` after a reboot in this case.

```bash
$$nemoclaw my-assistant connect [--probe-only]
$$nemoclaw connect
```

On Linux, the `--probe-only` flag is the infrastructure producer for launch-readiness evidence.
It validates a usable lease and exits without duplicate recovery.
Otherwise, it fences prior evidence, waits for the sandbox, verifies or repairs its in-sandbox agent process and host-side forwards, and publishes evidence only after every probe succeeds.
It rechecks the sandbox on its recorded OpenShell gateway after the readiness wait and never restarts the shared host gateway.
If an old runtime epoch might exist and cannot be durably rotated, the command exits nonzero before complete preflight or recovery and gives redacted repair guidance.
A securely absent runtime authority and receipt let ordinary `launch` run the complete preflight without optimization if new authority creation fails, but on Linux `connect --probe-only` still exits nonzero because it could not publish launch-readiness evidence.
A runtime failure and, on Linux, a failure to publish evidence for an otherwise healthy runtime also exit nonzero with different diagnostics.

Infrastructure must run the command as the same final numeric user that later runs `launch`.
Run it only after the final durable home and state volume is mounted and after policy and network provisioning is complete.
On Linux, that user also needs a secure, independently writable OS per-user runtime authority under `/run/user/<numeric-uid>`.
Do not redirect this authority with caller environment variables.
Do not use a graphical or login-session identifier as the deployment ordering boundary.
On macOS, `connect --probe-only` runs the complete preflight, including recovery and probes.
After a successful probe and recovery, it prints a note that launch-readiness evidence is unavailable on this platform and exits zero.
The next `launch` runs the complete preflight.
On Linux, the publication-failure diagnostic is redacted and does not print filesystem paths or environment values.
Run it for health checks and scripted readiness probes; users continue to run only `$$nemoclaw launch <name>`.

Use [`$$nemoclaw launch <name>`](#$$nemoclaw-launch-name) when you want launch-readiness validation, an automatic fallback that runs the complete preflight, and then the agent instead of a sandbox shell.

### `$$nemoclaw <name> exec`

Run a single command non-interactively in a running sandbox via the OpenShell exec endpoint.
The command runs as the sandbox user with `HOME=/sandbox`, so in-sandbox tooling resolves NemoClaw-provisioned config the same way it does for `connect` and `openshell sandbox connect`.
This is the supported substitute for `docker exec` on the sandbox container; raw `docker exec` runs as root and lands on `HOME=/root`, where the selected agent config is not present.
For a registered sandbox, NemoClaw selects its recorded owning OpenShell gateway before the workdir probe and command dispatch.
If gateway selection fails, `exec` stops without running the sandbox command.

<AgentOnly variant="openclaw">

OpenClaw config resolves under `/sandbox/.openclaw`.

Run one OpenClaw turn with `$$nemoclaw my-assistant exec -- openclaw agent --agent main -m "What is 2+2?"`.
List the default OpenClaw workspace with `$$nemoclaw my-assistant exec --workdir /sandbox/.openclaw/workspace -- ls -la`.

</AgentOnly>
<AgentOnly variant="hermes">

Hermes config resolves under `/sandbox/.hermes`.

```bash
nemohermes my-assistant exec -- hermes --version
nemohermes my-assistant exec --workdir /sandbox/workspace -- ls -la
```

</AgentOnly>

Everything after `--` is forwarded verbatim to the sandbox command, including flags the inner command needs.

<AgentOnly variant="openclaw">

After an OpenClaw one-shot command exits, NemoClaw verifies and, when needed, restores the mutable config permission contract.
When cleanup succeeds, `exec` returns the remote command's exit code.
If cleanup cannot inspect, restore, or verify that contract, it fails closed and prints `OpenClaw permission cleanup failed (...)` to `stderr`.
In that case, `exec` returns the cleanup failure instead of the remote command's status.

For a registered OpenClaw sandbox with a selected owning managed gateway, a successful direct `openclaw pairing approve googlechat <code>` command also restarts that gateway after cleanup so the new sender allowlist applies to the next message.
If cleanup or restart fails after the approval commits, `exec` exits with status `1` and reports that the approval was not rolled back.
When an owning gateway was selected, correct any reported cleanup problem, then run `$$nemoclaw <name> gateway restart` before testing the next message.
Without an owning managed gateway, NemoClaw does not attempt activation or print a managed restart command; unregistered and non-OpenClaw sandboxes also do not receive the automatic restart.

</AgentOnly>
<AgentOnly variant="hermes">

The exit code is the remote command's exit code.

</AgentOnly>

By default, NemoClaw inherits caller stdin only when it is a terminal.
Non-terminal or unavailable stdin is closed so SSH, CI, and other one-shot commands cannot wait on an inherited pipe.
Pass `--stdin` to forward an intentional pipe, or `--no-stdin` to close terminal stdin explicitly.

```bash
printf 'hello\n' | $$nemoclaw my-assistant exec --stdin -- cat
ssh dgx-spark '$$nemoclaw my-assistant exec --no-stdin -- pwd'
```

OpenShell preserves line endings and quote characters inside each command argument, so inline scripts and heredocs can be passed as one argument after `--`.
For example, a shell variable keeps the multi-line script in one argv element:

```bash
script=$'cat <<\'EOF\'\nline one\nline two\nEOF'
$$nemoclaw <name> exec -- bash -lc "$script"
```

NUL bytes are still rejected in command arguments.
Line breaks are accepted only in command argv: `--workdir` remains single-line, and NemoClaw does not expose OpenShell request-environment injection on this command.

| Flag | Description |
|------|-------------|
| `--workdir <dir>` | Working directory inside the sandbox. The directory is checked before the command runs; if it does not exist, NemoClaw reports `error: --workdir: <dir> does not exist inside the sandbox` and exits with status `1` without invoking the inner command. |
| `--tty` / `--no-tty` | Allocate a pseudo-terminal; defaults to auto-detection (on when stdin and stdout are terminals) |
| `--timeout <seconds>` | Timeout in seconds (`0` means no timeout) |
| `--stdin` / `--no-stdin` | Force caller stdin forwarding or closure (default: inherit terminal stdin; close non-terminal or unavailable stdin). |

### `$$nemoclaw <name> agent`

<AgentOnly variant="openclaw">

Run one agent turn non-interactively in a running sandbox.
For OpenClaw sandboxes, this command forwards arguments to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`.
For terminal-runtime sandboxes, NemoClaw forwards arguments to the manifest-declared interactive command; LangChain Deep Agents Code sandboxes run `dcode ...`.
Use this when driving the sandbox programmatically from another process (CI job, multi-agent platform, evaluation harness) rather than from an interactive terminal.

All flags accepted by the selected in-sandbox agent CLI are forwarded verbatim, so the upstream surface stays the single source of truth.

OpenClaw invocations must include at least one target selector: `--agent`, `--session-id`, `--session-key`, or `--to`.
This keeps the wrapper from falling back to the unspecified default-session behaviour.
Conflict resolution between multiple selectors is delegated to the in-sandbox `openclaw agent` argv contract; the host-side guard only checks presence.

```bash
$$nemoclaw my-assistant agent --agent main -m "Summarise README.md"
$$nemoclaw my-assistant agent --agent main -m "Status update?"
$$nemoclaw my-assistant agent --session-id review-42 -m "Any new findings?"
$$nemoclaw my-assistant agent --session-key intake-42 --json -m 'ping'
$$nemoclaw dcode-sandbox agent --help
$$nemoclaw dcode-sandbox agent -n "Summarize this repository"
$$nemoclaw dcode-sandbox agent -n "Summarize this repository" --json
```

For non-JSON OpenClaw turns, the wrapper captures `stdout` and `stderr` and replays them only after the in-sandbox command exits.
The combined capture limit is `64 MiB`; exceeding it reports an OpenShell invocation error and exits with status `1`.
If the captured output contains an embedded-fallback marker, the wrapper suppresses both streams, prints `recover`, `rebuild --yes`, and `onboard --resume` guidance to `stderr`, and exits with status `1`.
Otherwise, it writes the captured output to the corresponding host streams and returns the OpenShell command's exit status.
The in-sandbox NemoClaw plugin writes its registration banner to `stderr`, so the banner does not prefix the agent reply on `stdout` in non-JSON mode.
Because a delivered turn always writes to one of the two streams, the wrapper reports a dispatch with status `0` and no output as a failure.
The wrapper prints recovery guidance to `stderr` and exits with status `1`.
Pressing `Ctrl+C` interrupts the OpenShell child, and sending `SIGTERM` to the host wrapper forwards `SIGTERM` to that child.
NemoClaw waits for OpenShell to stop the in-sandbox turn, replays captured output, and returns status `130` for `SIGINT` or `143` for `SIGTERM`.
When the forwarded argv sets `openclaw agent --timeout <seconds>`, both captured paths bound the OpenShell command at that value plus 30 seconds.
The extra seconds let the in-sandbox turn report its own timeout first, so the host bound catches only a turn that stops answering.

These leave the OpenShell wait unbounded:

- `--timeout 0`.
- A value NemoClaw cannot read as a positive whole number of seconds.
- An argv without `--timeout`.
- An unrecognized option before `--timeout`, because NemoClaw does not infer a host deadline outside the documented OpenClaw option grammar.
- A `--timeout` after the `--` argv terminator, which OpenClaw reads as payload rather than as its own flag.

When the captured output reports that the turn's deadline fired, the wrapper replays the partial output and writes deadline guidance to `stderr`.
It exits with status `1` instead of the upstream status `0`.
The diagnostic shell-quotes the sandbox name and forwarded arguments, then redacts detected credential values before writing the recovery command to `stderr`.
If redaction changes the recovery command, the diagnostic tells you not to replay it; otherwise, it labels the command as runnable inside the sandbox.
For a registered sandbox, both captured paths pin the sandbox's recorded gateway with an explicit `-g`.
Neither path forwards an interactive terminal on `stdin`; a genuine pipe or redirect is still passed through, so `printf 'ping' | $$nemoclaw my-assistant agent --agent main` keeps working.
When the top-level OpenClaw `--json` output flag is present, the wrapper uses a captured no-TTY path with a `64 MiB` buffer so `stdout` stays parseable JSON.
Raw `stderr`, including structured JSON diagnostics, is forwarded unchanged.
NemoClaw appends failed-tool or untrusted-child provenance only from the `stdout` JSON.
The wrapper reads completion markers only from the final matching OpenClaw response envelope: a local `{ payloads, meta }` response or a gateway `{ status, result: { payloads, meta } }` response.
It ignores earlier JSON progress or log records.
It exits with status `1` when that metadata contains `error.kind: "incomplete_turn"`, `livenessState: "abandoned"`, `replayInvalid: true`, or a `timeoutPhase` value, even when the envelope reports success.
Marker-shaped values inside tool results, tool-call arguments, or other descendants do not change the exit status.
A turn can run every tool successfully and still become abandoned before it produces a reply.
The wrapper writes the unchanged JSON trace to `stdout` before it reports the incomplete turn, so the partial tool trace remains available.
The wrapper writes the verdict, the detected markers, and verify-before-retry guidance to `stderr`.
A `timeoutPhase` value names the phase the deadline fired in, so the wrapper writes deadline guidance in place of the generic incomplete-turn text.
Tool calls in a partial trace may have already applied side effects, so verify what the turn changed before you retry it.
The wrapper passes through an upstream non-zero exit status unchanged.
Literal `--json` values consumed by flags such as `-m` or `--reply-channel`, or arguments after `--`, stay on the normal passthrough path.
Documented value flags written as `--flag=value`, such as `--session-id=s1`, are recognized the same way as separated value flags.
If an unrecognized OpenClaw option appears before `--json`, NemoClaw also keeps the command on the normal passthrough path so OpenClaw remains the argv source of truth.

Common OpenClaw flags include `-m <text>`, `--session-id <id>`, `--agent <id>`, `--model <id>`, `--thinking <level>`, `--json`, `--deliver`, `--reply-channel <channel>`, and `--timeout <seconds>`.
For OpenClaw sandboxes and registry fallbacks, `$$nemoclaw <name> agent --help` prints the wrapper-level summary locally.
Invoke `$$nemoclaw <name> exec -- openclaw agent --help` to view the upstream OpenClaw help text directly.
For registered terminal-runtime sandboxes, bare invocations and `--help` are forwarded to the terminal command, so a LangChain Deep Agents Code sandbox receives `dcode` for `$$nemoclaw <name> agent` and `dcode --help` for `$$nemoclaw <name> agent --help`.

Host-side validation runs before the sandbox dispatch:

- OpenClaw sandboxes and registry fallbacks must include at least one target selector flag: `--agent`, `--session-id`, `--session-key`, or `--to` in either `--flag value` or `--flag=value` form. OpenClaw invocations without a selector exit `2` and print `No target session selected` locally, without paying the in-sandbox dispatch cost. Registered terminal-runtime sandboxes delegate bare invocations and help flags to the manifest command instead.
- If the sandbox is registered but not in a `Ready` or `Running` phase, the wrapper exits `1` and prints the documented recovery commands (`$$nemoclaw <name> recover`, `$$nemoclaw <name> rebuild --yes`, `$$nemoclaw onboard --resume`) rather than deferring the readiness rejection to `openshell sandbox exec`.
- If a recent timed shields window auto-restored before the one-shot OpenClaw command, the wrapper prints a stderr-only reminder such as `Shields auto-relocked` with the matching `$$nemoclaw <name> shields down --timeout ...` command before dispatch. JSON stdout stays parseable, and the warning is advisory because current scope state still belongs to OpenClaw and OpenShell.

</AgentOnly>
<AgentOnly variant="hermes">

The `agent` wrapper rejects Hermes sandboxes with guidance for the Hermes HTTP API.
Each Hermes sandbox exposes an OpenAI-compatible API inside the sandbox on its own port, which defaults to `8642`, so non-interactive use does not need a wrapper command.
When another sandbox or a host listener already holds `8642`, the sandbox receives the next free port from `8642` through `8652`.
The rejection message names that port and the `openshell forward start` command for it.
Run `openshell forward list` to read the host bind for each of that sandbox's forwards.

Forward the port and POST chat completions directly:

```bash
openshell forward start --background 8642 my-hermes
curl -sN http://127.0.0.1:8642/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"<onboarded-model>","messages":[{"role":"user","content":"What is 2+2?"}],"stream":true}'
```

</AgentOnly>
<AgentOnly variant="deepagents">

For Deep Agents sandboxes, `agent` forwards to the manifest-declared terminal command.
Bare invocations run `dcode`, and `--help` runs `dcode --help`.
Use `dcode -n` for explicit headless automation when you are already connected to the sandbox, or use `$$nemoclaw <name> agent -n "<task>"` from the host.
Add `--json` to either form for one managed, versioned JSON envelope on stdout.
The host wrapper forwards the flag to `dcode`.
For the schema, status and exit behavior, and 1 MiB output limit, refer to [Run Deep Agents Code](/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code).
The host wrapper keeps `HOME=/sandbox`, the managed proxy environment, and the manifest-declared Deep Agents config path aligned with `connect`.
Interactive `$$nemoclaw <name> agent` launches the same terminal TUI as `dcode`.
Headless `$$nemoclaw <name> agent -n "<task>"` uses the managed headless boundary, where non-shell tools can auto-run without the interactive approval UI.

</AgentOnly>

### Advanced Sandbox Maintenance Commands

The following commands are available for targeted host-side maintenance, but they are not part of the top-level public command list.

#### `$$nemoclaw <name> config get`

Read the sanitized agent configuration from a sandbox.
The output removes credential-bearing sections before printing.
Use `--key` to read one dotpath and `--format` to choose JSON or YAML output.

```bash
$$nemoclaw my-assistant config get
$$nemoclaw my-assistant config get --key model --format yaml
```

| Flag | Description |
|------|-------------|
| `--key <dotpath>` | Print one value from the sanitized config |
| `--format json\|yaml` | Output format. Defaults to JSON |

#### `$$nemoclaw <name> config set`

<AgentOnly variant="openclaw,hermes">

Write one value into the agent configuration in a sandbox.
The command validates every HTTP and HTTPS URL in the value, including URLs nested inside JSON objects or arrays.
It pins an HTTP host to the validated IP address.
Configuration changes are unavailable while shields are up, so lower shields with `$$nemoclaw <name> shields down` first.

```bash
$$nemoclaw my-assistant config set --key agents.defaults.model.primary --value nvidia/nemotron
$$nemoclaw my-assistant config set --key agents.defaults.timeoutSeconds --value 600 --restart
```

| Flag | Description |
|------|-------------|
| `--key <dotpath>` | Dotpath to update in the config. Required |
| `--value <value>` | Value to write. The command parses a JSON value when it can, and otherwise writes the text as a string. Required |
| `--restart` | Restart a supported OpenClaw or Hermes gateway after writing |
| `--config-accept-new-path` | Write a dotpath that does not already exist in the config |

The command treats a dotpath that does not already exist in the config as a possible typo.
An interactive run asks for confirmation before writing the new dotpath.
A run without a TTY, or a run with `NEMOCLAW_NON_INTERACTIVE=1`, refuses the write.
Pass `--config-accept-new-path`, or set `NEMOCLAW_CONFIG_ACCEPT_NEW_PATH=1`, to write the new dotpath without the confirmation.
If the confirmation reaches the end of input, for example when you press `Ctrl-D` or run the command from a harness that closes stdin, the command exits non-zero without writing and repeats the same guidance.

The command refuses to write `gateway` or any dotpath under `gateway.`, which holds credentials.

</AgentOnly>
<AgentOnly variant="hermes">

For Hermes, the command validates the complete candidate configuration with the bundled Hermes schema before it writes configuration or integrity metadata.
An incomplete structural object is rejected without changing the configuration or hashes.
Private URLs remain rejected unless the existing Hermes configuration explicitly sets `security.allow_private_urls: true`.
That opt-in allows private URLs for any Hermes configuration value. Public hostnames still receive DNS validation and pinning.
Hermes can restart its gateway when it applies a configuration change. Use `--restart` when the command must request and verify that restart.
`config set` changes `config.yaml` only. Hermes startup and rebuild can update managed `.env` keys and their integrity hashes without printing their values.

</AgentOnly>
<AgentOnly variant="deepagents">

For Deep Agents sandboxes, `config set` is unavailable because the `dcode` configuration is baked into the sandbox image at build time.
Run `$$nemoclaw onboard --agent dcode --name <sandbox-name> --fresh` when you need to change it.
Use `$$nemoclaw <name> config get` to read the current values.

</AgentOnly>

#### `$$nemoclaw <name> shields`

Manage the sandbox config lockdown posture from the host.
Use `shields status` to inspect the current state, `shields up` to lock the sandbox config and restore the captured restrictive policy, and `shields down` to temporarily unlock the config for maintenance.

<AgentOnly variant="openclaw,hermes">

For the full mutability matrix, refer to [Understand Runtime Changes](../manage-sandboxes/configure-sandboxes/understand-runtime-changes).

</AgentOnly>

```bash
$$nemoclaw my-assistant shields status
$$nemoclaw my-assistant shields up
$$nemoclaw my-assistant shields down --timeout 5m --reason "maintenance"
```

| Subcommand | Description |
|------|-------------|
| `shields status` | Show whether lockdown is configured, active, temporarily unlocked, or in error |
| `shields up` | Lock the sandbox config and restore the saved restrictive policy |
| `shields down` | Temporarily unlock the sandbox config. Supports `--timeout`, `--reason`, and `--policy` |

If OpenShell rejects the permissive policy before it is applied, `shields down` returns an error and keeps the sandbox in the Shields up state.
The command clears the provisional Shields down record and timer, and `shields status` remains `UP`.
If that record cannot be cleared and NemoClaw writes the rejection marker, `shields status` derives `UP` from that marker.
The auto-restore timer and transition remain the recovery authority.
If the rejection marker also cannot be written, `shields status` reports the incomplete transition as an error.

If a config path is unsafe, for example a symlink at the Hermes `config.yaml` path, `shields down` refuses that path before it weakens policy, writes a provisional Shields down record, or starts a timer.
The command returns an error and `shields status` remains `UP`.
If an unsafe path appears after the preflight and a provisional Shields down record already exists, the command restores the restrictive policy when it can but keeps the Shields down record until config protection is positively re-verified. This fail-closed behavior also applies when unlock fails after a partial mutation, and requires manual intervention if re-lock cannot be confirmed.

If `shields up` reports that the config remains unlocked or drifted, confirm that the sandbox is running and ready, then retry `$$nemoclaw <name> shields up`.
If the retry still fails, rebuild a known-good baseline with `$$nemoclaw <name> rebuild --yes`.

<AgentOnly variant="deepagents">

A `CRITICAL` Deep Agents config-lock failure is not an ordinary unlocked or drifted result.
The retry and rebuild guidance above does not apply to a `CRITICAL` Deep Agents config-lock diagnostic.
Do not retry `shields up` or attempt an in-sandbox repair.
Follow [Deep Agents Config Lock Failure Recovery](troubleshooting#deep-agents-config-lock-failure-recovery) to restore a trusted snapshot or recreate the sandbox before retrying.

</AgentOnly>

Host-side config and inference writes, snapshot mutation, sandbox destruction, and shields transitions serialize per sandbox.

<AgentOnly variant="openclaw,hermes">

Host-side gateway recovery uses the same per-sandbox serialization.

</AgentOnly>

<AgentOnly variant="hermes">

For a current NemoClaw-managed Hermes image on the Docker driver, `shields status` is a recovery and reconciliation command, not only a display command.
It first recovers any retained exact runtime provider state mutation, then applies and verifies the declared recursive posture.
A result exits with status `0` only after the command verifies that posture.
A status check can therefore complete work retained by an interrupted host process.

If provider recovery restores lockdown while the persisted Shields posture still says mutable, status prints `ERROR (runtime-provider recovery restored lockdown)`, exits with status `2`, and tells you to retry the intended Shields transition.
If live verification of a mutable default or timed Shields down posture fails, status prints `NOT CONFIGURED (DRIFTED...)` or `DOWN (DRIFTED...)`, exits with status `2`, and directs you to run `$$nemoclaw <name> shields up` to reconcile and verify lockdown.
Status does not report `UP`, `DOWN`, or mutable-default with exit status `0` when the provider cannot verify the exact recursive posture.

While an exact provider fence is active, ordinary direct-container, SSH, and OpenShell command transports are refused before a sandbox process starts.
They report `Runtime provider state mutation owns direct-container execution for sandbox '<name>'; retry after the provider fence is released.`
Recover and retry as follows:

1. Let the active Shields or recovery command finish.
2. Run `$$nemoclaw <name> shields status`.
3. Retry the original command only after provider verification completes and the command exits with status `0`.

Older managed Hermes images use the sealed-plan transition only when the current provider capability is proved absent.
Custom images and legacy Dockerfile workflows remain on their existing transition contract and do not use `provider-state-mutation-v2`.

</AgentOnly>

Before `shields down` opens a new window, NemoClaw must revoke any stale auto-restore timer authority.
If marker cleanup fails, the command reports `Cannot revoke stale auto-restore timer authority` and stops before policy capture, state writes, config unlock, replacement-timer startup, or audit writes.
The sandbox retains its existing configuration and policy posture, and the stale timer authority remains.
Resolve the reported timer-marker error on the trusted host, then retry `shields down`.
When a timed shields-down window reaches its deadline, auto-restore closes the per-sandbox lifecycle deadline gate.
The gate blocks new mutations and waits for the recorded live owner to release its exact lock generation before auto-restore restores lockdown.
NemoClaw does not signal that process because portable process inspection cannot prove that all descendants stopped.
An interactive command can take over an expired timer.
Interactive recovery has separate transition-takeover and restoration phases.
Each phase makes up to 7 attempts and waits 5 seconds between failures, for up to 30 seconds of retry delay per phase.
Detached recovery uses one 7-attempt budget across deadline setup, main-generation publication, and restoration.
The deadline gate remains closed during those attempts.
If restoration cannot commit, NemoClaw attempts to record durable containment.
If that containment commit also fails, NemoClaw retains any exact lifecycle and deadline gates it already owns.
A state-directory failure that prevented gate publication also prevents normal mutation-lock acquisition.
Correct the reported state-directory write failure, then run `$$nemoclaw <name> shields status` to resume recovery or receive exact-generation recovery guidance.
When recovery cannot complete, an interactive command returns an error, or the detached timer exits with a failure status.
NemoClaw also records durable containment when an owner exits before it can prove that the owner's descendants stopped, or when ownership becomes ambiguous.
Durable containment, retained exact gates, or the fail-closed state-directory error blocks new mutations until you complete exact-generation operator recovery.
Stop all NemoClaw processes for the sandbox, then follow the paths, identities, tokens, and removal order in the reported error.
Verify each recorded generation is unchanged, remove only the exact stale generations first, and remove the exact containment generation last.

Before a manual Shields transition replaces a policy, NemoClaw requires exact agreement among the sandbox registry, generated-policy record, and live gateway policy.
`shields down` carries the proven managed MCP policy entries into the relaxed policy.
Restoration removes snapshot-time managed MCP entries before it overlays current exact entries.
If exact agreement is absent, a manual Shields transition refuses the replacement policy.
At an expired deadline, auto-restore omits unproven managed MCP policy entries, restores lockdown, and records the omission count in its audit entry.
An MCP server removed during the shields-down window stays removed.
A surviving server keeps its recorded endpoint and address pins while its policy ownership remains exact.

<AgentOnly variant="openclaw,hermes">

### `$$nemoclaw <name> recover`

Repair a stopped in-sandbox gateway and re-establish host-side forwards without opening an SSH session.
Use this after a sandbox crash or whenever `$$nemoclaw <name> status` reports that the sandbox container or agent gateway is not running.

For a stopped, non-paused Docker-driver container, `recover` starts the existing container before it waits for OpenShell readiness.
It leaves a running or paused container unchanged.
If Docker cannot start the container, `recover` continues to the readiness check and reports the resulting failure.

`recover` waits up to 30 seconds to acquire the per-sandbox lifecycle lock.
After acquisition, it holds the lock until gateway recovery and forward repair finish.

For built-in OpenClaw and Hermes sandboxes, `recover` sends an authenticated lifecycle request through registry-scoped privileged direct-container control.
The host selects the controller from the live container topology.
In a direct root-entrypoint container, the request reaches the root PID 1 supervisor.
In an OpenShell-managed container, the request enters the root-owned mode `0500` managed controller through a sanitized root exec while OpenShell remains PID 1.
It does not use ordinary `openshell sandbox exec` or an in-sandbox manual relaunch as a fallback.
When the root-owned managed controller attests two unchanged zero-supervisor process scans with a stable PID 1 and reports `SUPERVISOR_NOT_RUNNING`, a local Docker-driver sandbox with the legacy keepalive startup can enter a transactional container recreation.
The recreation uses a credential-free managed startup command, pins the registered container identity, and retains the previous container for rollback.
Before recreation, NemoClaw backs up the state directories and files declared by the agent manifest.
NemoClaw waits for the exact replacement to pass managed gateway health and OpenShell re-registration before it restores state.
After state restoration, it restarts the gateway in the exact replacement container and requires an authenticated `ok` result.
It then runs the managed settle check.
It commits only after the replacement identity, state restoration, gateway restart, and settle check pass.
If OpenShell re-registration, state restoration, or a later gateway check fails, NemoClaw attempts to roll back the replacement.
The primary dashboard or API host forward stays stopped.
NemoClaw removes the temporary state backup after a successful restore or rollback.
If state restoration and rollback both fail, it retains the backup and prints host recovery guidance.
Mounted state remains available, but a committed swap does not retain other writable-layer changes.
It is idempotent.
When `recover` repairs a stopped built-in OpenClaw or Hermes gateway, it repeats the recovery action only for these exact transient results:

- Status `1` with blank stdout and exactly one stderr line, `SUPERVISOR_BUSY`.
- Status `137` with blank stdout and stderr.
- Status `1` with blank stdout and exactly one stderr line, `Error response from daemon: Container <id> is restarting, wait until the container is running`.

For the Docker result, `<id>` must be a 64-character lowercase hexadecimal ID that matches the selected registry-owned container.
Recovery makes at most 11 controller attempts in total.
It stops after 3 of those attempts return `SUPERVISOR_BUSY`.
Managed settle confirmation treats exact `SUPERVISOR_BUSY` as inconclusive within its configured window.
Status `137` and the Docker restart result remain terminal during that confirmation.
The managed supervisor startup waiter accepts the two container-transition results within its separate 11-attempt bound.
Unbound container IDs, reformatted Docker errors, status `137` with nonblank output, and other diagnostic results are terminal.
NemoClaw treats `SUPERVISOR_UNAVAILABLE` as terminal because the managed controller uses it for integrity refusals, ambiguous discovery, and process-identity changes.
It does not repeat the recovery action or treat the settle probe as inconclusive, and instead prints host-side restart and rebuild guidance.
Other controller failures also stop immediately.
If the gateway is already running, the command exits zero without force-restarting it; it can still re-evaluate supported safety checks and check or recover host-side forwards.
Use [`$$nemoclaw <name> gateway restart`](#$$nemoclaw-name-gateway-restart) when you deliberately need a running gateway to reload runtime configuration or plugins.

```bash
$$nemoclaw my-assistant recover
```

</AgentOnly>

<AgentOnly variant="openclaw">

For a portable experimental-profile sandbox with the recorded `ollama-local` provider, `recover` also runs the ownership-bound Ollama checks described for [`connect --probe-only`](#$$nemoclaw-name-connect).
Before it reports success, every completion path verifies the authenticated proxy on port `11435` and requires HTTP 2xx from `inference.local/v1/models`.

</AgentOnly>

<AgentOnly variant="hermes">

`recover` re-evaluates the documented Hermes secret boundary against `/sandbox/.hermes/.env` and the supervisor runtime environment on every run, including when the gateway is already healthy.
If the file contains raw secret-shaped values (for example a pasted Telegram, Discord, or Slack bot token in place of the expected `openshell:resolve:env:<name>` placeholder), the command exits non-zero and prints the offending key.
The direct root-entrypoint supervisor stops a running gateway after this refusal, while the managed controller refuses before signaling the observed child.
Replace each flagged value with the `openshell:resolve:env:<name>` placeholder and re-run.
The direct root-entrypoint supervisor verifies the strict root-owned config hash.
The managed controller verifies that strict hash when both Hermes config inputs are root-owned and locked.
Mutable config under the managed topology has no durable root-owned hash anchor and retains the same trust and time-of-check/time-of-use limits as managed cold start.
If the boundary validator or supervisor helper is missing, recovery fails closed, names the sandbox, explains that `/sandbox/.hermes/.env` could not be re-evaluated, and leaves an otherwise healthy gateway untouched.
Rebuild an older sandbox image with `$$nemoclaw <name> rebuild --yes` before retrying.

While a NemoClaw cron restore gate exists, Hermes `recover` keeps the same lifecycle lock through restore validation and gate release.
That controller call has a 130-second host timeout; the earlier 30-second limit applies only to lifecycle-lock acquisition.

After gateway and forward recovery, Hermes `recover` also checks for a NemoClaw cron restore gate retained by an interrupted rebuild.
It validates the restored cron jobs and scripts before it clears that gate, and it leaves an independent Hermes operator drain active.
A validation failure leaves the NemoClaw gate in place so new Hermes turns and cron dispatch remain blocked.

</AgentOnly>

<AgentOnly variant="openclaw,hermes">

The privileged control path requires a running direct sandbox container that belongs to the named registry entry.
Supported built-in images use either a direct root entrypoint or the OpenShell-managed process shape with OpenShell as PID 1 and exactly one nonroot `nemoclaw-start` supervisor.
An arbitrary nonroot entrypoint that does not match the supported OpenShell-managed process shape fails with the `privileged control unavailable` failure layer.
Kubernetes and other deployments without a matching direct container also fail with that layer.

### `$$nemoclaw <name> gateway restart`

Force-restart the supported in-sandbox gateway process through the controller for the live container topology.
Use this after runtime configuration or plugin changes that the agent reads only at gateway startup, such as Hermes Langfuse plugin settings.
Unlike `recover`, this command restarts a healthy gateway instead of exiting after the health probe.

```bash
$$nemoclaw my-assistant gateway restart [--quiet|-q]
```

On success, the command reports that the gateway was restarted, health passed, and forwards were checked or recovered.
It also checks the dashboard forward, messaging forward, and manifest-declared agent forwards.
`--quiet` suppresses progress lines but still prints refusal diagnostics.
In the direct root-entrypoint topology, PID 1 stops only the gateway child whose process ID and process start identity match the tracked child, applies the restart seal, and launches the replacement under the separate `gateway` UID.
In the OpenShell-managed topology, the installed root controller verifies a stable OpenShell to `nemoclaw-start` to gateway process shape, holds a root-only lifecycle lock, publishes one root-owned exit authorization bound to the exact gateway process ID, kernel start identity, and live controller identity, pidfd-targets the observed child, waits for the nonroot entrypoint supervisor to respawn it under the sandbox UID, and proves the replacement listener and HTTP health.
That managed process proof prevents PID reuse from redirecting the signal but cannot establish provenance against a malicious same-UID process or create gateway and agent UID isolation.
For Hermes, the entrypoint supervisor also owns the dashboard process, internal API relay, dashboard relay, and gateway log stream.
The managed nonroot supervisor continuously repairs those processes, stops an alive but deaf gateway after four consecutive failed health checks, and quarantines relaunch after five unexpected exits or failed replacement candidates within 60 seconds until sandbox recreation.
That authorization keeps an authenticated host-requested exit out of the crash budget while its exact root controller remains live; it records host intent for the exit but does not claim that the host signal was the only possible cause in the shared-UID topology.
The host repairs only the host-side OpenShell forwards after the supervisor reports a healthy gateway.

</AgentOnly>

<AgentOnly variant="hermes">

For Hermes, both controllers validate `/sandbox/.hermes/.env` against the secret-boundary guard and validate the supervisor runtime environment before restart.
The direct root-entrypoint supervisor verifies `/sandbox/.hermes/config.yaml` and `.env` against the root-owned strict hash and relaunches the process as the `gateway` user.
The managed controller verifies the strict hash when both config inputs are root-owned and locked, but mutable managed config retains cold-start-equivalent trust and time-of-check/time-of-use limits.
Neither controller recomputes a trusted strict hash to adopt direct in-sandbox edits.
Use supported host commands such as `$$nemoclaw <name> config set` and `$$nemoclaw inference set` for intended runtime configuration changes because those commands update the managed config metadata together.
When a strict hash is available and does not match, the command reports the `config hash mismatch` failure layer.
Hermes host config writes, shields transitions, and lifecycle seals share one root-only mutation lock.
Config writes are bound to the digest of the matching read and atomically refresh the strict and compatibility hashes before the prior ownership and mode posture is restored.
The shields transition keeps that lock through recursive filesystem updates, verification, and content-seal capture, and replaces sensitive inodes before lockdown.
If a concurrent lifecycle request reports `SUPERVISOR_BUSY`, or a config or shields command reports `Hermes config mutation is already in progress`, wait for the active operation to finish and retry.
Run `$$nemoclaw <name> shields down` before a Hermes config or inference change; these commands refuse to mutate a shields-up sandbox.

</AgentOnly>

<AgentOnly variant="openclaw,hermes">

The command can fail at these layers: unsupported agent, privileged control unavailable, supervisor not running, secret-boundary refusal, unsafe config path, config hash mismatch when a strict hash is available, MCP reconciliation refusal, relaunch quarantined, launch failure, health timeout, or forward recovery failure.
`relaunch quarantined` means the in-sandbox supervisor stopped attempting relaunch after a startup refusal or repeated gateway exits, so restart and recovery report the supported repair, `$$nemoclaw <name> rebuild --yes`, instead of a retry.
An older direct-container image without the matching supervisor or managed controller helper reports `privileged control unavailable` and requires `$$nemoclaw <name> rebuild --yes`.
Ordinary OpenShell exec and manual in-sandbox relaunch are not fallback paths.
Terminal agents do not have a gateway runtime and fail as unsupported.

</AgentOnly>

### `$$nemoclaw <name> stop`

Stop the sandbox's Docker container while preserving all of its state.
Workspace files, credentials, network policies, the registry entry, and the OpenShell sandbox record stay in place.
Use this to free CPU, memory, and GPU resources without destroying the sandbox; use [`$$nemoclaw <name> destroy`](#$$nemoclaw-name-destroy) when you want to delete it instead.

```bash
$$nemoclaw my-assistant stop
```

For OpenClaw-managed gateways, the command first asks the in-sandbox gateway to shut down its channels gracefully; agent-managed gateways (for example Hermes) are supervised inside the sandbox and shut down with the container's stop signal.
Then the container stops; a container stuck in a crash loop is stopped the same way, which also disarms its restart policy.
<AgentOnly variant="openclaw,hermes">
After the container stops, NemoClaw attempts to stop that sandbox's host dashboard forward.
If the container does not stop, NemoClaw leaves the dashboard forward running.
</AgentOnly>
The shared host gateway, tunnel services, and any local NIM inference container serve other sandboxes and keep running.
<AgentOnly variant="openclaw,hermes">
Stopping an already-stopped sandbox succeeds and attempts to remove any leftover dashboard forward for that sandbox.
</AgentOnly>
<AgentOnly variant="deepagents">
Stopping an already-stopped sandbox succeeds without changes.
</AgentOnly>
The command controls the local container directly, so it is available for local-container drivers (the default Docker driver and the vm driver) and unavailable for remote drivers such as kubernetes; if the Docker daemon itself is unreachable, the command reports the outage instead of guessing at container state.

### `$$nemoclaw <name> start`

Restart a sandbox container that was stopped with [`$$nemoclaw <name> stop`](#$$nemoclaw-name-stop) or by a host reboot, then repair the in-sandbox gateway and host-side forwards the same way [`$$nemoclaw <name> recover`](#$$nemoclaw-name-recover) does.

```bash
$$nemoclaw my-assistant start
```

Starting an already-running sandbox skips the container start and still runs the gateway and forward health checks.
A paused container is unpaused.
If the container was removed entirely, `start` fails and points you to `$$nemoclaw <name> rebuild`.

<AgentOnly variant="openclaw,hermes">
Before it repairs the gateway and host forwards, `start` waits for OpenShell to report the sandbox in the `Ready` or `Running` state, using the same `300`-second budget and `NEMOCLAW_CONNECT_TIMEOUT` override as `connect --probe-only`.
</AgentOnly>
<AgentOnly variant="deepagents">
Before it verifies the managed terminal runtime, `start` waits for OpenShell to report the sandbox in the `Ready` or `Running` state, using the same `300`-second budget and `NEMOCLAW_CONNECT_TIMEOUT` override as `connect --probe-only`.
</AgentOnly>
When that deadline expires, `start` keeps the existing container, exits non-zero, and prints the `NEMOCLAW_CONNECT_TIMEOUT` value to use on the next run.

After the gateway and forward checks pass, `start` sends one inference request through `https://inference.local` using the sandbox's recorded provider and model.
A gateway that answers the `/v1/models` probe can still reject an inference request or return an invalid result, so the command exits non-zero in either case.
It prints the probe result, including the HTTP status when the route returned one, and points you to the sandbox doctor command.
Each run sends one 16-token request through the stored provider credential, so `start` waits up to 30 seconds for it and consumes provider tokens on a hosted route.
When the sandbox records no provider or no model, `start` skips the request and exits `0`.
`doctor` still classifies an HTTP `401` or `403` route response as reachable, so correct the provider credential when `start` reports one of those statuses.

### `$$nemoclaw <name> status`

Show sandbox-scoped status, health, and inference configuration for one registered sandbox.
Use this form when you care about a specific sandbox's live OpenShell state, agent runtime, inference health, GPU proof, permissions, and recovery hints.
Do not pass a sandbox name to `$$nemoclaw status`; that command is the global all-sandbox/service overview.
NemoClaw resolves the sandbox's recorded owning OpenShell gateway before querying live state.
If another gateway is active, it selects the owner and queries again instead of trusting a result from the sibling gateway.

For a `compatible-endpoint` route that uses `openai-completions`, the text output prints `Reasoning effort` as `low`, `medium`, `high`, or `endpoint-default`.
The line is omitted for another provider or API family.

Pass `--json` to emit a structured per-sandbox report instead of the text renderer.
The JSON output includes at least `schemaVersion`, `name`, `found`, `agent`, `agentDisplayName`, `agentRuntime`, `dcodeAutoApprovalMode`, `model`, `provider`, `recordedRoute`, `liveRoute`, `routeDrift`, `phase`, `gatewayState`, `inferenceHealth`, `rpcIssue`, `hostGpuDetected`, `sandboxGpuEnabled`, `sandboxGpuMode`, `sandboxGpuDevice`, `openshellDriver`, `openshellVersion`, `policies`, `baselineExclusions`, `baselineExclusionStates`, `baselineExclusionTransition`, `failureLayer`, `terminalRuntimeHealth`, `servingProcessHealth`, and `dockerPaused`.
`baselineExclusions` is an array of exact baseline keys recorded for durable replay and is empty when the sandbox has none.
`baselineExclusionStates` reports each recorded key with its current verification state.
The `excluded` state means the reviewed entry still matches the active agent baseline and the key is absent from the live OpenShell policy.
Other states identify agent drift, changed or removed baseline content, an unreadable baseline or live policy, or a live policy that contains the excluded key.
`baselineExclusionTransition` is `null` when policy state is settled; otherwise it identifies the interrupted `exclude` or `restore` key that must be reconciled before sandbox creation or recreation, rebuild, or cross-sandbox snapshot cloning.
The schema-version `1` `model` and `provider` fields keep their established live-route meaning when the gateway route is readable.
Use `recordedRoute` for the sandbox's durable provider and model and `liveRoute` for the gateway-global route.
When the live shared route differs, text output prints both routes and JSON output sets `routeDrift.live`, `routeDrift.recorded`, and `routeDrift.canConnect`.
When `routeDrift.canConnect` is `false`, `connect` cannot safely restore the recorded route because provider-global identity differs or required route or gateway metadata is incomplete.
Refer to [Use Shared Gateway Routes](../inference/manage-inference/use-shared-gateway-routes) for the route-sharing workflow.
`openshellDriver` and `openshellVersion` are always strings (falling back to `"unknown"` when the registry has no value), so consumers can rely on `typeof` checks.
`agent` is always a string and reports `openclaw` when the registry records no agent for the sandbox.
`failureLayer` is `null` when no preflight failure was detected and otherwise one of `docker_unreachable`, `sandbox_container_stopped`, or `sandbox_dashboard_port_conflict`; when set, `inferenceHealth` is suppressed to `null` so automation does not see a stale remote-provider healthy status during a local outage.
`inferenceHealth.ok` reports whether the inference route returned a structurally valid result for one request sent from inside the sandbox.
The result must match Chat Completions, Responses, or Anthropic Messages for the selected route.
An empty body, malformed JSON, provider-error envelope, or wrong response shape reports `unhealthy`, even with a 2xx status.
The probe captures at most 64 KiB and does not include the response body in diagnostics.
The route probe treats any final HTTP status from `200` through `499` as reachable, so a route with an invalidated provider credential answers HTTP `401` while the route is up.
The request uses the live gateway route's provider and model, and falls back to the recorded values when the live route is unreadable.
When the live provider and model match the recorded route, the request also uses the sandbox's recorded API family, including `openai-responses`.
During route drift, NemoClaw does not carry the sandbox's recorded API family to the live provider and model.
An ordinary run sends one 16-token request through the stored provider credential, with a 30-second timeout, and consumes provider tokens on a hosted route.
When the same `status` run recovers a managed gateway, it retries the route and inference request together up to three total attempts, with a two-second delay between failed attempts.
Each attempt can consume another 16 tokens on a hosted route.
When NemoClaw sends an inference request, `inferenceHealth.subprobes` reports the route probe result as the `route reachability` hop, so a failing verdict still shows that the route itself answered.
`inferenceHealth.failureLabel` reports why the inference request failed:

- `unauthorized` when the route rejected it with HTTP `401` or `403`.
- `unhealthy` when the route returned another failing HTTP status or an invalid 2xx response body.
- `unreachable` when the request returned no HTTP status, including a probe that could not run.

A host-side upstream probe under `inferenceHealth.subprobes` stays a diagnostic and does not change `inferenceHealth.ok`, because the sandbox route is the one the agent uses.
When the route probe failed, or the sandbox records no provider or no model, NemoClaw skips the inference request and `inferenceHealth` reports the route probe result alone.
`dockerPaused` is `true` when NemoClaw detects that the Docker-driver sandbox container is paused.
In that case, text output keeps OpenShell's authoritative phase but prints a `docker unpause <container>` recovery hint instead of sending you directly to rebuild.
For terminal runtime sandboxes, the command also checks cgroup OOM kill counters.
If the counter records an OOM kill, text output prints `Runtime health: degraded (... OOM kill recorded)` and points you to `$$nemoclaw <name> rebuild`; JSON output reports `terminalRuntimeHealth.kind: "degraded"` with the OOM kill count and source counter path.
For a present gateway runtime, text output prints `Serving process (<agent> gateway): not checked`, and JSON output reports `servingProcessHealth: { "checked": false }`.
The existing inference probes run in a fresh sandbox command, so they do not attest that the long-running gateway process has equivalent inference access.
NemoClaw does not probe the serving process yet.
For terminal runtimes, `servingProcessHealth` is `null` and the text output omits this line because there is no long-running gateway process.
The command exits non-zero when the sandbox is missing locally, the gateway state is not `present`, the gateway reports a schema/protobuf mismatch (mirrored as `rpcIssue`), `failureLayer` is non-null, the authoritative in-sandbox inference route fails or cannot be probed, or a terminal runtime sandbox reports a recorded OOM kill.
The alias form `$$nemoclaw <name> status --json` requires the sandbox to be registered locally; the canonical form `$$nemoclaw sandbox status <name> --json` is the one to use from automation that may run against an unknown sandbox name, since it still emits a JSON document with `found: false` instead of a text error.

For a sandbox that owns managed llama.cpp, text output also reports the recipe ID, model digest, image reference, `https://inference.local/v1` endpoint, and lifecycle state.
It does not print the managed API key or its fingerprint.
The lifecycle state is one of these values:

| State | Meaning |
|---|---|
| `preparing` | The gateway-scoped owner exists, but `receipt.json` is absent. |
| `running` | The exact receipt-owned container is running under the recorded Docker authority. |
| `stopped` | The exact receipt-owned container exists but is stopped. |
| `absent` | The finalized receipt exists, but its exact container is absent. |
| `conflict` | The Docker authority or runtime identity differs from the receipt. |
| `unknown` | NemoClaw cannot read or prove the state. |

The managed llama.cpp check forces a nonzero exit for `absent`, `conflict`, or `unknown`.
Other sandbox and inference checks can also make the command fail.
Rerun the same `NEMOCLAW_PROVIDER=install-llama-cpp` and `NEMOCLAW_LLAMACPP_RECIPE` onboarding selection to recover a stopped or interrupted runtime.
Inspect and correct an identity conflict before retrying.

<AgentOnly variant="deepagents">

For a Deep Agents sandbox, text output includes `DCode auto-approval capability: disabled` or `DCode auto-approval capability: thread-opt-in`.
JSON output reports the same configured value in `dcodeAutoApprovalMode`.
This value does not attest that auto-approval is active in any live TUI thread.

</AgentOnly>

```bash
$$nemoclaw my-assistant status
$$nemoclaw my-assistant status --json
$$nemoclaw sandbox status my-assistant --json
```

The command probes `https://inference.local/v1/models` from inside the sandbox, and when that probe reports the route reachable it sends one inference request over the same route.
That inference request is the authoritative inference health check, and both checks exercise the route that agent traffic uses.
The main `Inference` line reports one of these states:

| State | Meaning |
|-------|---------|
| `healthy` | The route returned a structurally valid result for the inference request. |
| `unauthorized` | The route rejected the inference request with HTTP `401` or `403`. |
| `reachable` | The route returned an HTTP status from `200` through `499` and NemoClaw did not send an inference request. |
| `unhealthy` | The route returned HTTP `500` through `599`, another failing status, or an invalid 2xx response body. |
| `unreachable` | The route had a transport failure, returned no final HTTP status (`000` or an interim `100` through `199`), returned an invalid status outside `100` through `599`, or the inference request returned no HTTP status. |
| `not probed` | NemoClaw could not run the authoritative route probe from a reachable sandbox. |
| `not verified` | NemoClaw could not verify the sandbox or gateway state, so it skips inference probing. |

An authentication response on the route probe alone confirms that the route is reachable, not that provider credentials are valid.
`$$nemoclaw <name> doctor` sends no inference request, so it reports an HTTP `401` or `403` route response as reachable and exits `0` where `status` reports `unauthorized`.
The command can also print direct host-side provider checks such as `Inference (upstream)` and provider-specific subprobes.
For supported remote providers, this diagnostic sends an authenticated request to the configured model and accepts only a recognized Chat Completions, streaming Chat Completions, or Anthropic Messages response.
It uses a 3-second connection timeout, a 5-second total timeout, and an 8-token output limit.
If the request reaches the time limit, NemoClaw reports the provider as `not probed` and leaves model health unverified instead of reporting it as unhealthy.
These checks are diagnostic only and do not override the authoritative `inference.local` result or determine the command exit status.

Local providers add host-side backend diagnostics.
For Local Ollama, the command can also print an `Inference (auth proxy)` diagnostic when a proxy token is available.
Use these diagnostics to identify a failing auxiliary hop after checking the main `Inference` line.

For cloud-only providers, the output omits the NIM status line unless a NIM container is registered or an unexpected NIM container is running.

When the sandbox's recorded driver is `docker` and the host Docker daemon is not reachable, the command prints the `docker_unreachable` failure layer with the message `Docker daemon is not reachable.` as the first line of stdout, suppresses the host-side `Inference` probe (which otherwise hits the remote provider directly and is misleading when the local stack is down), and exits with a non-zero status.

When the host Docker daemon is reachable but the per-sandbox container is stopped, the initial preflight records the `sandbox_container_stopped` failure layer and suppresses the host-side `Inference` probe.
If the owning OpenShell gateway is healthy but no longer lists the registered Docker-driver sandbox, status attempts post-reboot recovery from the labeled container.
It waits for Docker readiness, restores the in-sandbox gateway and host forwards, and refreshes preflight before probing inference.
A successful recovery clears the stale stopped-container failure.
<AgentOnly variant="openclaw">
If OpenShell already reports the registered Docker-driver sandbox as present and `Ready`, status verifies the OpenClaw gateway and host forward.
It recovers either component when the verification reports it absent.
</AgentOnly>
When status finds the sandbox but cannot prove its agent delivery chain, it exits non-zero and reports the `sandbox_recovery_failed` state.
Address the reported recovery layer, then run the displayed `$$nemoclaw <sandbox-name> recover` command.
<AgentOnly variant="openclaw,hermes">
If the sandbox's recorded dashboard port is also held by a foreign listener, the header escalates to the `sandbox_dashboard_port_conflict` failure layer with the message `sandbox container is stopped and the dashboard port is held by a foreign listener.` so the operator can recover the port before restarting the sandbox.
</AgentOnly>

If the sandbox or gateway cannot be verified, the command exits non-zero instead of reporting healthy inference from stale registry state.
When a locally registered sandbox is missing from the live gateway, status preserves the registry entry so the suggested `rebuild --yes` recovery can still find the sandbox metadata.
<AgentOnly variant="openclaw,hermes">
Gateway and dashboard health checks treat HTTP `401` from device auth as a live service, not as an offline gateway.
</AgentOnly>

When sandbox GPU passthrough is enabled, the `Sandbox GPU` line includes the last CUDA usability proof state.
It reports `(CUDA verified)`, `(CUDA unverified)`, or `(last CUDA proof failed: <label>)` so automation and operators can distinguish configured GPU passthrough from proven CUDA access.
Failed proofs include remediation guidance for the detected platform.

An `SSH sessions` line reports how many active SSH sessions the sandbox has, or `none`; the line is omitted when the session probe is unavailable.
<AgentOnly variant="openclaw,hermes">
The sandbox list in the status output includes the dashboard port suffix for sandboxes with a recorded dashboard port.
</AgentOnly>

The Policy section displays the live enforced policy (fetched via `openshell policy get --full`), which reflects presets added or removed after sandbox creation.
When OpenShell reports an active policy version, the displayed YAML `version` line uses that active version instead of the static schema version.
If the sandbox is running an outdated agent version, the output includes an `Update` line with the available version and a `$$nemoclaw <name> rebuild` hint.

<AgentOnly variant="openclaw,hermes">
When NemoClaw detects a messaging overlap between sandboxes in the selected OpenShell gateway's sandbox registry, the output includes a cross-sandbox overlap warning.
The command cannot report overlaps in an independent OpenShell gateway's registry.
The command also tails `/tmp/gateway.log` inside the default sandbox and flags Telegram `409 Conflict` errors that indicate a duplicate consumer for the bot token.
</AgentOnly>

```bash
$$nemoclaw my-assistant status
```

<AgentOnly variant="openclaw">

#### Checking the OpenClaw version

Refer to [Update Sandboxes](../manage-sandboxes/operate-sandboxes/update-sandboxes#understand-agent-version-pins) for the OpenClaw version pin and rebuild policy.

`$$nemoclaw <name> status` prints the running OpenClaw version on the `Agent` line:

```bash
$$nemoclaw my-assistant status
```

Expected output:

```text
...
    Agent:    OpenClaw v<version>
...
```

If the sandbox is running an OpenClaw older than the version this NemoClaw release pins, `status` and `connect` add an `Update` line pointing at `$$nemoclaw <name> rebuild` to pick up the newer version.
The rebuild reuses the existing sandbox name and persisted credentials, so messaging tokens and provider keys carry over.

</AgentOnly>
<AgentOnly variant="hermes">

#### Checking the Hermes version

Refer to [Update Sandboxes](../manage-sandboxes/operate-sandboxes/update-sandboxes#understand-agent-version-pins) for the Hermes version pin and rebuild policy.

`nemohermes <name> status` prints the running Hermes version on the `Agent` line:

```bash
nemohermes my-assistant status
```

Expected output:

```text
...
    Agent:    Hermes v<version>
...
```

If the sandbox is running an older Hermes version than this NemoClaw release expects, `status` and `connect` add an `Update` line pointing at `nemohermes <name> rebuild` to pick up the newer version.
The rebuild reuses the existing sandbox name and persisted credentials, so messaging tokens and provider keys carry over.

</AgentOnly>
<AgentOnly variant="deepagents">

#### Checking the Deep Agents version

Refer to [Update Sandboxes](../manage-sandboxes/operate-sandboxes/update-sandboxes#understand-agent-version-pins) for the Deep Agents Code version pin and rebuild policy.

`nemo-deepagents <name> status` prints the running Deep Agents Code version on the `Agent` line:

```bash
nemo-deepagents my-assistant status
```

Expected output:

```text
...
    Agent:    LangChain Deep Agents Code vX.Y.Z
...
```

If the sandbox is running an older Deep Agents Code version than this NemoClaw release expects, `status` and `connect` add an `Update` line pointing at `nemo-deepagents <name> rebuild` to pick up the newer version.
The rebuild reuses the existing sandbox name and preserved manifest-defined state, so skills, app state, and managed config carry over while credentials stay in host-side OpenShell state.

</AgentOnly>

### `$$nemoclaw <name> doctor`

Run a focused health check for one sandbox and the host services it depends on.
The command checks the local CLI build, Docker daemon, OpenShell CLI, NemoClaw gateway container, gateway port mapping, live sandbox state, inference route, configured-provider model invocation, Ollama reachability, and the cloudflared tunnel state.
<AgentOnly variant="openclaw,hermes">
For gateway-based agents, it also reports messaging channel conflicts within the selected OpenShell gateway's sandbox registry.
</AgentOnly>

`doctor` also checks whether the sandbox registry contains the metadata required for snapshot, rebuild, upgrade, recovery, and reboot.
When lifecycle metadata is incomplete, the report names the missing or invalid fields and affected operations without printing stored values.
Dashboard metadata is required only for agents that manage a dashboard.
If the registered gateway binding is invalid, `doctor` reports a failed gateway check and does not select, probe, or recover a gateway from that binding.

For inference health, `doctor` treats the probe to `https://inference.local/v1/models` from inside the sandbox as authoritative.
HTTP responses from `200` through `499`, including `401` and `403`, pass this check.
HTTP `500` through `599`, interim `100` through `199`, transport failures with status `000`, invalid status values, and an unavailable authoritative probe fail the check.
Direct provider and upstream probes use the same authenticated model-invocation checks as status and remain diagnostic only, so their failure does not fail `doctor` when the authoritative in-sandbox route is reachable.
For gateway runtimes, `doctor` also reports an informational `Serving process: not checked` result because its fresh sandbox probes do not attest the long-running gateway process.
This result does not fail the readiness check.
Terminal runtimes omit it because they have no long-running gateway process.

For each recorded baseline exclusion, `doctor` compares the approval with the active agent baseline and verifies that the excluded key is absent from the live OpenShell policy.
An unreadable live policy produces a warning because NemoClaw cannot verify enforcement.
A live policy that contains the excluded key fails the check and requires policy repair before you rely on the exclusion.

Warnings do not make the command fail.
Failed checks, including a failed or unavailable authoritative inference route, exit non-zero so scripts can use `doctor` as a readiness gate.
Use `--json` for machine-readable output.
For a `compatible-endpoint` route that uses `openai-completions`, the JSON report includes an informational `Inference` check labeled `Reasoning effort`.
The check reports `low`, `medium`, `high`, or `endpoint-default` and never includes credentials.
Because the check has `info` status, it does not change the command's exit status.

For a sandbox that owns managed llama.cpp, `doctor` adds secret-free identity and runtime checks.
The runtime check passes only when the exact container is running.
It warns for `preparing` or `stopped`, and it fails for `absent`, `conflict`, or `unknown`.
The recovery hint tells you to rerun onboarding for the same sandbox so NemoClaw can use the persisted receipt and create journal.

<AgentOnly variant="openclaw">

For OpenClaw sandboxes, `doctor` also checks the mutable config permission contract.
If `openclaw doctor --fix` was run inside the sandbox, it can tighten `/sandbox/.openclaw` and `openclaw.json` to a single-user `700/600` layout, which stops the gateway from persisting config changes.
`doctor` reports this as a `Config permissions` warning; pass `--fix` to restore the group-writable `2770/660` contract without rebuilding.
Restarting the sandbox repairs the same drift automatically.

```bash
$$nemoclaw my-assistant doctor [--json | --fix]
```

| Flag | Description |
|------|-------------|
| `--json` | Emit the report as JSON |
| `--fix` | Restore the mutable OpenClaw config permission contract if it was tightened. Mutually exclusive with `--json` |

</AgentOnly>
<AgentOnly variant="hermes">

```bash
$$nemoclaw my-assistant doctor [--json]
```

| Flag | Description |
|------|-------------|
| `--json` | Emit the report as JSON |

</AgentOnly>

### `$$nemoclaw <name> exec`

Run a command non-interactively inside a running sandbox through the OpenShell exec endpoint.
The command runs as the sandbox user with `HOME=/sandbox`.
Use `--` to separate `exec` options from the command you want to run inside the sandbox.

<AgentOnly variant="openclaw">

After the remote command exits, NemoClaw verifies and, when needed, restores the mutable OpenClaw config permission contract.
When cleanup succeeds, `exec` preserves the remote command's exit code.
When cleanup fails closed, `exec` returns the cleanup failure and reports both statuses on `stderr`.

A successful direct `openclaw pairing approve googlechat <code>` command in a registered OpenClaw sandbox with a selected owning managed gateway restarts that gateway after cleanup, so the new sender allowlist applies to the next message.
If the approval commits but cleanup or restart fails, `exec` exits with status `1` and reports that the approval was not rolled back.
When an owning gateway was selected, it directs you to run `$$nemoclaw <name> gateway restart` after correcting any cleanup problem.
Without an owning managed gateway, NemoClaw does not attempt activation or print a managed restart command; unregistered and non-OpenClaw sandboxes do not receive the automatic restart.

</AgentOnly>
<AgentOnly variant="hermes">

The command exits with the remote command's exit code.

</AgentOnly>

```bash
$$nemoclaw my-assistant exec [--workdir <dir>] [--tty|--no-tty] [--timeout <s>] [--stdin|--no-stdin] -- <cmd> [args...]
```

By default, NemoClaw inherits caller stdin only when it is a terminal.
Non-terminal or unavailable stdin is closed so SSH, CI, and other one-shot commands cannot wait on an inherited pipe.
Pass `--stdin` to forward an intentional pipe, or `--no-stdin` to close terminal stdin explicitly.

OpenShell preserves line endings and quote characters inside each command argument, so inline scripts and heredocs can be passed as one argument after `--`.
For example, a shell variable keeps the multi-line script in one argv element:

```bash
script=$'cat <<\'EOF\'\nline one\nline two\nEOF'
$$nemoclaw <name> exec -- bash -lc "$script"
```

NUL bytes are still rejected in command arguments.
Line breaks are accepted only in command argv: `--workdir` remains single-line, and NemoClaw does not expose OpenShell request-environment injection on this command.

| Flag | Description |
|------|-------------|
| `--workdir <dir>` | Set the working directory inside the sandbox. The directory is checked before the command runs; if it does not exist, NemoClaw reports `error: --workdir: <dir> does not exist inside the sandbox` and exits with status `1` without invoking the inner command. |
| `--tty`, `--no-tty` | Allocate or disable a pseudo-terminal; defaults to auto-detection |
| `--timeout <s>` | Timeout in seconds. Use `0` for no timeout |
| `--stdin`, `--no-stdin` | Force caller stdin forwarding or closure (default: inherit terminal stdin; close non-terminal or unavailable stdin). |

### `$$nemoclaw <name> logs`

View sandbox logs.
Use `--follow` to stream output in real time.
Use `--tail <lines>` or `-n <lines>` to limit the number of returned lines.
Use `--since <duration>` to show recent logs only, such as `5m`, `1h`, or `30s`.
The command reads both agent gateway output and OpenShell audit events, so policy denials appear alongside the gateway log stream.
If one log source is unavailable, NemoClaw prints a warning and keeps reading the remaining source.
NemoClaw's `--tail <lines>` flag is a line-count flag; the lower-level `openshell logs --tail` flag means follow live output, so use `openshell logs <sandbox> -n <lines>` when running OpenShell directly for a fixed line count.

```bash
$$nemoclaw my-assistant logs [--follow] [--tail <lines>|-n <lines>] [--since <duration>]
```

### `$$nemoclaw <name> dashboard-url`

<AgentOnly variant="openclaw">

Print the browser dashboard URL for a running sandbox.
For OpenClaw sandboxes this includes the authenticated URL fragment.
For agent dashboards that manage their own session, such as Hermes Agent, this prints the plain dashboard URL.
Use this when you are on a remote machine, using an SSH or reverse tunnel, or need a complete URL for a browser session.

```bash
$$nemoclaw my-assistant dashboard-url
$$nemoclaw my-assistant dashboard-url --quiet
```

The default output includes a label and a warning.
Pass `--quiet` or `-q` to print only the URL to stdout so scripts can capture it:

```bash
URL=$($$nemoclaw my-assistant dashboard-url --quiet)
```

<Warning>
Treat the authenticated dashboard URL like a password.
Do not log it, share it, or commit it to version control.
This warning applies when the command prints an OpenClaw tokenized URL.
</Warning>

</AgentOnly>
<AgentOnly variant="hermes">

Print the browser dashboard URL for a running Hermes sandbox.
Hermes manages dashboard sessions itself, so this command prints a plain URL without an OpenClaw `#token=` fragment.
The built-in dashboard is forwarded on port `18789` by default.

```bash
nemohermes my-assistant dashboard-url
nemohermes my-assistant dashboard-url --quiet
```

The Hermes OpenAI-compatible API is separate and serves `/v1` on a per-sandbox port that defaults to `8642`.
Run `openshell forward list` to read the host bind for the dashboard and API forwards.

</AgentOnly>
<AgentOnly variant="deepagents">

`dashboard-url` is not applicable to Deep Agents sandboxes because the managed harness is a terminal runtime without a dashboard port.
Use `$$nemoclaw launch <name>` to start `dcode`.
Use `$$nemoclaw <name> connect` instead when you want a sandbox shell.

</AgentOnly>

### `$$nemoclaw <name> gateway-token`

<AgentOnly variant="openclaw">

Print the OpenClaw gateway auth token for a running sandbox to stdout.
The token is required by `openclaw tui` and the OpenClaw dashboard URL.
Use `dashboard-url` for browser access; use `gateway-token` only when automation needs the raw token.
Pipe it into automation or capture it into an environment variable:

```bash
TOKEN=$($$nemoclaw my-assistant gateway-token --quiet)
export OPENCLAW_GATEWAY_TOKEN="$TOKEN"
```

The token is written to stdout with no surrounding text.
A one-line security warning is written to stderr; pass `--quiet` (or `-q`) to suppress it.
The command exits non-zero with a diagnostic on stderr when the sandbox is not registered or when the token cannot be retrieved (for example, if the sandbox is not running).

The token also authenticates the Control UI config endpoint served by the gateway on the forwarded dashboard port.
There is no `controlui.bootstrap.config.json` path; the supported endpoint is `/__openclaw/control-ui-config.json`, and it requires the token (unauthenticated requests return `401` with a JSON body):

```bash
TOKEN=$($$nemoclaw my-assistant gateway-token --quiet)
curl -fsS -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:18789/__openclaw/control-ui-config.json"
```

<Warning>
Treat the gateway token like a password.
Do not log it, share it, or commit it to version control.
</Warning>

</AgentOnly>
<AgentOnly variant="hermes">

Print the Hermes API bearer token for a running sandbox to stdout.
NemoClaw retrieves the sandbox's `API_SERVER_KEY`, which authenticates OpenAI-compatible clients on the forwarded API port.
During a normal sandbox lifecycle, the token is generated once for each sandbox home.
Different sandbox homes receive different tokens.
NemoClaw preserves it across a gateway restart, sandbox stop and start, and host OpenShell gateway restart.
When you rebuild or replace the sandbox, the replacement home receives a new token.
At gateway startup, NemoClaw also generates a new token when `API_SERVER_KEY` is missing or is not exactly 64 lowercase hexadecimal characters.
If an ordinary restart changes the token while the existing `API_SERVER_KEY` was present and valid, collect the before and after sandbox identity plus redacted mint logs and report it as a bug.
Capture the token and pass it in the `Authorization` header:

```bash
TOKEN=$(nemohermes my-assistant gateway-token --quiet)
curl -fsS -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8642/v1/models
```

<Warning>
Treat the token like a password.
Do not log it, share it, or commit it to version control.
</Warning>

The sandbox must be running for `nemohermes my-assistant gateway-token --quiet` to retrieve the token.
Use this supported command instead of reading or editing `.hermes/.env` directly.
For browser access to the dashboard, use `nemohermes my-assistant dashboard-url`.

</AgentOnly>
<AgentOnly variant="deepagents">

`gateway-token` is not applicable to Deep Agents sandboxes because there is no OpenClaw gateway token.
Model traffic uses the OpenShell-managed `inference.local` route configured by NemoClaw.

</AgentOnly>

### `$$nemoclaw <name> destroy`

Stop managed local inference resources, remove the host-side Docker image built during onboard, and delete the sandbox.
This removes the sandbox from the registry.
For Ollama-backed sandboxes, `destroy` also asks Ollama to unload currently loaded models and clears stale auth proxy state on a best-effort basis.
For Model Router sandboxes, `destroy` keeps the process and recovery identity when another sandbox uses the port or when session, process, or absence checks are inconclusive.
It also preserves a replacement onboarding session when the captured session identity changed.
If the captured session uses the destroyed sandbox name with another router port, `destroy` clears only the sandbox association and preserves that router's recovery identity.
For lock order, same-port peer handling, and cleanup checks, refer to [Set Up Model Router](../inference/hosted-inference/set-up-model-router#router-and-sandbox-lifecycle-locks).

If `destroy` warns that it could not identify or stop a listener for the deleted sandbox:

1. Inspect the current listener process immediately before you stop anything.
2. Stop it only if its command line identifies the Model Router on the named port.
3. Do not stop the router recorded by a preserved session for another port.
4. Do not stop a previously reported process ID if its command line no longer matches.

<Warning>
This command attempts to wipe the manifest-defined agent state while its persistent volume is mounted, then removes the sandbox.
OpenShell can retain the per-name persistent volume after sandbox deletion.
If the wipe cannot complete, onboarding with the same name can resurface old files.
Do not rely on a retained volume as a backup.
Back up your workspace first with `$$nemoclaw <name> snapshot create` or refer to [Create and Restore Snapshots](../manage-sandboxes/state-and-backups/create-and-restore-snapshots).
If you want to upgrade the sandbox while preserving state, use `$$nemoclaw <name> rebuild` instead.
</Warning>

If another terminal has an active SSH session to the sandbox, `destroy` prints an active-session warning and requires a second confirmation before it proceeds.
Pass `--yes`, `-y`, or `--force`, or set `NEMOCLAW_NON_INTERACTIVE=1`, to authorize deletion without prompting in scripted workflows.

Before changing a Docker-backed sandbox, NemoClaw inspects every container with the requested `openshell.ai/sandbox-name` label.
The command continues when Docker returns no matching containers.
For one matching container, the command continues only when all these labels have the required values:

- `openshell.ai/managed-by=openshell`
- A nonempty `openshell.ai/sandbox-workspace`
- A nonempty `openshell.ai/sandbox-id`

If the initial inspection cannot complete, more than one container matches, a matching container has conflicting or incomplete labels, or Docker returns malformed identity data, `destroy` exits before changing sandbox resources.
The identity checks still apply with `--force`, `--yes`, or `NEMOCLAW_NON_INTERACTIVE=1`; those controls authorize confirmation but do not authorize an unproven container identity.
NemoClaw rechecks the exact identity after read-only preflight, before provider cleanup, and synchronously at the sandbox-deletion boundary.
If a later recheck detects drift or fails, `destroy` refuses sandbox deletion, restores managed MCP preparation when possible, preserves local ownership state, and reports any earlier cleanup already performed.
If OpenShell reports the sandbox absent after preflight captured one matching Docker container, `destroy` rechecks and removes only that exact container ID.
If Docker reports another OpenShell-managed container, removal fails, or NemoClaw cannot confirm removal, `destroy` exits nonzero and preserves the registry entry.
Correct the reported Docker state, then rerun `destroy`.
If Docker cannot complete the inspection, correct the reported Docker error before you rerun `destroy`.
For common recovery steps, refer to [Docker is not running](troubleshooting#docker-is-not-running) and [Docker permission denied on Linux](troubleshooting#docker-permission-denied-on-linux).

If `destroy` reports conflicting, incomplete, or malformed identity data, inspect the matching containers:

~~~bash
docker ps -a --no-trunc \
  --filter "label=openshell.ai/sandbox-name=my-assistant" \
  --format 'table {{.ID}}\t{{.Label "openshell.ai/managed-by"}}\t{{.Label "openshell.ai/sandbox-workspace"}}\t{{.Label "openshell.ai/sandbox-id"}}'
~~~

The labels show what each container claims.
They do not prove container ownership.

<Warning>
Do not remove or recreate a container until you verify its purpose, ownership, and data-retention requirements.
Removing or recreating a container can discard state that is not stored in a volume.
</Warning>

Resolve a conflict through the workflow that created the conflicting container.
Docker cannot change labels on an existing container.
Rerun the query after you resolve the conflict.
Rerun `destroy` only when the query returns one complete expected label set that you verified belongs to the target sandbox, or no containers after you independently confirm that the sandbox is absent.

<AgentOnly variant="hermes">

If the Hermes sandbox has managed MCP entries, shields must be down before destroy can scrub their adapter configuration.
Use `$$nemoclaw <name> shields down --timeout 15m --reason "MCP maintenance"`, allowing at least 15 minutes per configured server.
If sandbox deletion is refused after destroy has restored lockdown, NemoClaw opens an owner-bound timed rollback window, restores the preserved MCP state, and re-locks shields; the timer retains auto-restore authority if the host process exits.

</AgentOnly>

If a shields auto-restore timer is active, `destroy` holds the same per-sandbox transition through state wipe and deletion.
It restores and verifies lockdown and revokes the active timer before deletion.
It clears the remaining local shields state only after deletion succeeds.
If the pre-delete re-lock fails, the command warns and attempts to destroy the sandbox.
If the destroy operation succeeds, it destroys the sandbox and deletes its unguarded configuration.
If the destroy operation fails, NemoClaw keeps the local shields state and the auto-restore timer.
The timer keeps retrying lockdown and can restore it after the sandbox is reachable again.
NemoClaw records Shields down until a retry verifies lockdown, or until you destroy or rebuild the sandbox.
If deletion fails after hardening, the command keeps the surviving sandbox's locked shields state instead of cleaning it up as though deletion succeeded.
By default, unattended final-sandbox destroys (`--yes`, `--force`, or `NEMOCLAW_NON_INTERACTIVE=1`) remove the shared NemoClaw gateway on macOS so the host listener is released, while Linux preserves it for reuse.
Pass `--cleanup-gateway` to force removal, or `--no-cleanup-gateway` to force preservation.
These flags always override both `NEMOCLAW_CLEANUP_GATEWAY` and the platform default.
If the pre-delete workspace wipe cannot run, use a different sandbox name for a clean start.
Cleaning up the gateway after the last sandbox also purges the shared cluster volume that retains the per-name persistent volume.
If final gateway cleanup finds a live PID-file process whose command line does not prove it owns the target gateway, `destroy` exits non-zero after sandbox and registry deletion and skips gateway and volume removal.
NemoClaw preserves the per-gateway PID file and runtime marker so you can inspect the process.
Stop only the listener that matches the target gateway, then rerun `destroy` to converge cleanup.
When the default-port gateway runs under the packaged OpenShell gateway service, gateway cleanup stops that service before it reaps host processes, so the gateway port is released instead of being rebound by the service manager.
The service is stopped, not disabled or removed, and the next onboarding run starts it again.
On headless Linux, the packaged service can exist while its `systemd` user manager is unavailable and the gateway runs through the standalone fallback.
For this recognized manager-unavailable failure only, `destroy` uses the per-gateway PID file when the service is not enabled for automatic activation.
If the recorded PID is live, its command line must match the exact gateway name and port before `destroy` stops it.
If the recorded process has exited, `destroy` continues only after it verifies that the gateway port is free.
If a live PID does not prove gateway ownership or the port remains occupied, `destroy` exits non-zero and preserves the runtime evidence for inspection.
For any other service stop failure, `destroy` exits non-zero after sandbox and registry deletion, prints the status command for the service, and skips gateway and volume removal.
If the OpenShell gateway is unreachable and the sandbox has no managed MCP ownership state, `--force` removes only NemoClaw's local registry entry and local artifacts.
Gateway-side deletion remains unconfirmed, shared host-service and gateway teardown are skipped, and the sandbox and retained volume may still exist if the gateway returns.
Start the gateway with `$$nemoclaw <name> status` and retry destroy when you need a confirmed deletion.
Managed MCP ownership disables the local-only fallback because exact provider cleanup requires the retained ownership state, and other delete failures remain fatal.
A failed pre-delete re-lock also disables the local-only fallback, because the auto-restore timer is then the only authority that can lock the configuration again after the gateway returns.

```bash
$$nemoclaw my-assistant destroy [--yes|-y|--force] [--cleanup-gateway|--no-cleanup-gateway]
```

After OpenShell confirms deletion of a sandbox that owns managed llama.cpp, `destroy` revalidates the exact container, internal network, lifecycle journal, and gateway-scoped receipt.
It removes those resources by inspected ID, then removes the API key and managed ownership state.
It preserves the shared `~/.cache/huggingface/` cache.
If exact cleanup fails, `destroy` preserves the sandbox registry entry and ownership state so you can correct the reported conflict and retry.

### `$$nemoclaw <name> policy get`

Export the sandbox's round-trippable OpenShell base policy as YAML.
The command runs `openshell policy get --base`, validates the returned policy, and strips the OpenShell metadata header.
The default output is suitable for review, editing, and later use with `openshell policy set`.
The command exits non-zero when OpenShell fails, returns an empty response, or returns content that is not valid policy YAML.

```bash
$$nemoclaw my-assistant policy get > current-policy.yaml
```

Use `--raw` only to inspect the unparsed OpenShell response, including its metadata header:

```bash
$$nemoclaw my-assistant policy get --raw
```

Do not pass `--raw` output to `openshell policy set` because the metadata header is not part of the policy document.

| Flag | Description |
|------|-------------|
| `--raw` | Print the unparsed `openshell policy get --base` response, including its metadata header. |

### `$$nemoclaw <name> policy add`

Add a policy preset to a sandbox.
Presets extend the baseline network policy with additional endpoints.
Before applying, the command shows which endpoints the preset would open and prompts for confirmation.
The scope comes from the exact preset YAML and includes each endpoint's host, port, access, protocol, TLS, and enforcement settings, allowed methods and paths, and binary allowlist.
When a lifecycle operation reapplies a preset, NemoClaw compares it with the live policy and reports whether the preset opens new egress, replaces a drifted entry, or is already effective with no new egress.

```bash
$$nemoclaw my-assistant policy add
```

To apply a specific preset without the interactive picker, pass its name as a positional argument:

```bash
$$nemoclaw my-assistant policy add pypi --yes
```

The positional form is required in scripted workflows.
Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` if you want the same behavior from an environment variable.
Without a preset name, a run with `NEMOCLAW_NON_INTERACTIVE=1` reports that non-interactive mode requires a preset name.
A run without a terminal on stdin instead reports that no input is available on stdin.
Both exit non-zero rather than open the picker.
If the preset name is unknown, the command exits non-zero with a clear error.
If a named preset is already applied, the command compares the preset content with the live policy.
When the content matches, the command reports no changes and exits zero.
When the content differs, the command shows the normal preview and asks for confirmation before applying the preset again.
This includes changes to the preset file.
The comparison requires both the preset content and the live policy.
If either cannot be read, the command exits non-zero.
The command also exits non-zero when the name belongs to a custom preset applied with `--from-file`.
Use `--from-file` to apply that custom preset again.
Built-in preset choices are scoped to the sandbox's active agent.
Messaging channel presets appear only when NemoClaw has a matching channel policy for that agent; unavailable channel presets use the standard unknown-preset error before endpoint preview or confirmation.
When a baseline key is durably excluded, NemoClaw reserves that key and refuses built-in, custom, channel, and MCP policy additions that would define it again.
Restore the baseline entry before applying a preset that intentionally owns the same key, or rename a custom preset entry whose key represents different access.
Custom preset files are tracked with the sandbox that applied them.
`policy list`, `policy add`, and `policy remove` compare the local registry and live gateway state using that sandbox-scoped preset metadata, so custom presets do not appear missing just because they are not part of the built-in preset catalog.
Before `policy add` writes a merged policy, it reads and parses the round-trippable base policy from OpenShell.
If the base policy read returns non-empty output that NemoClaw cannot parse, the command exits non-zero instead of overwriting the live policy with only the new preset.
Fix the gateway or policy read problem, then rerun the command.
For custom presets, the command also reports when the preset reached the gateway but NemoClaw could not record it in the local sandbox registry, because unrecorded custom presets will not appear in `policy list` or `status`.
Recover or re-onboard the sandbox, then re-apply the custom preset.

With `--from-file` or `--from-dir`, pass a repeatable `--trusted-private-host <exact-host-or-ip>` option to admit matching RFC1918, carrier-grade network address translation (CGNAT), or IPv6 unique local endpoints.
The option is invalid for built-in presets.
You can supply exact hosts through `NEMOCLAW_TRUSTED_PRIVATE_HOSTS` instead, and NemoClaw combines the variable with command options.
NemoClaw resolves each matching exact host and adds generated `allowed_ips` pins to an in-memory copy of the preset.
User-authored `allowed_ips` remains rejected.
Dry-run output shows the generated pins, and rebuild replays the transformed preset recorded in the sandbox registry without widening it from ambient DNS.
A snapshot alone does not grant private-host authority to a clean target; after a cross-sandbox restore, reapply the source preset with explicit trust.

| Flag | Description |
|------|-------------|
| `--from-file <path>` | Apply a custom preset YAML file instead of a built-in preset |
| `--from-dir <path>` | Apply every custom preset YAML file in a directory in lexicographic order |
| `--trusted-private-host <exact-host-or-ip>` | Admit one exact private endpoint host from a custom preset and generate exact address pins; repeat for additional hosts |
| `--yes`, `--force` | Skip the confirmation prompt (requires a preset name, `--from-file`, or `--from-dir`) |
| `--dry-run` | Preview the endpoints a preset would open without applying changes |

Use `--dry-run` to audit a preset before applying it:

```bash
$$nemoclaw my-assistant policy add --dry-run
```

Apply a custom preset file when you need to grant access to an endpoint that is not covered by a built-in preset:

```bash
$$nemoclaw my-assistant policy add --from-file ./presets/my-internal-api.yaml
```

For a trusted private endpoint, preview the generated pins before applying them:

```bash
$$nemoclaw my-assistant policy add \
  --from-file ./presets/my-internal-api.yaml \
  --trusted-private-host api.corp.example \
  --dry-run
```

For batch workflows, apply all preset files from a directory:

```bash
$$nemoclaw my-assistant policy add --from-dir ./presets/ --yes
```

Review every host in custom preset files before applying them.
Custom presets bypass the built-in preset review process and can widen sandbox egress.

### `$$nemoclaw <name> policy list`

List available policy presets and show which ones are applied to the sandbox.
The available built-in rows are scoped to the sandbox's active agent, so unsupported messaging channel policies are not listed for agents without matching channel policy files.
The command cross-references the local registry against the live gateway state (via `openshell policy get`), so it flags presets that are applied in one place but not the other.
This catches desync caused by external edits to the gateway policy or stale registry entries after a manual rollback.
Preset summaries come only from the YAML `preset.description` field.
NemoClaw does not render network-policy rule bodies as prose in `policy list` output.
Recorded baseline exclusions appear in a separate section.
`active` means the reviewed digest still matches the current baseline, `baseline changed — re-review required` means the current entry differs, and `baseline entry removed — restore to clear` means the current release no longer defines the key.
Use `status` or `doctor` to additionally verify that the approval belongs to the active agent and the excluded key is absent from the live policy.
`repair required — interrupted exclude/restore; rebuild blocked` means NemoClaw preserved a durable transaction journal after a crash or persistence failure; rerun the displayed exact policy command to reconcile it before sandbox creation or recreation, rebuild, or cross-sandbox snapshot cloning.

Each active preset is annotated with its provenance so you can tell why it is applied:

- `[from <tier> tier]` — the preset name matches an entry in the sandbox's current tier definition (see [Policy Tiers](../reference/network-policies#policy-tiers)).
- `[from <agent> agent]` — the preset name matches a NemoClaw-managed agent preset and the active agent matches that label.
- `[user-added]` — anything else: presets applied later through `policy add`, presets that match no tier or agent default, or presets that match the opposite agent's reserved names on a sandbox running the other agent.
- `[source unverified]` — the row is active but the local registry and live gateway state disagree.
  When the gateway cannot be queried, this renders as `[source unverified (gateway unreachable)]`.
  The provenance check is suppressed in these trust-degraded states because the source cannot be confirmed against both halves of the sandbox policy view.

Provenance tags are inferred from the sandbox's current tier and agent metadata at display time and are not persisted per preset.
A preset whose name appears in the sandbox's current tier YAML is labelled `[from <tier> tier]` even when an operator added it manually with `policy add` after onboarding.
Agent-specific preset names are only labelled `[from <agent> agent]` when the active agent matches that label.

```bash
$$nemoclaw my-assistant policy list
```

### `$$nemoclaw <name> policy remove`

Remove a previously applied policy preset from a sandbox.
The command lists only the presets currently applied, prompts you to select one, shows the endpoints that would be removed, and asks for confirmation before narrowing egress.

```bash
$$nemoclaw my-assistant policy remove
```

To remove a specific preset non-interactively, pass its name as a positional argument:

```bash
$$nemoclaw my-assistant policy remove pypi --yes
```

Set `NEMOCLAW_NON_INTERACTIVE=1` as an alternative to `--yes`.
Without a preset name, `policy remove` reports the same two picker errors as `policy add` and exits non-zero.
If the preset is unknown or not currently applied, the command exits non-zero with a clear error.

| Flag | Description |
|------|-------------|
| `--yes`, `--force` | Skip the confirmation prompt (requires a preset name) |
| `--dry-run` | Preview which endpoints would be removed without applying changes |

Unchecking a preset in the onboard TUI checkbox also removes it from the sandbox.

### `$$nemoclaw <name> policy exclude <key>`

Persistently exclude one exact entry from the agent baseline policy after previewing the egress and support impact that the change removes.
The preview names the supported features that may stop working.
The command refuses an entry that does not have a reviewed feature-impact disclosure.
The versioned exclusion record is bound to the reviewed baseline content and active agent, then replayed during rebuild.
If the active agent or entry changes, rebuild fails closed until you clear or review the exclusion again.
The command refuses to exclude a key that an applied preset already owns, because removing that live key would also remove the preset's access.
The critical `managed_inference` entry cannot currently be excluded pending product direction.
Use `--force` or `--yes` for explicit non-interactive acknowledgement, or `--dry-run` to preview without changing the sandbox.
A run with `NEMOCLAW_NON_INTERACTIVE=1`, or a run without a terminal on stdin, does not prompt and requires one of those acknowledgement flags.

```bash
$$nemoclaw my-assistant policy exclude nous_research --dry-run
$$nemoclaw my-assistant policy exclude nous_research --force
```

When a release changes an excluded entry, first run `$$nemoclaw <name> policy restore <key> --dry-run` to preview the current baseline egress that restoration would allow again.
After you review the output, run `$$nemoclaw <name> policy restore <key> --force` to allow that egress again and clear the stale exclusion record.
Then preview the current exclusion scope with `$$nemoclaw <name> policy exclude <key> --dry-run` and reapply it with `$$nemoclaw <name> policy exclude <key> --force` only if you still accept the support impact.
When a release removes the entry, first run `$$nemoclaw <name> policy restore <key> --dry-run` to confirm that restoration will clear only the stale exclusion record.
After you review the output, run `$$nemoclaw <name> policy restore <key> --force`; there is no replacement scope to review or approve.

### `$$nemoclaw <name> policy restore <key>`

Restore a previously excluded entry from the current agent baseline and clear its durable exclusion record.
When the current baseline still defines the entry, `--dry-run` lists the egress that restoration would allow again.
After you review the output, `--force` allows that egress again and clears the exclusion record.
When the baseline no longer defines the entry, `--dry-run` states that restoration will clear only the stale exclusion record.
After you review the output, `--force` clears that record without changing live egress.
Both paths require explicit acknowledgement unless you use `--dry-run`; use `--force` or `--yes` for non-interactive acknowledgement.
As with `policy exclude`, a run with `NEMOCLAW_NON_INTERACTIVE=1`, or a run without a terminal on stdin, does not prompt.
If a restore is interrupted, NemoClaw finalizes it only when the durable exclusion still exactly matches the staged exclusion and the current release baseline still exactly matches the journaled live target.
If either value changed or the current baseline is unreadable, the journal remains in `repair required` state so you can inspect and re-review the current scope instead of silently accepting a different entry.

```bash
$$nemoclaw my-assistant policy restore nous_research --dry-run
$$nemoclaw my-assistant policy restore nous_research --force
```

The restore command accepts these flags:

| Flag | Description |
|------|-------------|
| `--yes`, `-y`, `--force` | Skip the confirmation prompt |
| `--dry-run` | Preview the egress restoration or stale-record cleanup without applying changes |

### `$$nemoclaw <name> policy explain`

Print a redacted summary of the active policy context for a sandbox so an agent or operator can reason about what is allowed, what is blocked, and how to request a change.
The output covers the recorded tier, applied presets and allowed host categories, known unapplied presets, baseline exclusions and their support impact, policy-change commands, and the support boundaries between NemoClaw, OpenShell, and the agent.
Raw policy YAML, rule bodies, and credential metadata are deliberately not included.

```bash
$$nemoclaw my-assistant policy explain
```

Pass `--json` to emit the same context as a structured object for agent consumption:

```bash
$$nemoclaw my-assistant policy explain --json
```

<AgentOnly variant="openclaw">
NemoClaw refreshes the rendered context inside the sandbox at `/sandbox/.openclaw/workspace/POLICY.md` whenever a preset is added or removed, and once at the end of the onboarding policy step.
Pass `--write` to refresh that file on demand without changing the policy:

```bash
$$nemoclaw my-assistant policy explain --write
```
</AgentOnly>

The context also documents how a failed host or integration attempt should be classified.
The classifications are `blocked-by-policy`, `missing-approval`, `unsupported`, and `unknown`, so the agent can pick a remediation step instead of surfacing a lower-level network error.

| Flag | Description |
|------|-------------|
| `--json` | Emit the policy context as a structured JSON object for agent consumption |
<AgentOnly variant="openclaw">
| `--write` | Refresh `/sandbox/.openclaw/workspace/POLICY.md` inside the sandbox in addition to printing |
</AgentOnly>

### `$$nemoclaw <name> hosts-add`

Add a host alias to the sandbox pod template.
Use this when a sandbox needs a stable LAN-only name, such as a local SearXNG or internal model endpoint, without dropping to `docker exec` and `kubectl patch`.
Host alias commands use the legacy Kubernetes gateway `Sandbox` resource path.
In that older topology, the `openshell-cluster-nemoclaw` container runs an embedded k3s cluster with a `sandboxes.agents.x-k8s.io` custom resource definition, and an `agent-sandbox-controller` reconciles each `Sandbox` resource into the agent pod.
They are not supported on Docker-driver or VM-driver sandboxes because those drivers do not run the gateway cluster container that owns this resource.

```bash
$$nemoclaw my-assistant hosts-add searxng.local 192.168.1.105
```

The command validates the hostname and IP address, rejects duplicate hostnames, and patches `spec.podTemplate.spec.hostAliases` on the sandbox resource.

| Flag | Description |
|------|-------------|
| `--dry-run` | Print the JSON patch for the resulting `hostAliases` list without applying it |

### `$$nemoclaw <name> hosts-list`

List host aliases configured on the sandbox resource.

```bash
$$nemoclaw my-assistant hosts-list
```

### `$$nemoclaw <name> hosts-remove`

Remove a hostname from the sandbox `hostAliases` list.

```bash
$$nemoclaw my-assistant hosts-remove searxng.local
```

| Flag | Description |
|------|-------------|
| `--dry-run` | Print the JSON patch for the resulting `hostAliases` list without applying it |

<AgentOnly variant="openclaw,hermes">

### `$$nemoclaw <name> channels list`

List the messaging channels supported by the sandbox's agent runtime with a short description.
Telegram, Discord, Slack, WeChat, WhatsApp, and Microsoft Teams are available for OpenClaw and Hermes.
WeChat, WhatsApp, and Microsoft Teams are experimental.
OpenClaw also supports experimental Google Chat.

The command reads the sandbox registry to select agent-compatible channel manifests.
It does not inspect messaging credentials or the live sandbox runtime.

```bash
$$nemoclaw my-assistant channels list
```

### `$$nemoclaw <name> channels add <channel>`

Register a messaging channel with the sandbox and rebuild so the image picks up the new channel.
Channel enrollment uses these credential and pairing flows:

- **Token paste** (`telegram`, `discord`, `slack`, `teams`): the command prompts for required channel inputs.
  It registers secret credentials with the OpenShell gateway and saves non-secret configuration for rebuilds.
- **Host-side QR** (`wechat`, experimental): the command renders an iLink QR code on the host and you scan it from WeChat on your phone.
  On confirm, NemoClaw captures the bot token, registers it with the OpenShell gateway, and stores non-secret per-account metadata (`WECHAT_ACCOUNT_ID`, `WECHAT_BASE_URL`, `WECHAT_USER_ID`) for the in-sandbox bridge.
  NemoClaw automatically adds the scanning operator's WeChat user ID to `WECHAT_ALLOWED_IDS`.
  Supply additional comma-separated IDs to authorize more DM senders.
  NemoClaw advertises WeChat for both OpenClaw (the `@tencent-weixin/openclaw-weixin` plugin) and Hermes (the built-in iLink WeChat adapter).
- **In-sandbox QR** (`whatsapp`, experimental): the command records the channel without a host-side token or OpenShell credential provider.
  NemoClaw advertises WhatsApp for OpenClaw and Hermes sandboxes; after rebuild, run `openclaw channels login --channel whatsapp` for OpenClaw or `hermes whatsapp` for Hermes.
  This intentionally leaves QR-created mutable session state in the sandbox until you unpair it or clear the durable agent state.

The OpenClaw-only Google Chat channel uses an experimental token-paste flow for the service-account JSON.
It also requires interactive public-webhook confirmation and prompts for optional app-principal configuration during enrollment.

After registering the channel, NemoClaw asks whether to rebuild immediately.
Running `add` for an already-configured channel overwrites the stored credentials where applicable.
The operation is idempotent.
Channel names are trimmed and lowercased before NemoClaw stores credentials, names bridge providers, or prints rebuild messages.
NemoClaw requires the matching built-in network policy preset YAML to be present.
A missing or malformed preset YAML (no `network_policies:` section) aborts `channels add` before any token prompt, registry write, or rebuild prompt.
After validating that preset, NemoClaw discloses its effect before prompting for credentials or changing gateway or registry state.
It prints the exact effective egress scope when the preset would open or replace access, or reports that no new egress would be opened when the preset is already effective.
The `--dry-run` path prints the same disclosure without collecting credentials or applying changes.
With the preset file in place, NemoClaw applies it to the sandbox before the rebuild so the bridge has egress to its upstream API.
When the apply step itself fails after the registry write on a fresh add, NemoClaw attempts to roll back the bridge providers, the `messagingChannels` entry, and any staged environment credentials, then exits without prompting for a rebuild; if any gateway-side step (provider detach or delete) fails the rollback continues and prints a `Rollback could not fully clean <surfaces>` warning so the operator can clean up manually.
When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior `messagingChannels` entry, restores staged environment credentials when available, restores registry credential hashes, and attempts to re-upsert the prior bridge providers, but flags `gateway-providers` as residual because the in-flight upsert may have left the gateway with the new token; verify the gateway bridge before relying on the channel.
Restore the preset YAML and re-run `$$nemoclaw <name> channels add <channel>`.
For Telegram, Discord, and Slack, a rebuild triggered by `channels add` also verifies that the selected bridge starts and reports credential, startup, or plugin discovery warnings.

```bash
$$nemoclaw my-assistant channels add telegram
```

| Flag | Description |
|------|-------------|
| `--dry-run` | Validate the channel name and matching policy preset without prompting for credentials, contacting the gateway, or rebuilding |
| `--force` | Add the channel despite a credential conflict, shared-resource conflict, or incomplete required check. This flag is the only conflict override. |

Slack requires both `SLACK_BOT_TOKEN` (bot user OAuth) and `SLACK_APP_TOKEN` (app-level Socket Mode token); the command prompts for each in turn.
The conflict check compares only sandboxes in the selected OpenShell gateway's sandbox registry.
It cannot detect Slack token reuse across independent OpenShell gateways.
Run only one active Slack sandbox on each OpenShell gateway, and use distinct Slack bot and app tokens across gateways.
Optional Slack allowlists come from `SLACK_ALLOWED_USERS` and `SLACK_ALLOWED_CHANNELS` at rebuild time.
Telegram and Discord mention mode default to `1` when no environment, session, or saved state value exists for that setting.
Discord applies that default only when a server ID is configured.
A run with `NEMOCLAW_NON_INTERACTIVE=1`, or a run without a terminal on stdin, fails fast on any missing token and shows no rebuild prompt.
Instead, the change is queued and you are told to run `$$nemoclaw <name> rebuild` manually.
An SSH command without `-t`, a service unit, or a CI job has no terminal on stdin, so it does not need `NEMOCLAW_NON_INTERACTIVE=1` to reach this path.
If you omit the required `<channel>` argument, the CLI prints the `channels add <channel>` usage with the supported channel list instead of falling back to top-level help.

### `$$nemoclaw <name> channels remove <channel>`

Clear the stored credentials for a messaging channel and rebuild the sandbox so the image drops the channel.
Running `remove` for a channel that was never configured is a no-op against the credentials file and still triggers the rebuild prompt.
When the bridge provider is attached to a live sandbox, NemoClaw detaches it before deleting the provider from the OpenShell gateway.
If the matching built-in policy preset is applied, NemoClaw also removes that preset so the upstream API is no longer allow-listed after the channel is gone.
NemoClaw also strips the channel from `session.policyPresets` so a subsequent `onboard --resume` does not re-apply the preset on the next rebuild.

For QR-paired channels (today: WhatsApp), NemoClaw destructively clears the in-sandbox session directories before the rebuild so the `state_dirs` backup does not restore the auth blob and let the channel reconnect:

- OpenClaw: `/sandbox/.openclaw/<channel>/` (for example `/sandbox/.openclaw/whatsapp/`).
- Hermes: `/sandbox/.hermes/platforms/<channel>/` (for example `/sandbox/.hermes/platforms/whatsapp/`).
  For WhatsApp, NemoClaw also clears the current Dashboard profile at `/sandbox/.hermes/profiles/dashboard-home/platforms/whatsapp/session/` and the legacy migration source at `/sandbox/.hermes/dashboard-home/platforms/whatsapp/session/`.

The cleanup tries `openshell sandbox exec` first and falls back to SSH if the exec wrapper does not return the success sentinel. If both transports fail (the sandbox is stopped, the gateway is down, or SSH cannot reach it) the command refuses to proceed to the rebuild and asks you to start the sandbox and re-run, so a half-removed state cannot leave stale Baileys auth files behind for the next rebuild to restore.

```bash
$$nemoclaw my-assistant channels remove telegram
```

| Flag | Description |
|------|-------------|
| `--dry-run` | Report the channel that would be removed without clearing credentials or rebuilding |

As with `channels add`, `NEMOCLAW_NON_INTERACTIVE=1` or a run without a terminal on stdin skips the rebuild prompt and queues the change for a manual `$$nemoclaw <name> rebuild`.
`channels start` and `channels stop` follow the same rule.
If you omit the required `<channel>` argument, the CLI prints the `channels remove <channel>` usage with the supported channel list.

Host-side removal is the supported path because agent channel config is baked into the container image at build time (`/sandbox/.openclaw/openclaw.json` for OpenClaw and `/sandbox/.hermes/.env` for Hermes); agent-specific channel removals inside the sandbox would modify the running config but not persist changes across rebuilds.

### `$$nemoclaw <name> channels stop <channel>`

Pause one configured messaging channel without clearing its credentials.
The command verifies that the sandbox's agent runtime supports the channel before reading configured or disabled channel state.
It then requires the channel to be configured for the sandbox.
The channel is marked disabled in the per-sandbox registry, and the sandbox is rebuilt so the onboard step skips registering the bridge with the gateway.
The provider stays registered with the OpenShell gateway, so a later `channels start` brings the bridge back without re-entering tokens.

```bash
$$nemoclaw my-assistant channels stop telegram
```

| Flag | Description |
|------|-------------|
| `--dry-run` | Report the channel that would be disabled without updating the registry or rebuilding |

Use `channels stop` instead of `channels remove` when you want to pause a bridge temporarily. `channels remove` is destructive to credentials; `channels stop` is not.

### `$$nemoclaw <name> channels start <channel>`

Re-enable a channel previously paused with `channels stop`. The channel is removed from the disabled list, the sandbox is rebuilt, and the bridge registers with the gateway again using the stored credentials.
The command verifies that the sandbox's agent runtime supports the channel before reading configured or disabled channel state.
It then requires the channel to be configured for the sandbox.
Before the rebuild, NemoClaw reapplies the matching built-in network policy preset so the restored bridge has egress to its upstream API.
Before updating the disabled list or applying the policy, NemoClaw prints the exact effective egress scope when the preset would open or replace access, or reports that no new egress would be opened when the preset is already effective.
If policy restoration fails, NemoClaw rolls the channel back to disabled and exits without rebuilding into a partially active state.

```bash
$$nemoclaw my-assistant channels start telegram
```

| Flag | Description |
|------|-------------|
| `--dry-run` | Report the channel that would be re-enabled without updating the registry or rebuilding |

### `$$nemoclaw <name> channels status`

Run messaging channel status checks.
Without `--channel`, the command prints a compact summary for every configured channel, including registration, policy coverage, and non-secret rendered config comparisons.
For channel and agent combinations that support a detailed probe, the summary adds a `Runtime health: not checked in summary view` pointer instead of running the probe, so it never reads as healthy without an explicit check.
With `--channel`, it prints the detailed status for that channel.

For an OpenClaw WhatsApp sandbox, `--channel whatsapp` probes the sandbox to separately report pairing/session state, the Noise WebSocket connection, inbound event delivery, and policy coverage.
A paired channel with no observed inbound delivery exits non-zero with verdict `idle` so an unhealthy bridge cannot pass as healthy.
The detailed WhatsApp probe stays focused on QR/session runtime diagnostics and does not include rendered-config comparison lines.
For a Hermes WhatsApp sandbox, `--channel whatsapp` first checks the shared gateway path and the `profiles/dashboard-home` path for `creds.json`.
The status compatibility probe has this contract:

| Property | Contract |
|------|-------------|
| Owner | The NemoClaw WhatsApp status hook owns the probe. |
| Scope | The hook reads only `platforms.whatsapp.extra.session_path` from `/sandbox/.hermes/config.yaml` when the durable session path has no `creds.json`. The hook does not write the field or configure Hermes. |
| Validation | The value must be an absolute path under `/sandbox/.hermes` with no `.` or `..` segment. |
| Supported state | The durable Hermes WhatsApp session remains `/sandbox/.hermes/platforms/whatsapp/session`. The compatibility field is not a supported NemoClaw setup or session-storage control. |
| Support period | Keep the probe only while a supported Hermes image can place dashboard-paired credentials outside the durable path. |
| Retirement | [Issue #8947](https://github.com/NVIDIA/NemoClaw/issues/8947) tracks removal after every supported Hermes image uses the durable path for dashboard pairing and gateway startup. |

After validation, the command checks the configured path and reports a `Session path override` signal.
An unsupported path produces a warning, and the report uses the default gateway path.
If the dashboard path has credentials and the gateway path is empty, the report tells you to run `$$nemoclaw <sandbox> channels remove whatsapp` and then `$$nemoclaw <sandbox> channels add whatsapp`, because a rebuild restores the legacy session instead of dropping it.
Pair again from the dashboard so credentials use `/sandbox/.hermes/platforms/whatsapp/session`.
Rerun `$$nemoclaw <sandbox> channels status --channel whatsapp`.
NemoClaw does not treat a Hermes session file as live inbound-health evidence.

For Telegram, `--channel telegram` probes the sandbox to report the gateway process, Bot API reachability, and inbound delivery alongside the config comparison.
It classifies the state as `healthy`, `idle`, `token_rejected`, `unreachable`, `not_started`, `policy_gap`, `config_gap`, `unknown`, or `probe_failed`.
A network or egress failure, or a non-authentication Bot API startup HTTP error, produces `unreachable`; a 401 or 404 response produces `token_rejected`.
It reads the gateway's own startup and poll log breadcrumbs rather than issuing its own Bot API request, so the resolved bot token never leaves the gateway.
The verdict reflects the most recent evidence in the log window, so a bridge that recovered after a blocked start reports `healthy` while one blocked again reports `unreachable`.
Telegram health is probed only for OpenClaw sandboxes; a Hermes Telegram sandbox uses the basic config report.

For OpenClaw Slack, `--channel slack` reports registration, policy coverage, the account runtime, Socket Mode transport, and the account probe.
Add `--wait` to poll these conditions until Slack becomes operational, a terminal error occurs, or the timeout expires.
The default timeout is 180 seconds, and `--timeout <seconds>` requires `--wait`.
NemoClaw treats the timeout as the total budget for polling and live probes, limits each live probe to the remaining budget, and starts no probe at or after the deadline.
Use `--json` with `--wait` for a structured readiness result with `readiness.state`, `readiness.category`, `readiness.reason`, `readiness.retryable`, `readiness.attempts`, `readiness.elapsedMs`, `readiness.lastTransitionAt`, and `readiness.lastObserved`.
Slack `--wait` applies only to OpenClaw sandboxes and uses its manifest-defined check; other channel manifests return `readiness_not_supported` until they define one.
For an OpenClaw sandbox, if Slack is paused with `channels stop`, the command skips the live probe and returns one terminal result with `readiness.reason` set to `channel_paused`.
On timeout, the command exits nonzero with `readiness.state`, `readiness.category`, and `readiness.reason` set to `timeout`; its `readiness.retryable` mirrors the last observed state, whose category and reason preserve the underlying cause.

For registered channel details and the compact summary, the status output compares non-secret config inputs from the sandbox registry against the values rendered into the agent config, such as Telegram group policy in `openclaw.json` or mention mode in Hermes config.
Secret inputs, including tokens, are not printed.
If the registry contains a non-secret expected value but NemoClaw cannot read or check the rendered source, the comparison is a warning and the detail includes `(not checked)`.
Optional unset inputs remain informational.

```bash
$$nemoclaw my-assistant channels status
$$nemoclaw my-assistant channels status --channel whatsapp
$$nemoclaw my-assistant channels status --channel telegram
$$nemoclaw my-assistant channels status --channel slack --wait --timeout 180 --json
```

| Flag | Description |
|------|-------------|
| `--channel <channel>` | Channel to inspect in detail |
| `--wait` | Wait for the selected channel's manifest-defined readiness check (requires `--channel`) |
| `--timeout <seconds>` | Stop waiting after this number of seconds (default: `180`; requires `--wait`) |
| `--json` | Emit the status or readiness report as JSON; non-ready terminal and timeout results exit nonzero |

Each live probe is bounded by an in-sandbox `openshell sandbox exec` with a hard timeout.
The WhatsApp probe returns strict OpenClaw status JSON to the host, where NemoClaw allowlists pairing, liveness, connection-state, and timestamp fields before rendering the report and discards phone-number and free-text error fields.
The Hermes WhatsApp probe returns fixed session-presence booleans to the host.
When the shared gateway path is empty, a sandbox-local parser can also return the configured WhatsApp session path.
The parser does not return other Hermes configuration values.
NemoClaw validates the path before it uses the path in a second session-presence probe.
The Telegram probe returns only matched gateway log lines to the host, where NemoClaw reduces them to fixed classifications without rendering the raw lines, message bodies, or tokens.
The Slack probe returns OpenClaw status JSON to the host.
NemoClaw reduces it to allowlisted account booleans, credential availability, probe success, fixed error categories, and timestamps; the rendered and JSON readiness reports omit tokens and free-text errors.

</AgentOnly>

### `$$nemoclaw <name> mcp list`

List MCP servers configured for a sandbox.
The command reports the selected agent's MCP support status and, for each configured server, whether the generated OpenShell provider, policy, and agent adapter are present.

```bash
$$nemoclaw my-assistant mcp list [--json]
```

| Flag | Description |
|------|-------------|
| `--json` | Emit sandbox, support, and MCP server state as JSON without credential values |

### `$$nemoclaw <name> mcp add`

Add an MCP Streamable HTTP server to a sandbox.
Pass `--url` for the MCP endpoint and the required single `--env KEY` bearer credential for the sandbox-side MCP client.
Pass a repeatable `--trusted-private-host <exact-host-or-ip>` option to admit an exact RFC1918, CGNAT, or IPv6 unique local destination for the current command.
The declaration must equal the normalized host from `--url`.
For managed MCP, use a DNS hostname for an IPv6 unique local address because NemoClaw has not qualified direct IPv6-literal MCP URLs.
You can supply exact hosts through `NEMOCLAW_TRUSTED_PRIVATE_HOSTS` instead, and NemoClaw combines the variable with command options.
NemoClaw records the resulting exact trust intent and address pins, so restart, rebuild, and restore do not depend on the ambient environment.
NemoClaw registers that credential in an OpenShell provider, installs a generated OpenShell `protocol: mcp` policy for the target endpoint, attaches the provider to the running sandbox, and writes only an `openshell:resolve:env:KEY` placeholder into the agent config.
Inline `--env KEY=VALUE` is rejected because it would expose the value in NemoClaw process arguments.
Load the variable from a secret manager or masked prompt, export it without recording the value in shell history, and pass only `--env KEY`.
All endpoints must use HTTPS.
The full URL and path are persisted and displayed, so URLs cannot contain userinfo, query strings, fragments, known secret-shaped path material, percent-escaped or glob-style paths, or port zero.
Server names must start with a letter and contain at most 64 letters, digits, hyphens, or underscores, and endpoint hostnames must use canonical lowercase DNS labels.
NemoClaw rejects invalid names and endpoints before it writes lifecycle state or changes OpenShell resources.
NemoClaw generates a narrow `protocol: mcp` policy for the destination, literal path, adapter binaries, pinned addresses, explicit MCP methods, and a 131,072-byte request-body limit.
OpenShell `0.0.101` evaluates that policy before replacing the attached provider placeholder in the allowed request header.
Static provider placeholders are sandbox-scoped rather than endpoint-exclusive, so do not grant broader inspected-HTTP routes to the same adapter runtime and credential key.
The sandbox client connects directly through OpenShell's existing egress path, and NemoClaw does not run a host-side MCP data-plane bridge, proxy, relay, or listener.
After the add commits, NemoClaw freshly verifies the exact generated policy, expected provider attachment, recorded provider ID, generic type, valid resource version, and exactly one credential key matching the recorded key.
If those readiness checks pass, it sends a differential pair of wire-level MCP `initialize` requests from inside the sandbox — one with the placeholder header and one with an unresolvable control bearer — to verify that OpenShell resolves the credential on egress; otherwise it reports an inconclusive `probe skipped` result and sends no request.
Neither outcome fails the committed add, and `--no-probe` skips this check.
For full setup details, see [Add an MCP Server](../manage-sandboxes/mcp-servers/add-an-mcp-server).

<AgentOnly variant="hermes">

Hermes MCP add, restart, and remove mutate managed config and are refused while shields are up.
Run `$$nemoclaw <name> shields down --timeout 15m --reason "MCP maintenance"` before the mutation, then run `$$nemoclaw <name> shields up` after it; list and status remain read-only.
Allow at least 15 minutes per configured server for an all-server restart or destroy; rebuild opens its own crash-recoverable maintenance window.
Keep shields down until the command returns; a concurrent relock refuses the config commit and can leave an earlier policy/provider stage for the next retry to converge.

</AgentOnly>
<AgentOnly variant="deepagents">

Deep Agents MCP add and restart require the managed MCP v2 capability in the sandbox image.
If `mcp add` or `mcp restart` reports an older v1 runtime, run `nemo-deepagents <name> rebuild` before retrying.
NemoClaw writes managed server definitions to `/sandbox/.deepagents/.nemoclaw-mcp.json`; user-owned `.mcp.json` files are not auto-loaded by the managed harness.

</AgentOnly>

```bash
export GITHUB_MCP_TOKEN=ghp_...
$$nemoclaw my-assistant mcp add github --url https://api.githubcopilot.com/mcp/ --env GITHUB_MCP_TOKEN
unset GITHUB_MCP_TOKEN
```

For a private endpoint, use its exact URL host:

```bash
export LOCAL_MCP_TOKEN='replace-with-secret-manager-value'
$$nemoclaw my-assistant mcp add local-tools \
  --url https://mcp-host.corp.example/mcp \
  --env LOCAL_MCP_TOKEN \
  --trusted-private-host mcp-host.corp.example
unset LOCAL_MCP_TOKEN
```

### `$$nemoclaw <name> mcp status`

Inspect MCP server state for one server or for all configured servers.
Status includes OpenShell provider presence and credential-key shape, provider attachment, generated policy content match, adapter registration, current host-variable availability, and the selected agent's MCP support mode.
For a trusted private endpoint, status also compares current DNS answers with recorded pins without changing the policy.
Text output reports `private address pins: match`, `drift`, or `unresolved`.
JSON output reports the same value in `trustedPrivateTarget.state` and includes the recorded pins.
While a managed provider is attached, text and JSON status warn that its credential is sandbox-scoped until OpenShell supports endpoint-exclusive binding plus Host, scheme, and query enforcement.
When a single server is named, status requests a differential wire-level credential-resolution probe.
It sends no probe traffic unless the exact generated policy matches the effective gateway policy, the expected provider attachment is confirmed, and the live provider has the recorded ID, generic type, a valid resource version, and exactly one credential key matching the recorded key; a readiness failure reports `unknown` with a `probe skipped` detail.
When ready, the same MCP `initialize` is sent from inside the sandbox once with the `openshell:resolve:env:KEY` placeholder header and once with a deliberately-unresolvable control bearer.
Classification uses the two HTTP status codes plus curl exit codes for transport, timeout, and policy-denial outcomes; response bodies are never captured or printed.
A `verified` verdict requires the placeholder request to be accepted (HTTP 2xx) while the control is rejected — the only outcome that proves a valid credential was on the wire.
Identical HTTP 400, 401, or 403 rejections raise a warning that names the hypotheses — the placeholder forwarded verbatim, an expired or revoked credential that resolved correctly, or (for HTTP 400) endpoint request validation — and tells you to verify the stored credential first.
For HTTP 401 or 403, a confirmed-valid credential means the host is not rewriting placeholders and agent runtimes receive the same auth failure and skip the server; HTTP 400 remains inconclusive because the endpoint may reject the probe request itself.
Every other outcome — differing rejections (an endpoint may reject two different literal bearers differently), endpoints that skip authentication, endpoint outages, policy denials, and unreachable sandboxes — reports as `unknown` rather than blaming the credential rewrite, and a persisted URL that fails the current authenticated-endpoint boundary is never probed.

Pass `--tools` with one server name to request a live tool inventory.
The shared client runs through the managed registration's existing OpenShell credential provider and policy; OpenShell injects the credential at that boundary, and the runtime never accepts it as an argument, environment value, or authorization option.
It performs `initialize`, `notifications/initialized`, and paginated `tools/list`, then attempts to close the MCP session and transport.
Cleanup errors do not replace the bounded discovery result.
It retains and returns deterministic tool names only, never prints the other tool-definition fields returned by `tools/list`, and never calls a tool.
The operation is bounded by total and per-request timeouts plus response-byte, page, tool-count, cursor-length, and tool-name limits.

Use `--tools` only with a configured endpoint you trust to advertise names while authenticated.
The endpoint controls its returned names and can derive them from the request or credential it receives; NemoClaw validates and bounds the text but cannot prove that the endpoint did not encode credential-derived data in an otherwise valid name.

The `toolDiscovery` JSON field contains `ok`, `count`, `tools`, and `truncated`, plus a redacted `detail` on failure or a bounded partial result.
These names are the server's point-in-time advertised tools, not an attestation of the exact tools visible to the model after agent filters, progressive disclosure, or session state.
An older sandbox image without the shared client reports that the sandbox must be rebuilt.

Tool discovery is opt-in and sends authenticated network traffic to the configured endpoint.
Passing `--tools` suppresses the named-server credential-resolution probe that otherwise runs by default.
Pass `--probe --tools` to request both checks explicitly.
An unsuccessful discovery does not remove the ordinary provider, policy, environment, or adapter status from the result.

```bash
$$nemoclaw my-assistant mcp status [server] [--json] [--probe|--no-probe] [--tools]
```

| Flag | Description |
|------|-------------|
| `--json` | Emit status as JSON without credential values |
| `--probe` | Request the wire-level credential-resolution probe for every listed server; entries that fail readiness checks are skipped |
| `--no-probe` | Skip the probe; it defaults on only when a single server is named |
| `--tools` | Request advertised tool names from one trusted configured endpoint through its managed credential provider; suppresses the implicit credential probe unless `--probe` is also passed |

### `$$nemoclaw <name> mcp restart`

Refresh one MCP server registration, or every server on the sandbox when no server is supplied.
Restart reapplies the generated policy, reattaches the OpenShell provider when needed, and refreshes the sandbox agent adapter registration.
For a trusted-private entry, restart replays recorded address pins without resolving the endpoint again or widening the policy.
For a public entry, restart resolves the hostname again and refreshes the policy with the current validated public addresses.
If the recorded host variable is exported, restart replaces the provider credential and waits for its new opaque revision.
Otherwise, restart reuses an existing provider whose current metadata match the registry.
A missing provider requires the variable to be exported before retrying.
When that provider is already absent but its name still blocks sandbox exec,
restart first detaches only the dangling sandbox-spec reference, then runs the
agent capability probe before changing a live provider or policy.

<AgentOnly variant="hermes">

Hermes shields must be down for this config mutation.
Keep them down until the command returns; a concurrent relock refuses the config commit and can leave an earlier policy/provider stage for the next retry to converge.

</AgentOnly>
<AgentOnly variant="deepagents">

Deep Agents restart refreshes the NemoClaw-managed `/sandbox/.deepagents/.nemoclaw-mcp.json` projection and validates the HTTPS-only server definitions before `dcode` sees them.
If the sandbox still uses the older v1 MCP projection, rebuild first so restart can use the v2 capability.

</AgentOnly>

```bash
$$nemoclaw my-assistant mcp restart [server]
```

### `$$nemoclaw <name> mcp remove`

Remove an MCP server from a sandbox.

<AgentOnly variant="hermes">

Hermes shields must be down for this config mutation.
Keep them down until the command returns; a concurrent relock refuses the config commit and can leave an earlier policy/provider stage for the next retry to converge.

</AgentOnly>

NemoClaw unregisters the sandbox agent adapter, prechecks and removes the recorded OpenShell provider, removes the owned generated policy, and clears the sandbox registry entry.
Deep Agents teardown does not require managed MCP capability v2 from the old image.
For a v1 image, NemoClaw removes the exact registry-owned entry from the legacy `.mcp.json` while preserving unrelated user state; a replacement image must pass the v2 capability check before post-rebuild providers or policy are restored.
The command fails closed on observed drift.
`--force` may remove a modified same-name agent adapter entry, but provider deletion still requires the exact recorded ID, type, and credential key and policy deletion still requires exact owned content.
Residuals preserve registry state.
OpenShell `0.0.101` mutates providers by name, so do not concurrently replace a managed provider through another OpenShell client during this command.

When an interrupted destroy leaves a prepared-only transaction, deletion is not durably confirmed.
If the sandbox is still live, run `$$nemoclaw <name> mcp remove <server> --force` with the affected server name.
NemoClaw clears the prepared marker only after cleanup succeeds without residuals and no bridge entries remain.
A failed cleanup, a wrong server name, residual resources, or any remaining bridge entry preserves the marker for another retry.

A pending marker, including a transaction with both prepared and pending markers, means the registry records that OpenShell deletion was already confirmed.
`mcp remove --force` refuses this state.
Run `$$nemoclaw <name> destroy` to finish the idempotent provider and policy cleanup.

```bash
$$nemoclaw my-assistant mcp remove github [--force]
```

| Flag | Description |
|------|-------------|
| `--force` | Remove same-name adapter config and continue exact-ownership provider and policy cleanup. For a prepared-only destroy, attempt recovery when the sandbox is still live and clear the marker only after residual-free cleanup drains every bridge entry. |

### `$$nemoclaw <name> skill install <path>`

Deploy a skill directory to a running sandbox.
The command validates the `SKILL.md` frontmatter, which requires a `name` field.
It uploads selected non-dot regular files while preserving their subdirectory structure.
It then performs agent-specific post-install steps.

```bash
$$nemoclaw my-assistant skill install ./my-skill/
```

The skill directory must contain a `SKILL.md` file with YAML frontmatter that includes a `name` field.
Skill names must contain only alphanumeric characters, dots, hyphens, and underscores.

<AgentOnly variant="openclaw">

OpenClaw plugins are a different kind of extension.
To install an OpenClaw plugin, refer to [Install OpenClaw Plugins](../manage-sandboxes/install-openclaw-plugins).
For OpenClaw, the command uploads the skill to the OpenClaw state directory and mirrors it into `$HOME/.openclaw/skills/<name>` when the agent home directory differs from the state directory.
That mirror makes skills listed by `openclaw skills list` available at session startup.
If mirror creation fails, NemoClaw prints a warning so you can reinstall or inspect the home directory permissions.
OpenClaw caches skill content per session, so the command also refreshes the OpenClaw session index after every install and update to avoid stale `SKILL.md` data.

</AgentOnly>
<AgentOnly variant="hermes">

Hermes plugins are different from NemoClaw skills.
`skill install` uploads agent skills, while Hermes plugin configuration is managed by the Hermes runtime and the NemoClaw Hermes plugin baked into the sandbox image.
The NemoClaw Hermes plugin reloads installed skills when a new chat session starts.
Start a new Hermes chat session after an install or update; a gateway restart is not required.

</AgentOnly>
<AgentOnly variant="deepagents">

For Deep Agents, the command installs a fresh skill directly into `/sandbox/.deepagents/agent/skills/<name>`, the directory Deep Agents Code loads at session start.
Before upload, NemoClaw copies each selected regular file into a private host snapshot and rejects a path that changes identity during the copy.
It creates the archive from that snapshot and records each path, normalized mode, and SHA-256 digest.
It rejects symlinks and special files.
Inside the sandbox, it stages the archive and verifies that its paths, normalized modes, and SHA-256 digests match the host snapshot.
It then moves the staged directory into place only if the destination is still absent.
On success, the command prints the content digest that the sandbox confirmed: one SHA-256 digest over the recorded paths, normalized modes, and file digests.
Record that value to compare it with the digest printed by a later install of the same skill directory.
Deep Agents Code and its built-in skill creator also write to this directory.
The command therefore refuses any name whose file, directory, or symlink already exists.
Updates are not automatic.
Use `$$nemoclaw <name> connect` to inspect the existing directory.
Update it manually only after confirming ownership.
The legacy `/sandbox/.deepagents/skills/<name>` path is not written or treated as ownership proof.
The managed `dcode` launchers discover newly installed skills on the next session without accepting executable hook configuration.
Installation does not enable project hooks or unmanaged MCP files.

</AgentOnly>

Run `$$nemoclaw <name> skill install --help` to print usage for this subcommand.
If you pass a plugin-shaped directory to `skill install`, the CLI prints a plugin-specific hint instead of treating it as a missing skill file.

Files with names starting with `.` (dotfiles) are skipped and listed in the output.
Files with unsafe path characters are rejected to prevent shell injection.
Symlinks and other non-regular paths are rejected rather than followed or copied.

For OpenClaw and Hermes, an existing sandbox skill is updated in place and chat history is preserved.
Deep Agents supports only fresh-name installs because its active skill directory is shared with agent-authored content.
Follow the agent-specific activation guidance above after installation.

### `$$nemoclaw <name> skill remove <skill>`

Remove an installed skill from a running sandbox by skill name when the selected agent supports automatic removal.
The command validates the skill name before it applies the agent-specific removal behavior below.

<AgentOnly variant="openclaw">

For OpenClaw, the command also removes the OpenClaw home-directory mirror when present and refreshes the OpenClaw session index.

</AgentOnly>
<AgentOnly variant="hermes">

Start a new Hermes chat session for the removal to take effect.
A gateway restart is not required.

</AgentOnly>
<AgentOnly variant="deepagents">

For Deep Agents, automatic removal is refused before any sandbox files change.
The active `/sandbox/.deepagents/agent/skills/<name>` directory is shared with agent-authored content, so its presence alone cannot prove NemoClaw owns it.
Use `$$nemoclaw <name> connect` to inspect the existing directory.
Remove it manually only after confirming ownership.

</AgentOnly>

```bash
$$nemoclaw my-assistant skill remove my-skill
```

Use the skill name from the `SKILL.md` frontmatter, not the local directory name.
Skill names must contain only alphanumeric characters, dots, hyphens, and underscores, and cannot be `.` or `..`.

<AgentOnly variant="openclaw">

### `$$nemoclaw <name> agents list`

List the OpenClaw agents configured in the sandbox.
This is a thin pass-through to `openclaw agents list` via `openshell sandbox exec`; the OpenClaw CLI owns the gateway `agents.list` call, output formatting, and binding summaries.
Flags accepted by the in-sandbox CLI (`--json`, `--bindings`) are forwarded verbatim.

```bash
$$nemoclaw my-assistant agents list
$$nemoclaw my-assistant agents list --json
$$nemoclaw my-assistant agents list --bindings
```

### `$$nemoclaw <name> agents add`

Run the OpenClaw interactive add wizard inside the sandbox.
This is a thin pass-through to `openclaw agents add` via `openshell sandbox exec`; flags accepted by the in-sandbox CLI are forwarded verbatim.

```bash
$$nemoclaw my-assistant agents add
$$nemoclaw my-assistant agents add work --model gpt-4o
```

### `$$nemoclaw <name> agents delete <agent-id>`

Remove an OpenClaw agent from the sandbox.
This is a thin pass-through to `openclaw agents delete <id>` via `openshell sandbox exec`; the OpenClaw CLI owns gateway dispatch (`agents.delete`), host-side workspace removal, and config edits.
Flags accepted by the in-sandbox CLI (`--force`, `--json`) are forwarded verbatim.

```bash
$$nemoclaw my-assistant agents delete work
$$nemoclaw my-assistant agents delete work --force --json
```

### `$$nemoclaw <name> agents apply`

Reconcile the live sandbox roster against a declarative [agents.yaml manifest](../configure-agents/declarative-agents-manifest).
The verb lists current agents via `openclaw agents list --json`, diffs them against the manifest, and adds missing secondaries or deletes orphan ones through `openclaw agents add|delete`.
Per-agent `model`, `subagents.*`, `tools`, top-level `defaults`, and `main` overrides need a sandbox rebuild and are surfaced as warnings rather than silently dropped; rerun `$$nemoclaw onboard --agents <agents.yaml> --recreate-sandbox` to bake those fields.
When the diff removes orphan agents, NemoClaw invokes OpenClaw's confirmation-skipping delete mode internally.
`--non-interactive` controls the host-side `agents apply` prompt and is not forwarded to OpenClaw's delete command.

```bash
$$nemoclaw my-assistant agents apply -f ./agents.yaml
$$nemoclaw my-assistant agents apply -f ./agents.yaml --yes
$$nemoclaw my-assistant agents apply -f ./agents.yaml --yes --non-interactive
```

Pass `-f` / `--file <agents.yaml>` to point at the manifest; `--yes` confirms the roster diff above; `--non-interactive` fails fast when `--yes` is absent so scripted callers cannot accidentally hang on a missing prompt.

</AgentOnly>

<AgentOnly variant="openclaw">

### `$$nemoclaw <name> sessions`

List OpenClaw conversation sessions in the sandbox.
With no subcommand the in-sandbox CLI lists stored sessions for the configured default agent.
NemoClaw invokes `openclaw sessions` via `openshell sandbox exec` and forwards OpenClaw flags verbatim, but filters default list output so internal `nemoclaw-onboard-warmup-*` sessions created during onboarding are hidden from user-facing output.

```bash
$$nemoclaw my-assistant sessions
$$nemoclaw my-assistant sessions --all-agents --json
```

</AgentOnly>
<AgentOnly variant="hermes">

### `$$nemoclaw <name> sessions`

List Hermes conversation sessions in the sandbox.
NemoClaw invokes `hermes sessions list` via `openshell sandbox exec`, forwards native Hermes flags such as `--source` and `--limit`, and streams the output unchanged.

```bash
$$nemoclaw my-assistant sessions
$$nemoclaw my-assistant sessions --source cli --limit 20
```

</AgentOnly>

<AgentOnly variant="openclaw">

### `$$nemoclaw <name> sessions list`

Invoke `openclaw sessions list` inside the sandbox.
NemoClaw forwards every flag the in-sandbox CLI accepts (`--agent`, `--all-agents`, `--active`, `--limit`, `--json`, `--store`, `--verbose`) and filters the resulting default table or JSON so internal `nemoclaw-onboard-warmup-*` sessions are hidden.

```bash
$$nemoclaw my-assistant sessions list
$$nemoclaw my-assistant sessions list --agent main --json
```

</AgentOnly>
<AgentOnly variant="hermes">

### `$$nemoclaw <name> sessions list`

Invoke `hermes sessions list` inside the sandbox.
NemoClaw forwards native Hermes flags such as `--source` and `--limit` and streams the output unchanged.

```bash
$$nemoclaw my-assistant sessions list
$$nemoclaw my-assistant sessions list --source cli --limit 20
```

### `$$nemoclaw <name> sessions delete <id>`

Invoke `hermes sessions delete <id> --yes` inside the sandbox to remove a session from the Hermes store.
Pass a native Hermes session id from `sessions list` (for example `20260727_130357_cb2b61`).
The OpenClaw-only `--agent`, `--keep-transcript`, `--json`, and `--verbose` flags are not supported on a Hermes sandbox.

```bash
$$nemoclaw my-assistant sessions delete 20260727_130357_cb2b61
```

</AgentOnly>

<AgentOnly variant="openclaw">

### `$$nemoclaw <name> sessions reset <key>`

Archive a session and rebind its key to a fresh `sessionId` by invoking the OpenClaw gateway `sessions.reset` RPC inside the sandbox.
Goes through `openshell sandbox exec` -> `openclaw gateway call sessions.reset`, so the gateway owns archival, lock handling, and lifecycle events; the host never edits `sessions.json` directly.

```bash
$$nemoclaw my-assistant sessions reset main
$$nemoclaw my-assistant sessions reset agent:main:telegram:t-1
$$nemoclaw my-assistant sessions reset telegram:t-1 --agent main --reason new
$$nemoclaw my-assistant sessions reset agent:main:main --json
```

| Flag | Description |
|------|-------------|
| `--agent <id>` | Agent id when `<key>` is an alias rather than the canonical `agent:<id>:<rest>` form. |
| `--reason new\|reset` | `reset` (default) archives the prior transcript; `new` rebinds without preserving the archive trail. |
| `--json` | Print the reset result as JSON. |
| `--verbose` | Print the gateway entry payload after a successful reset. |

The `<key>` argument accepts an alias (e.g. `main`, `telegram:t-1`) or the canonical `agent:<id>:<rest>` form.
Mismatched `--agent` plus canonical-key combinations are refused before the gateway is invoked.

### `$$nemoclaw <name> sessions delete <key>`

Remove a session entry by invoking the OpenClaw gateway `sessions.delete` RPC inside the sandbox.
The gateway refuses to remove the agent's main session.
The transcript on disk is removed by default; pass `--keep-transcript` to retain it.

```bash
$$nemoclaw my-assistant sessions delete telegram:t-1
$$nemoclaw my-assistant sessions delete agent:main:telegram:t-1
$$nemoclaw my-assistant sessions delete telegram:t-1 --agent main --keep-transcript
$$nemoclaw my-assistant sessions delete agent:main:slack:c-9 --json
```

| Flag | Description |
|------|-------------|
| `--agent <id>` | Agent id when `<key>` is an alias rather than the canonical `agent:<id>:<rest>` form. |
| `--keep-transcript` | Retain the session transcript on disk after the entry is removed. |
| `--json` | Print the delete result as JSON. |
| `--verbose` | Print the gateway entry payload after a successful delete. |

</AgentOnly>

<AgentOnly variant="openclaw">

### `$$nemoclaw <name> sessions export [keys...]`

Export an OpenClaw sandbox's session history from the running sandbox to the host.
The command enumerates the session store through `openclaw sessions list --agent <id> --json` and copies only the matching `<sessionId>.jsonl` files, plus optional `<sessionId>.trajectory.jsonl` files.
It never picks up `sessions.json`, stale `.jsonl.lock` files, or other store bookkeeping.
By default it writes a browsable directory of session files (`dir` format); pass `--format tar` for a single `.tgz` bundle suited to sharing or upload.
With no positional keys, the command exports every non-internal session for the agent; if only internal warm-up sessions exist, the command reports that there are no sessions to bundle and writes no artifact.
Internal `nemoclaw-onboard-warmup-*` sessions are excluded from export-all output, but passing an explicit warm-up session key still exports that session for debugging.
Pass one or more keys, as aliases or canonical `agent:<id>:<rest>` keys, to filter.

```bash
$$nemoclaw my-assistant sessions export
$$nemoclaw my-assistant sessions export main --agent main
$$nemoclaw my-assistant sessions export agent:main:telegram:t-1 --include-trajectory
$$nemoclaw my-assistant sessions export --format tar --out ./bundles/alpha.tgz --json
```

| Flag | Description |
|------|-------------|
| `--agent <id>` | Agent id when `<keys>` are aliases rather than the canonical `agent:<id>:<rest>` form. |
| `--format <dir\|tar>` | `dir` (default) writes a directory of session files; `tar` writes a single `.tgz` bundle for sharing/upload. |
| `--out <path>` | Host destination. Defaults to `./sessions-<sandbox>/` for `dir` or `./sessions-<sandbox>-<agent>.tgz` for `tar`. |
| `--include-trajectory` | Include the large `*.trajectory.jsonl` files in the export. Excluded by default. |
| `--json` | Print the export manifest as JSON instead of a status line. |

Mismatched `--agent` plus canonical-key combinations are refused before any download runs.
Session keys that begin with `-` are rejected at the command boundary instead of being silently dropped.
Session JSONL can contain pasted secrets, such as API keys or tokens, so exported files are written owner-only (`0600`).
The in-sandbox staging artefact is additionally created with `umask 077` and removed after the host download completes.

</AgentOnly>
<AgentOnly variant="hermes">

### `$$nemoclaw <name> sessions export`

Export a Hermes sandbox's session history from the running sandbox to the host.
The command invokes the in-sandbox `hermes sessions export` against a staging path under `/sandbox/.nemoclaw-staging`, then downloads the resulting single JSONL stream to the host.
Hermes stores session history in a SQLite database, so the command refuses positional keys, `--format tar`, and `--include-trajectory` with a clear error when the sandbox is Hermes.
`--agent` accepts only `hermes` as a no-op alias on a Hermes sandbox and rejects any other value.
The host destination defaults to `./sessions-<sandbox>.jsonl`; `--out` picks a different path.

```bash
$$nemoclaw my-assistant sessions export
$$nemoclaw my-assistant sessions export --agent hermes --out ./sessions-my-assistant.jsonl
$$nemoclaw my-assistant sessions export --json
```

| Flag | Description |
|------|-------------|
| `--agent hermes` | Optional no-op alias accepted only on a Hermes sandbox. Any other value is rejected. |
| `--out <path>` | Host destination. Defaults to `./sessions-<sandbox>.jsonl`. |
| `--json` | Print the export manifest as JSON instead of a status line. |

Session JSONL can contain pasted secrets, such as API keys or tokens, so exported files are written owner-only (`0600`).
The in-sandbox staging artefact is additionally created with `umask 077` and removed after the host download completes.

</AgentOnly>

### `$$nemoclaw <name> download <sandbox-path> [host-dest]`

Host-side wrapper around `openshell sandbox download` that checks the live sandbox.
The command confirms before and after transfer that the source remains a file or directory.
Symbolic links, source-type changes, and other special source types are refused.
If the command cannot confirm the source type, it exits without publishing.
The command downloads to a fresh private temporary directory on the host, verifies that OpenShell wrote an artifact, publishes the artifact to your destination, and removes the temporary directory.
An existing destination directory is resolved to its canonical path before publication.
The command refuses an existing file destination that is a symbolic link and a new destination below a symbolic-link parent.
Regular files are published through a private temporary entry and atomically replace an existing regular file.
Relative host destinations resolve against the caller's working directory.
Absolute host destinations do not use caller-working-directory resolution.
With no `host-dest` the destination defaults to the current directory.

<AgentOnly variant="openclaw">

```bash
$$nemoclaw my-assistant download /sandbox/.openclaw/workspace/SOUL.md ./
$$nemoclaw my-assistant download /sandbox/.openclaw/agents/main/sessions/ ./sessions/
```

</AgentOnly>
<AgentOnly variant="hermes">

```bash
$$nemoclaw my-assistant download /sandbox/.hermes/state.db ./
$$nemoclaw my-assistant download /sandbox/.hermes/logs/ ./logs/
```

</AgentOnly>
<AgentOnly variant="deepagents">

```bash
$$nemoclaw my-assistant download /sandbox/.deepagents/agent/skills/ ./agent-skills/
$$nemoclaw my-assistant download /sandbox/.deepagents/.state/ ./deepagents-state/
```

</AgentOnly>

### `$$nemoclaw <name> upload <host-path> [sandbox-dest]`

Host-side wrapper around `openshell sandbox upload`, symmetric to the download wrapper.
With no `sandbox-dest` the destination defaults to `/sandbox/` inside the sandbox.

<AgentOnly variant="openclaw">

```bash
$$nemoclaw my-assistant upload ./local-file /sandbox/
$$nemoclaw my-assistant upload ./backups/SOUL.md /sandbox/.openclaw/workspace/SOUL.md
```

</AgentOnly>
<AgentOnly variant="hermes">

```bash
$$nemoclaw my-assistant upload ./local-file /sandbox/
$$nemoclaw my-assistant upload ./backups/state.db /sandbox/.hermes/state.db
```

</AgentOnly>
<AgentOnly variant="deepagents">

```bash
$$nemoclaw my-assistant upload ./local-file /sandbox/
$$nemoclaw my-assistant upload ./agent-skills/ /sandbox/.deepagents/agent/skills/
```

</AgentOnly>

### `$$nemoclaw <name> rebuild`

Upgrade a sandbox to the current agent version while preserving workspace state.
The command backs up workspace state, destroys the old sandbox (including its host-side Docker image), recreates it with the current image via `onboard --resume`, and restores workspace state into the new sandbox.
Credentials are stripped from backups before storage.
Policy presets applied to the old sandbox are reapplied to the new one so your egress rules survive the rebuild.
Before creating the replacement sandbox, NemoClaw prints the finalized create-time policy scope whenever presets are included.
The replacement uses the recorded compatible-endpoint reasoning mode, reasoning effort, and web search selection instead of ambient shell values.
When same-gateway legacy sandbox records use the selected supported provider but omit its credential environment-variable name, rebuild fills only those missing names from the provider's canonical configuration.
The target update and peer metadata migration use one registry update.
Conflicting credential environment-variable names, custom endpoints, or API families still stop the rebuild.
Incomplete routes and invalid gateway bindings also stop the rebuild.
NemoClaw checks the shared route again immediately before deleting the original sandbox.
Rebuild preserves the recorded sandbox GPU enablement mode and, for an explicitly enabled sandbox, its recorded device selector.
It re-resolves the Docker-driver GPU route from the current host and current `NEMOCLAW_DOCKER_GPU_PATCH` value, so native-only, explicitly authorized native-with-fallback, and compatibility-only routing may differ from the original onboarding run.
A rebuild preserves the recorded tool-disclosure mode unless `--tool-disclosure` explicitly changes it; it ignores an ambient `NEMOCLAW_TOOL_DISCLOSURE` value while recreating the sandbox.
A rebuild preserves the recorded Deep Agents Code observability choice and matching local OTLP policy state unless `--observability` or `--no-observability` explicitly changes them.
A rebuild preserves the recorded Deep Agents Code auto-approval capability unless `--dcode-auto-approval` explicitly changes it.
A sandbox onboarded with an explicit GPU opt-out (stored as `sandboxGpuMode: "0"`, plus legacy registry entries that only record `gpuEnabled: false`) is recreated with the same opt-out, so the inner `onboard --resume` skips the Docker CDI GPU preflight on hosts without an NVIDIA GPU.
Auto-mode sandboxes remain auto.

```bash
$$nemoclaw my-assistant rebuild [--yes|-y|--force] [--verbose|-v] [--tool-disclosure <progressive|direct>] [--dcode-auto-approval <disabled|thread-opt-in>] [--observability|--no-observability]
```

| Flag | Description |
|------|-------------|
| `--yes`, `-y` | Skip the confirmation prompt. |
| `--force` | Skip the confirmation prompt and continue when no state directory was preserved or a manifest-declared state file failed. NemoClaw restores any captured entries; after a total failure, it recreates from registry metadata only. If a pre-mutation no-op cannot execute in a sandbox with managed MCP servers, it may preserve the exact registered MCP intent through host-side recovery. |
| `--verbose`, `-v` | Log SSH commands, exit codes, and session state (also enabled by `NEMOCLAW_REBUILD_VERBOSE=1`) |
| `--tool-disclosure <progressive\|direct>` | Change the model-visible tool catalog during this transactional rebuild. Use this path for sandboxes with managed MCP servers so their providers and adapter state are preserved. |
| `--dcode-auto-approval <disabled\|thread-opt-in>` | Change the managed Deep Agents Code thread auto-approval capability. `thread-opt-in` is accepted only for managed Deep Agents Code sandboxes and is rejected for other agents or custom images. Enabling prints a warning, and either value requires sandbox recreation. |
| `--observability`, `--no-observability` | Enable or disable managed trace export for a LangChain Deep Agents Code sandbox during the transactional rebuild. This path preserves managed MCP providers and adapter state. |

If another terminal has an active SSH session to the sandbox, `rebuild` prints an active-session warning and requires confirmation before destroying the sandbox.
Pass `--yes`, `-y`, or `--force` to skip the prompt in scripted workflows.

The sandbox normally must be reachable for the backup step to succeed.
If an archive command preserves at least one state directory, `rebuild` keeps the captured backup entries and reports the manifest-defined paths that could not be archived.
If a manifest-declared state file fails, `rebuild` exits before destroying the original sandbox even when it preserved state directories, unless you explicitly pass `--force`.
If every state directory fails, `rebuild` exits before destroying the original sandbox even when it captured loose files, unless you explicitly pass `--force`.
With `--force`, NemoClaw preserves any captured loose files in the partial manifest and restores them after recreation.
If the backup produced nothing usable, it continues from recorded registry metadata without restoring prior sandbox state.
Use this recovery path only when losing the state that could not be backed up is acceptable.
For a sandbox with managed MCP servers, `--force` probes sandbox execution before MCP teardown.
If that no-op cannot run, NemoClaw requires complete bridge entries and exact live policy and provider identities, without trying an in-sandbox adapter scrub or changing MCP ownership state.
Each bridge must record the adapter for the sandbox's recorded agent.
The registered policy must match the policy NemoClaw generates for that adapter, server name, endpoint URL, and resolved addresses.
It rechecks the registry, recorded gateway, resolved targets, live generated policies, and provider identities immediately before deletion; incomplete adds, drift, or ambiguous ownership stop before deletion.
NemoClaw sends the delete request and every deletion-confirmation lookup to the sandbox's exact recorded gateway.
Across every rebuild path, NemoClaw does not attempt to stop local NIM until sandbox deletion is positively confirmed, then attempts NIM cleanup on a best-effort basis.
When `openshell sandbox delete` exits nonzero, an exact recorded-gateway lookup distinguishes explicit absence from a confirmed `Ready` or `Running` sandbox.
Any other phase or probe failure is ambiguous.
Explicit absence continues the rebuild.
Confirmed intact state triggers an attempt to restore prepared MCP state and any shields lockdown that rebuild temporarily opened.
NemoClaw reports any MCP or shields restoration failure and does not present the operation as a successful rollback.
Ambiguous state preserves MCP ownership and recovery metadata without attempting to stop NIM or claiming the original sandbox remains intact, and the rebuild process skips its immediate shields relock.
Failures after a successful exec probe do not switch to the host-side path.
Before backup or deletion, `rebuild` also refuses an incomplete MCP destroy transaction.
It also refuses a pending baseline exclusion transaction before opening a shields-down window, starting backup, or deleting the sandbox, and prints the exact `policy exclude` or `policy restore` command to rerun.
For a prepared-only transaction, the redacted diagnostic points to `$$nemoclaw <name> mcp remove <server> --force` when the sandbox is still live.
For a pending or both-marker transaction, it points to `$$nemoclaw <name> destroy` because the registry records that OpenShell deletion was already confirmed.
Before backup or deletion, rebuild checks the staged messaging configuration against other sandboxes in the selected OpenShell gateway's sandbox registry.
A rebuild cannot detect messaging conflicts in an independent OpenShell gateway's registry.
A conflict aborts with the original sandbox registered and intact so you can resolve the conflict before retrying.
After OpenShell accepts the sandbox deletion, `rebuild` waits until OpenShell explicitly reports that the old sandbox is absent.
Only then can NemoClaw perform any required local registry removal and begin creating the replacement.
If OpenShell does not confirm absence within the bounded wait, including when gateway transport errors block the probes, `rebuild` exits nonzero before registry removal or replacement creation and preserves both the local registry entry and the state backup.
Restore OpenShell connectivity and confirm the sandbox's live state before you retry, and keep the printed backup path for recovery.
Before deletion, rebuild records a replacement journal that binds the operation to the recorded gateway, source identity, and target settings.
Rerunning the same rebuild continues from the recorded boundary or accepts the proven replacement instead of deleting it again.
Use `--verbose` to print the replacement identifier, gateway, and journal phase.
Refer to [Continue an Interrupted Replacement](../manage-sandboxes/operate-sandboxes/recover-and-rebuild-sandboxes#continue-an-interrupted-replacement) for the recovery procedure and fail-closed conditions.
When rebuild starts with shields up, NemoClaw opens a 30-minute shields-down window for backup and recreation.
A detached auto-lock timer remains active until NemoClaw commits a successful shields-up state, so it can attempt to restore lockdown if the host rebuild process exits unexpectedly.

<AgentOnly variant="openclaw">

After restore, the command runs `openclaw doctor --fix` for cross-version structure repair.

</AgentOnly>
<AgentOnly variant="hermes">

After restore, the command restores Hermes manifest-defined state and starts the rebuilt Hermes gateway with the regenerated `/sandbox/.hermes` config.
A rebuild creates a new sandbox home and a new Hermes API bearer token.
After the rebuild succeeds, retrieve the replacement token with `nemohermes my-assistant gateway-token --quiet` before reconnecting API clients.
For an older Hermes image that predates sealed shields transitions, rebuild is the only workflow authorized to use the descriptor-safe compatibility transition.
The compatibility path verifies the strict root-owned hash and the in-tree hash, publishes fresh config inodes to revoke retained write descriptors, and restores the trusted lock posture if the transition cannot finish.
Ordinary `shields up` and `shields down` commands refuse the older protocol and direct you to rebuild.

</AgentOnly>
<AgentOnly variant="deepagents">

After restore, the command restores Deep Agents manifest-defined state, regenerates `/sandbox/.deepagents/config.toml`, and recreates the managed MCP projection from the host registry.
Before changing the sandbox, rebuild verifies that the recorded `inference.local` route is still reachable and that the target provider, model, reasoning settings, web search selection, base image, and policy inputs match the recorded context.
If those checks fail after backup, NemoClaw restores the previous MCP state and keeps the existing sandbox intact.
Use rebuild after a failed Deep Agents version check, after enabling Tavily Search, or after upgrading from an older managed MCP runtime.

</AgentOnly>

### `$$nemoclaw update`

Check for a NemoClaw CLI update and, when requested, run the maintained installer flow.
This command is a discoverable CLI wrapper around the supported installer path:

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

```bash
$$nemoclaw update [--check] [--fresh] [--allow-downgrade] [--yes|-y]
```

| Flag | Description |
|------|-------------|
| `--check` | Show the current version, latest maintained version, install type, and maintained update command without changing anything. |
| `--fresh` | Reinstall the maintained build for a clean re-clone of `~/.nemoclaw/source`; useful to repair a broken install. Does not reset onboarding state. By default, runs only when the maintained build is the same version or newer than the installed version. |
| `--allow-downgrade` | Allow `--fresh` to reinstall when the maintained build is older than the installed version or the versions cannot be ordered. This can downgrade the host installation. |
| `--yes`, `-y` | Skip the confirmation prompt and run the maintained installer flow. |

`$$nemoclaw update` updates the host-side NemoClaw installation.
The maintained installer flow follows the admin-promoted `lkg` release tag by default, so it may trail the newest semver or `latest` tag while validation completes.
Because of that, an install can be newer than the maintained tag.
Without `--allow-downgrade`, `--fresh` runs only when the maintained build is the same version or newer than the installed version.
When the maintained tag resolves, the command passes that repository revision to the installer, so a later tag change cannot select a different build for that update.
It reports the reason and exits non-zero in these cases:

- The installed version is newer than the maintained tag.
- The versions cannot be ordered.
- The maintained tag does not resolve to a version.

NemoClaw cannot order a `git describe` version against a different prerelease on the same release line.
Rerun with `--allow-downgrade` to reinstall regardless; `--yes` waives the confirmation prompt only and never accepts a downgrade on its own.
It does not replace `$$nemoclaw upgrade-sandboxes`; use that command to inspect or rebuild existing sandboxes after the CLI has been updated.
When the command is running from a source checkout, it reports that state and does not replace the checkout with a global package install.

### `$$nemoclaw upgrade-sandboxes`

Rebuild sandboxes whose base image is older than the one currently pinned by NemoClaw.
NemoClaw resolves the digest of `ghcr.io/nvidia/nemoclaw/sandbox-base:latest` from the registry, then compares it against the digest each sandbox was created with.
Sandboxes that match the current digest are left alone.
NemoClaw also checks the build fingerprint recorded on each managed sandbox image.
A sandbox needs upgrade when its agent version is stale, when its recorded NemoClaw image fingerprint differs from the running CLI, or both.
When the target version is older than the recorded one (for example after reinstalling with an older `NEMOCLAW_INSTALL_TAG`), the stale listing marks the change with a `(downgrade)` suffix instead of framing it as a routine upgrade.
Custom Dockerfile sandboxes are not classified by image drift because rebuilding them onto the default image would drop the custom image.
Legacy sandboxes without a recorded fingerprint opt into this check after their next rebuild.
A recorded sandbox that is not observed in any phase on its own recorded gateway is reported as not found there, with remediation guidance — this typically means its gateway registration or Docker image was removed (for example by `$$nemoclaw uninstall`, which preserves `sandboxes.json` but removes both).

```bash
$$nemoclaw upgrade-sandboxes [--check] [--auto] [--yes|-y]
```

| Flag | Description |
|------|-------------|
| `--check` | List stale sandboxes without rebuilding any of them. Exits non-zero if any are stale. |
| `--auto` | Rebuild every stale sandbox without prompting. Used by the installer to upgrade in place. |
| `--yes`, `-y` | Skip the confirmation prompt for the rebuild plan. |

Before it inspects a gateway or starts a rebuild, the command validates every registered sandbox name against the NemoClaw sandbox name format.
Route-only reservations are not sandboxes and are excluded from this validation.
If the command finds incompatible names, it lists each name before any gateway inspection or rebuild.
With `--check`, the command then returns without changing state.
In a mutating mode, it exits with a nonzero status.
NemoClaw does not truncate or rename a registered sandbox identity.
Follow [Update Sandboxes](../manage-sandboxes/operate-sandboxes/update-sandboxes) to transfer state to a compatible replacement before you rerun the command.

Each rebuild reuses the same workspace backup-and-restore flow as `$$nemoclaw <name> rebuild`, so workspace files survive the upgrade.
If the registry is unreachable (offline or firewalled hosts), NemoClaw falls back to the unpinned `:latest` tag and reports that the digest could not be resolved instead of failing.
During installer recovery, a registered sandbox that is not Ready can also be rebuilt from its validated latest backup.
That recovery requires a NemoClaw-managed image fingerprint or the installer's explicit confirmation for a listed pre-fingerprint OpenClaw or Hermes entry.
The legacy confirmation never overrides recorded custom-image evidence.
A custom OpenClaw sandbox is recoverable only when the selected backup independently carries complete authoritative image-plugin provenance.

### `$$nemoclaw backup-all`

Back up registered sandboxes that are running or have an eligible stopped Docker-driver container to `~/.nemoclaw/rebuild-backups/`.
A registered docker-driver sandbox whose container is stopped is started for the duration of the backup and returned to its stopped state afterward.
If the container cannot be returned to the stopped state, the command fails and reports that the container was left running.
Sandboxes that are not running and cannot be started this way are skipped with remediation guidance.

For each eligible sandbox, `backup-all` holds one lifecycle transaction through the complete backup.
Within that transaction, it starts a stopped container when required, opens a 30-minute shields-down window when the sandbox starts with Shields up, copies sandbox state, restores the previous Shields state, and returns any container it started to the stopped state.
If the timer expires during the transaction, the deadline gate blocks new mutations and waits for the exact backup owner to finish without signaling it.
An initial lock or unlock failure marks that sandbox as failed, and `backup-all` continues with the next sandbox.
A failure to restore the previous Shields state stops `backup-all` before it processes another sandbox.

```bash
$$nemoclaw backup-all
```

Before an OpenShell upgrade, the installer prepares the current release CLI and uses it to run `backup-all` in strict mode.
Strict mode requires every registered sandbox to produce a fresh backup and aborts before gateway changes if any sandbox is skipped or fails.
When strict mode reports a skipped sandbox, start that sandbox or its container and rerun the installer or `$$nemoclaw backup-all`.

A running sandbox whose in-sandbox SSH endpoint does not answer fails its backup and aborts the run.
For a standalone `$$nemoclaw backup-all` run, set `NEMOCLAW_SKIP_UNREACHABLE_SANDBOX_BACKUP=1` exactly to skip such sandboxes instead of failing.
Other values such as `true`, `yes`, or `0` are not accepted.
This variable does not weaken the installer's strict pre-upgrade requirement.
A skipped sandbox's uncommitted state is not included in its last successful backup.

### `$$nemoclaw <name> snapshot create`

Create a timestamped snapshot of sandbox state.
Snapshots are stored in `~/.nemoclaw/rebuild-backups/<name>/`.
The command requires shields to be down and keeps the shields check and backup under one per-sandbox transition.
If the timer expires during a long-running backup, the deadline gate blocks new mutations and waits for the exact backup owner to finish.
Auto-restore does not signal the backup process.
If ownership becomes ambiguous, NemoClaw attempts to record durable containment and reports exact-generation recovery guidance.
If the containment commit fails, NemoClaw retains any exact lifecycle and deadline gates it already owns.
A state-directory failure that prevented gate publication also prevents normal mutation-lock acquisition.
Correct the reported state-directory write failure, then run `$$nemoclaw <name> shields status` to resume recovery or receive exact-generation recovery guidance.
When the sandbox has active baseline exclusions, successful output lists their keys and repeats that excluded egress leaves dependent agent features unsupported for that sandbox.

```bash
$$nemoclaw my-assistant snapshot create
```

| Flag | Description |
|------|-------------|
| `--name <label>` | Attach a human-readable label to the snapshot so you can restore by name later |

Names must be 1 to 63 characters from `[A-Za-z0-9._-]`, start with an alphanumeric character, and cannot look like a version selector (`v1`, `v2`, ...). Duplicate names per sandbox are rejected; pick a different name or delete the existing snapshot first.

```bash
$$nemoclaw my-assistant snapshot create --name before-upgrade
```

When a directory or state file cannot be captured, the command reports the failed items, removes the incomplete snapshot, and exits nonzero.
A removed snapshot does not appear in `snapshot list` and cannot be restored, so a later restore cannot select a capture that never completed.
When removal fails, the command reports the listed snapshot path and exits nonzero.
Remove that directory manually before you run `snapshot restore` because the incomplete capture remains selectable.

### `$$nemoclaw <name> snapshot list`

List available snapshots for a sandbox as a table of version, name, timestamp, and path.
Versions (`v1`, `v2`, ...) are computed on read from timestamp-ascending order, so `v1` is the oldest snapshot and `vN` is the newest. Snapshots created before this feature landed are numbered retroactively.

```bash
$$nemoclaw my-assistant snapshot list
```

### `$$nemoclaw <name> snapshot restore [selector] [--to <dst>] [--force] [--yes|-y]`

Restore sandbox state from a snapshot.
For an in-place restore, the sandbox must be running.
If no selector is provided, the latest snapshot is used.
Restore removes files added after the snapshot only from state directories selected for cleanup.
It preserves directories that exist only in the target manifest or whose backup failed.
The state replacement, mutable-config permission repair, and policy reconciliation run under the same per-sandbox transition.
If the timer expires during that work, the deadline gate blocks new mutations and waits for the exact restore owner to finish.
Auto-restore does not signal the restore process.
If ownership becomes ambiguous, NemoClaw attempts to record durable containment and reports exact-generation recovery guidance.
If the containment commit fails, NemoClaw retains any exact lifecycle and deadline gates it already owns.
A state-directory failure that prevented gate publication also prevents normal mutation-lock acquisition.
Correct the reported state-directory write failure, then run `$$nemoclaw <name> shields status` to resume recovery or receive exact-generation recovery guidance.

<Warning>
Post-restore policy reconciliation is best-effort.
NemoClaw warns and continues the remaining restore steps in these cases:

- NemoClaw cannot verify whether a custom policy owns the live `observability-otlp-local` policy entry.
- The built-in `observability-otlp-local` policy preset has drifted or cannot be inspected.
- NemoClaw cannot add or remove a recorded policy preset.

The live network policy can then retain unwanted egress or omit expected egress until you repair the named preset.
After a warning, run `$$nemoclaw <name> policy list`.
Confirm that the named preset is recorded in the sandbox registry and active on the gateway, or absent from both.
</Warning>

The selector accepts any of:

- A version (`v1`, `v2`, ..., `vN`) from `snapshot list`.
- An exact name passed to `snapshot create --name`.
- An exact timestamp.

Pass `--to <dst>` to restore the snapshot into a different sandbox instead of the source.
When `dst` does not exist, it is auto-created from the source image.
For a Docker- or VM-driver source, the source can be stopped when its registry entry records both the sandbox image and a complete inference route.
For a Kubernetes-driver source, the pod image must remain resolvable through its gateway.
No re-onboarding is needed when those prerequisites are present.
For a new destination, NemoClaw requires its owning gateway to report Ready state and a valid live identity.
It revalidates that identity immediately before registration.
The destination receives a new lifecycle generation and does not inherit the source sandbox's generation.
If the destination is not Ready with the same valid identity, the command exits nonzero before registration or state restore.
The created destination remains unregistered, so `--force` cannot select it for deletion.
Run the exact owner-scoped deletion command printed by the failure:

```bash
openshell sandbox delete -g '<owning-gateway>' '<destination>'
```

After OpenShell deletes the destination, rerun the original `snapshot restore --to` command.
<AgentOnly variant="openclaw">
After NemoClaw creates the destination, it waits for the managed OpenClaw supervisor to pass a bounded readiness check before it applies snapshot state.
If the check fails, the command leaves the destination registered without restored snapshot state and exits nonzero.
Correct the reported supervisor failure, then run `$$nemoclaw <destination> destroy` or rerun the restore with `--force`.
</AgentOnly>
A cross-sandbox restore refuses to clone a source or replace an existing destination whose baseline exclusion transaction needs repair, before it creates or deletes anything.
When `dst` already exists, `snapshot restore --to <dst>` refuses by default to avoid silently mutating the destination's filesystem.
To overwrite an existing destination, pass `--force`: the command deletes `dst`, then recreates it from the source's image and restores the snapshot into the fresh copy.
If the existing destination has an active shields timer, the force path restores and verifies lockdown, revokes the timer, and then deletes the destination.
It clears the remaining local shields state only after deletion succeeds.
The `--force` path prompts interactively to confirm the destination name before deleting.
Pass `--yes` (or set `NEMOCLAW_NON_INTERACTIVE=1`) to skip the prompt.
The snapshot selector, source image, and durable inference route are validated before any deletion. If any prerequisite is invalid, restore stops before it deletes `dst`.

```bash
# restore latest snapshot in-place
$$nemoclaw my-assistant snapshot restore

# restore by version
$$nemoclaw my-assistant snapshot restore v3

# restore by user-assigned name
$$nemoclaw my-assistant snapshot restore before-upgrade

# restore by exact timestamp
$$nemoclaw my-assistant snapshot restore 2026-04-21T07-35-55-987Z

# clone v3 into a new sandbox
$$nemoclaw my-assistant snapshot restore v3 --to my-assistant-clone

# overwrite an existing destination with v3, non-interactively
$$nemoclaw my-assistant snapshot restore v3 --to my-assistant-clone --force --yes
```

When `--to` names an existing sandbox, restore refuses to overwrite it unless you pass `--force`.
With `--force`, NemoClaw confirms the destructive restore unless you also pass `--yes` or run with `NEMOCLAW_NON_INTERACTIVE=1`.
Use this path only when the destination sandbox can be replaced by the selected snapshot.

### `$$nemoclaw <name> share mount`

Mount the sandbox filesystem on the host machine via SSHFS for bidirectional file sharing.
Files edited on the host appear instantly inside the sandbox, and vice versa.

```bash
$$nemoclaw my-assistant share mount
```

Expected output:

```text
✓ Mounted /sandbox → ~/.nemoclaw/mounts/my-assistant
```

| Argument | Default | Description |
|----------|---------|-------------|
| `sandbox-path` | `/sandbox` | Remote path inside the sandbox to mount |
| `local-mount-point` | `~/.nemoclaw/mounts/<name>` | Local directory to mount onto (auto-created) |

Prerequisites:

- `sshfs` must be installed on the host (`sudo apt-get install sshfs` on Linux, `brew install macfuse && brew install sshfs` on macOS).
- The sandbox must be running.
- The remote sandbox path must exist. NemoClaw verifies it against the target sandbox before invoking `sshfs` and prints a `connect`, then `ls <path>` check when the probe fails.
- Sandboxes created before the `openssh-sftp-server` base image update must be rebuilt with `$$nemoclaw <name> rebuild`.
- The local mount path must be on a writable filesystem; FUSE creates the mount on the host side.
  If the default `~/.nemoclaw/mounts/<name>` lives on a read-only filesystem, pass an explicit writable path as the second positional argument.

```bash
# mount a specific path to a custom local directory
$$nemoclaw my-assistant share mount /sandbox/workspace ~/my-workspace
```

### `$$nemoclaw <name> share unmount`

Unmount a previously mounted sandbox filesystem.

```bash
$$nemoclaw my-assistant share unmount
```

| Argument | Default | Description |
|----------|---------|-------------|
| `local-mount-point` | `~/.nemoclaw/mounts/<name>` | Local directory to unmount |

### `$$nemoclaw <name> share status`

Check whether the sandbox filesystem is currently mounted.

```bash
$$nemoclaw my-assistant share status
```

Expected output:

```text
● Mounted at ~/.nemoclaw/mounts/my-assistant
```

| Argument | Default | Description |
|----------|---------|-------------|
| `local-mount-point` | `~/.nemoclaw/mounts/<name>` | Local directory to check |

## `openshell term`

Open the OpenShell TUI to monitor sandbox activity and approve network egress requests.
Run this on the host where the sandbox is running.

```bash
openshell term
```

For a remote server, connect through SSH and run `openshell term` on that server.

<AgentOnly variant="openclaw,hermes">

### `$$nemoclaw tunnel start`

Start optional host auxiliary services.
This is the cloudflared tunnel when `cloudflared` is installed, which exposes the dashboard with a public URL.
Channel messaging (Telegram, Discord, Slack) is not started here; it is configured during `$$nemoclaw onboard` and runs through OpenShell-managed constructs.

```bash
$$nemoclaw tunnel start
```

By default, NemoClaw starts a Cloudflare quick tunnel and prints the generated `*.trycloudflare.com` URL when `cloudflared` reports it.
Set `CLOUDFLARE_TUNNEL_TOKEN` to start a Cloudflare named tunnel instead.
The named tunnel hostname and `localhost:<dashboard-port>` route must already be configured in the Cloudflare dashboard.
NemoClaw passes the token to `cloudflared` through the `TUNNEL_TOKEN` environment variable, so the token does not appear in the `cloudflared` command-line arguments.

```bash
export CLOUDFLARE_TUNNEL_TOKEN=<cloudflare-tunnel-token>
$$nemoclaw tunnel start
```

`$$nemoclaw start` remains as a deprecated alias that prints a warning and delegates to `tunnel start`.

### `$$nemoclaw tunnel stop`

Stop host auxiliary services that `$$nemoclaw tunnel start` started (for example cloudflared).

Use `$$nemoclaw <name> channels stop <channel>` when you only want to pause one messaging bridge.

```bash
$$nemoclaw tunnel stop
```

The command asks NemoClaw to stop an in-sandbox gateway only when NemoClaw directly owns that process.
Supervisor-owned agent runtime processes remain managed inside their sandbox.
The command leaves agent-owned host forwards and the managed OpenShell gateway port available.

`$$nemoclaw stop` remains as a deprecated legacy full stop.
In addition to stopping tunnel services, it attempts to stop the selected agent's host forwards when the sandbox uses a manifest-resolved non-OpenClaw agent.
It also attempts to safely release an unshared OpenShell gateway port whose ownership NemoClaw can verify.
Shared gateways remain running, and ambiguous ownership fails closed without releasing the port.
Use `$$nemoclaw tunnel stop` when the shared gateway should remain available.

### `$$nemoclaw tunnel status`

Show the current cloudflared public-URL tunnel status for the selected or default sandbox dashboard.
The output reports whether cloudflared is running, stopped, or stale, and includes the same recovery hint used by `$$nemoclaw status`.
Selection honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default.

```bash
$$nemoclaw tunnel status
```

### `$$nemoclaw start`

<Warning>
Deprecated. Use `$$nemoclaw tunnel start` instead.
</Warning>

This command remains as a compatibility alias to `$$nemoclaw tunnel start`.

### `$$nemoclaw stop`

<Warning>
Deprecated legacy full stop.
Use `$$nemoclaw tunnel stop` when the shared gateway should remain available.
</Warning>

This command stops tunnel services and, for a manifest-resolved non-OpenClaw agent, attempts to stop the selected agent's host forwards.
It attempts to release the managed OpenShell gateway port only when the gateway is unshared and ownership is safely resolved; otherwise it preserves the gateway.
When no sandbox name resolves, gateway release requires a valid, explicitly set `NEMOCLAW_GATEWAY_PORT`; a bare command leaves the process-wide default gateway running and reports `Host services stopped; managed gateway not released.`
If NemoClaw attempts the release but cannot confirm it, the command reports that outcome and does not claim that all services stopped.
For manifest-resolved non-OpenClaw agents, it also requests cleanup of host-forwarding resources that `$$nemoclaw tunnel stop` leaves running.
The command is retained for compatibility with full-stop automation.
Supervisor-owned agent runtime processes remain managed inside their sandbox.

</AgentOnly>

### `$$nemoclaw status`

Show the global sandbox list and the status of host auxiliary services (for example cloudflared).
This command is host-wide. It summarizes registered sandboxes, the default sandbox's live inference route, gateway health, and host services.
<AgentOnly variant="openclaw,hermes">
For gateway-based messaging agents, it also reports messaging overlap warnings within the selected OpenShell gateway's sandbox registry.
</AgentOnly>
Use `$$nemoclaw <name> status` when you need one sandbox's live health and recovery guidance.
Pass `--json` for machine-readable output with registered sandboxes, service state, inference routes, and health details.
Each JSON sandbox row reports `agent` as a string, never `null`.
The row reports `openclaw` when the registry records no agent for the sandbox.
This command reads the registry without gateway recovery, so it never reports `unknown`.
For each listed sandbox, the text output includes the configured inference provider and model plus the number of active SSH sessions when the session probe is available.
Host-service PID lookup honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default.

```bash
$$nemoclaw status
$$nemoclaw status --json
```

When at least one sandbox is registered and the named NemoClaw gateway is unreachable, unhealthy, or attached to a different sandbox, the command prints a `gateway: down [state] (reason)` line between the sandbox list and the host-service list.
The command classifies the failing layer when possible: the named gateway port is not accepting connections, the named gateway is running but not Connected, the active OpenShell gateway points at a different name, or the named gateway is not configured at all.
It then prints the gateway recovery guidance for your host.
That guidance names `$$nemoclaw onboard` when NemoClaw starts the gateway process.
When another deployment owns that process, the guidance directs you to start it with the owning deployment and run `openshell gateway select <gateway>`.
It exits with code `1` so shell scripts and CI can detect the degraded state from `$?`.
For `--json`, the structured output includes `gatewayHealth`, and the exit code is set after the report is generated.
A clean machine with no registered sandboxes keeps the legacy `0` exit because no gateway is expected to be configured yet.
If cloudflared is installed but not running, the host-service section reports whether the PID file is missing, invalid, or points at a dead process, then suggests `$$nemoclaw tunnel start` as the recovery command.

### `$$nemoclaw inference get`

Show the active live inference provider and model from the NemoClaw-managed OpenShell gateway.
Use this command when you want the direct runtime route without the rest of the sandbox status output.
It is also available in sandbox-first form as `$$nemoclaw <name> inference get`.

```bash
$$nemoclaw inference get
$$nemoclaw inference get --json
```

The sandbox-first grammar `$$nemoclaw <name> inference get` is also accepted and reads the same gateway-wide route, so it stays symmetric with `$$nemoclaw <name> inference set`.

```bash
$$nemoclaw my-assistant inference get
```

### `$$nemoclaw inference set`

<AgentOnly variant="openclaw">

Switch the active inference provider or model for a NemoClaw-managed OpenClaw sandbox.
The command updates the OpenShell gateway route, patches the selected running agent config so it matches the route, recomputes the config hash, and updates the NemoClaw registry.
It is also available in sandbox-first form as `$$nemoclaw <name> inference set --provider <provider> --model <model>`.
For OpenClaw, the patch updates the OpenClaw config provider namespace and selected model.
Same-API-family changes hot-reload without replacing the gateway process.
When the API family changes, NemoClaw commits the config and integrity hash, then uses the managed supervisor to restart only the OpenClaw gateway and verify its health and forwards.
The sandbox remains running, but agent requests are briefly interrupted.
If the restart fails, the route and config remain committed; run `$$nemoclaw <name> gateway restart` to finish applying the switch.

</AgentOnly>
<AgentOnly variant="hermes">

Switch the active inference provider or model for a NemoClaw-managed Hermes sandbox.
The command updates the OpenShell gateway route, patches the selected running agent config so it matches the route, recomputes the config hash, and updates the NemoClaw registry.
It is also available in sandbox-first form as `$$nemoclaw <name> inference set --provider <provider> --model <model>`.
For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) and does not rebuild or restart the gateway.
When the Hermes dashboard profile exists, the command also mirrors the model route into `/sandbox/.hermes/profiles/dashboard-home/config.yaml` for Dashboard Chat.
Keeping the placeholder preserves dashboard and API authentication after provider switches.
If NemoClaw cannot confirm that the dashboard config was updated, the route, registry, and main Hermes config remain committed, but the command exits nonzero without printing `Inference route synced`.
Restart the sandbox with `nemohermes <name> stop` followed by `nemohermes <name> start`, then verify Dashboard Chat before relying on it.
A missing dashboard profile is treated as disabled and does not fail the switch.
Under the `nemohermes` alias, it uses the registered Hermes sandbox when exactly one exists; otherwise pass `--sandbox <name>` to target one explicitly.

</AgentOnly>

<AgentOnly variant="openclaw,hermes">

By default, the command syncs the default registered sandbox.
The command refuses before changing the OpenShell route when the selected sandbox has shields up.
Run `$$nemoclaw <name> shields down`, apply the inference change, then run `$$nemoclaw <name> shields up` again.

Each OpenShell gateway exposes one inference route to every sandbox registered on that gateway.
Before changing the route, NemoClaw compares the requested provider and model with every same-gateway registry entry, including stopped sandboxes.
Custom compatible routes must also have matching normalized endpoint URLs and API families.
Provider-global credential environment-variable names must also match for the same provider name.
If a route conflicts or a legacy custom route lacks enough endpoint or API-family metadata to prove compatibility, the command exits non-zero before changing the OpenShell route, agent config, or host registry and names the conflicting sandboxes.
Align those sandboxes to the same route or remove a conflicting sandbox that you no longer need.

Onboarding and `connect` can time-share compatible provider and model routes without replacing provider-global configuration.
Refer to [Use Shared Gateway Routes](../inference/manage-inference/use-shared-gateway-routes) for the onboarding warnings, compatibility fields, and status drift report.

```bash
$$nemoclaw inference set --provider <provider> --model <model> [--sandbox <name>] [--no-verify] [--endpoint-url <url>] [--credential-env <ENV>] [--inference-api <api>]
```

You can also name the sandbox in sandbox-first position instead of passing `--sandbox`.
`$$nemoclaw <name> inference set --provider <provider> --model <model>` targets `<name>` directly and is equivalent to `$$nemoclaw inference set --provider <provider> --model <model> --sandbox <name>`.

```bash
$$nemoclaw my-assistant inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b
```

Pass both `--provider` and `--model` when you want NemoClaw to update the OpenShell inference route and sync the selected sandbox's agent config.
NemoClaw resolves the OpenShell gateway from the target sandbox's recorded gateway binding, including non-default `NEMOCLAW_GATEWAY_PORT` deployments.
Do not run `openshell inference set` directly on a shared NemoClaw gateway because that bypasses registry compatibility checks and can break other sandboxes.
When either flag is missing, `$$nemoclaw inference set` reports both required flags without suggesting a raw OpenShell command.
The command updates the host registry immediately after the gateway route changes.

</AgentOnly>

<AgentOnly variant="openclaw">

If the in-sandbox config sync fails, NemoClaw keeps the gateway and registry aligned, warns that the running image may still need a rebuild, and points you to `$$nemoclaw <name> rebuild`.

</AgentOnly>

<AgentOnly variant="hermes">

If the in-sandbox config write or integrity hash update fails, the OpenShell route and NemoClaw registry remain committed, but the command exits with status `1` and points you to `$$nemoclaw <name> rebuild`.

</AgentOnly>

<AgentOnly variant="openclaw,hermes">

Supported provider names are `nvidia-prod`, `nvidia-nim`, `nvidia-router`, `openai-api`, `anthropic-prod`, `compatible-anthropic-endpoint`, `gemini-api`, `compatible-endpoint`, `hermes-provider`, `ollama-local`, and `vllm-local`.
Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential.
When you explicitly supply a direct compatible endpoint at `http://host.openshell.internal:<port>`, NemoClaw skips OpenShell's host-side provider probe because that hostname resolves only inside the sandbox network.
Before it persists the route in the NemoClaw registry or agent config, the command sends a validation request from the target sandbox with a 16-token output limit.
When the switch changes the API family and that request returns HTTP `400` or `404`, NemoClaw retries up to two times after delays of one and two seconds.
Each retry has the same 16-token output limit.
Other failures are not retried.
If that request fails, the command attempts to restore the previous OpenShell selection and remove a provider that this switch created.
If the error reports that rollback could not complete, rerun onboarding before using the route or retrying the switch.
Endpoint-shape and shared-gateway compatibility checks still apply.
When switching to `compatible-endpoint` or `compatible-anthropic-endpoint` from a different provider family, pass `--endpoint-url` with the trusted custom provider URL and, except for the Hermes case below, `--inference-api` with its API family so NemoClaw can persist a complete route identity for rebuild and shared-gateway checks.
For a Hermes `compatible-anthropic-endpoint` target, `--inference-api` may be omitted because NemoClaw deterministically selects `openai-completions`; an explicit different API family is rejected.
NemoClaw rejects loopback, link-local, private, and internal endpoint addresses, including public hostnames that resolve to a private address.
For a same-provider model change, pass `--endpoint-url` with the endpoint URL recorded during onboarding for the target sandbox.
Missing or `inference set` provenance and every different URL remain subject to the full address validation above.
For public HTTP URLs, NemoClaw stores the validated IP address to prevent DNS rebinding.
For a DNS-backed HTTPS URL, NemoClaw routes the endpoint through a local HTTPS Pin Runtime adapter that terminates a pinned, SNI-correct outbound connection to the real upstream hostname; the sandbox and the persisted registry only ever see a local `host.openshell.internal` route, never the real hostname.
HTTPS IP-literal URLs remain supported and do not need the adapter.
NemoClaw accepts `http://host.openshell.internal:<port>` only with an explicit port from `1024` through `65535`; this narrow exception supports NemoClaw's sandbox-to-host inference routes and is not a general private-endpoint bypass.
`--credential-env` may also be supplied for compatible provider metadata; supported `--inference-api` values are `openai-completions`, `anthropic-messages`, and `openai-responses`.

</AgentOnly>
<AgentOnly variant="openclaw">

```bash
$$nemoclaw inference set --provider <provider> --model <model> [--sandbox <name>] [--no-verify] [--endpoint-url <url>] [--credential-env <ENV>] [--inference-api <api>] [--reasoning-effort <effort>]
```

`--reasoning-effort` accepts `low`, `medium`, `high`, or `default`.
An explicit flag or `NEMOCLAW_REASONING_EFFORT` value applies only to a `compatible-endpoint` route that resolves to `openai-completions`.
NemoClaw validates the explicit value, provider, and API before it changes the OpenShell route, the agent config, or the host registry.
It rejects an unsupported route for every explicit value, including `default`.
For a `low`, `medium`, or `high` value on an `openai-completions` route, NemoClaw writes `params.extra_body.reasoning_effort` on the model entry, and OpenClaw merges it into the request body.
`--reasoning-effort` overrides `NEMOCLAW_REASONING_EFFORT`.
When you omit the flag, `$$nemoclaw inference set` applies an exported `NEMOCLAW_REASONING_EFFORT`.
When neither is set, the sandbox keeps the recorded effort only while the resulting route uses `compatible-endpoint` and `openai-completions`.
Without an explicit effort input, switching to another provider or API family removes an inherited `reasoning_effort` field and records the endpoint-default state.
Pass `default` on a `compatible-endpoint` route that uses `openai-completions` to clear a recorded effort and return the endpoint to its own default.
An ordinary sandbox restart preserves the resulting effort or endpoint-default state; it does not replay the image's original onboarding value.

</AgentOnly>
<AgentOnly variant="deepagents">

For Deep Agents sandboxes, run `$$nemoclaw onboard --fresh --name <sandbox-name> --recreate-sandbox` when you need to change the provider or model.
The managed `dcode` configuration is written under `/sandbox/.deepagents` during onboarding, so the recreate path keeps the OpenShell route and the sandbox config aligned.
Use `$$nemoclaw inference get` and `$$nemoclaw <name> status` to inspect the current route.

</AgentOnly>

### `$$nemoclaw setup`

<Warning>
The `$$nemoclaw setup` command is deprecated.
Use `$$nemoclaw onboard` instead.
</Warning>

This command remains as a compatibility alias to `$$nemoclaw onboard` and accepts the same flags: `--profile <name>`, `--non-interactive`, `--resume`, `--fresh`, `--recreate-sandbox`, `--gpu` / `--no-gpu`, `--from`, `--name`, `--host-mount`, `--sandbox-gpu` / `--no-sandbox-gpu`, `--sandbox-gpu-device`, `--agent`, `--agents <agents.yaml>`, `--tool-disclosure <progressive|direct>`, `--observability` / `--no-observability`, `--control-ui-port`, `--yes` / `-y`, `--no-ollama-autostart`, `--yes-i-accept-third-party-software`.

```bash
$$nemoclaw setup
```

### `$$nemoclaw setup-spark`

<Warning>
The `$$nemoclaw setup-spark` command is deprecated.
Use the standard installer and run `$$nemoclaw onboard` instead, because current OpenShell releases handle the older DGX Spark cgroup behavior.
</Warning>

This command remains as a compatibility alias to `$$nemoclaw onboard` and accepts the same flags: `--profile <name>`, `--non-interactive`, `--resume`, `--fresh`, `--recreate-sandbox`, `--gpu` / `--no-gpu`, `--from`, `--name`, `--host-mount`, `--sandbox-gpu` / `--no-sandbox-gpu`, `--sandbox-gpu-device`, `--agent`, `--agents <agents.yaml>`, `--tool-disclosure <progressive|direct>`, `--observability` / `--no-observability`, `--control-ui-port`, `--yes` / `-y`, `--no-ollama-autostart`, `--yes-i-accept-third-party-software`.

```bash
$$nemoclaw setup-spark
```

### `$$nemoclaw debug`

Collect diagnostics for bug reports.
Gathers system info, Docker state, gateway logs, and sandbox status into a summary or tarball.
Use `--sandbox <name>` to target a specific sandbox, `--quick` for a smaller snapshot, or `--output <path>` to save a tarball that you can attach to an issue.

```bash
$$nemoclaw debug [--quick|-q] [--sandbox NAME] [--output PATH|-o PATH]
```

| Flag | Description |
|------|-------------|
| `--quick`, `-q` | Collect minimal diagnostics only |
| `--sandbox NAME` | Target a specific sandbox (default: auto-detect) |
| `--output PATH`, `-o PATH` | Write diagnostics tarball to the given path |

If `--output` is set and the tarball cannot be written (for example, the destination directory is missing or read-only), the command exits non-zero so scripts can detect the failure.
The tarball is written to a temporary sibling and renamed on success, so a pre-existing file at `--output` is preserved when `tar` fails.

When `--sandbox` is supplied explicitly through the flag or one of `NEMOCLAW_SANDBOX_NAME`, `NEMOCLAW_SANDBOX`, or `SANDBOX_NAME`, the name must match a registered sandbox.
The flag wins, then the env vars in that order.
If `openshell sandbox list` succeeds, the sandbox must also appear in the live gateway.
An unknown or stale name exits non-zero with an actionable error that names the sandbox and reports the source env var when applicable, and no tarball is written.
Without an explicit name, `$$nemoclaw debug` falls back to the registry's default sandbox and warns if that default is stale.

### `$$nemoclaw credentials list`

List the provider credentials registered with the OpenShell gateway.
Values are not printed.

```bash
$$nemoclaw credentials list
```

### `$$nemoclaw credentials add <PROVIDER>`

Register a provider credential with the OpenShell gateway by name and type.
Each `--credential` takes the env variable name whose value the gateway should read; export the value first so it is not placed in argv.
Pass either repeatable `--credential <ENV_NAME>` or `--from-existing`, but do not combine them.
After the gateway accepts the provider, rebuild the target sandbox so the new provider is attached.

Registered providers attach to every sandbox you build or rebuild after the call (the gateway is one process serving all sandboxes).
If you want a provider available to only some sandboxes, scope it with `nemoclaw credentials reset <PROVIDER>` once those sandboxes finish using it.

```bash
$$nemoclaw credentials add tavily-search --type tavily --credential TAVILY_API_KEY
```

| Flag | Description |
|------|-------------|
| `--type <TYPE>` | Provider type (e.g. `tavily`, `nvidia`, `openai`, `anthropic`, `generic`) |
| `--credential <ENV_NAME>` | Env variable name whose value holds the credential. Repeatable |
| `--config <K=V>` | Provider configuration pair. Repeatable |
| `--from-existing` | Load credentials and config from existing local state |

### `$$nemoclaw credentials reset <PROVIDER>`

Remove a provider credential from the OpenShell gateway by provider name.
After removal, re-running `$$nemoclaw onboard` re-prompts for that provider's credential.
Run `$$nemoclaw credentials list` first if you are not sure of the provider name.

```bash
$$nemoclaw credentials reset nvidia-prod
```

| Flag | Description |
|------|-------------|
| `--yes`, `-y` | Skip the confirmation prompt |

### `$$nemoclaw gc`

Remove orphaned sandbox Docker images from the host.
Sandbox creation can build images in the gateway-managed `openshell/sandbox-from` repository or the locally prebuilt `nemoclaw-sandbox-local` repository.
The `destroy` and `rebuild` commands clean up the image automatically, but images from older NemoClaw versions or interrupted operations may remain.
This command lists images from both repositories, cross-references the sandbox registry, and removes any that are no longer associated with a registered sandbox.

```bash
$$nemoclaw gc [--dry-run] [--yes|-y|--force]
```

| Flag | Description |
|------|-------------|
| `--dry-run` | List orphaned images without removing them |
| `--yes`, `-y`, `--force` | Skip the confirmation prompt |

### `$$nemoclaw uninstall`

Run `uninstall.sh` to uninstall NemoClaw. Unless this section explicitly describes portable cleanup, its resource-removal statements apply outside portable cleanup.
The CLI runs the local `uninstall.sh` shipped with the installed npm package.
If that local script is missing, the CLI does not auto-fetch a remote copy.
It prints the versioned URL of the matching `uninstall.sh` so you can download, review, and run it manually.

When the gateway is externally supervised, uninstall preserves its process, Docker resources, and OpenShell binaries.
It still deletes the selected sandboxes and attempts to remove the modern local gateway registration.
When uninstall confirms that no sibling gateways remain, it also deletes NemoClaw provider registrations.
For a managed dual-Station vLLM runtime, full uninstall revalidates the exact recorded pair and removes both managed containers before starting the remaining uninstall steps.
If that cleanup fails, uninstall exits nonzero, preserves its owner-only cleanup receipt, and tells you to resolve the reported peer error before retrying.
Pair cleanup can partially complete before an error; verify both Stations before the retry.
For an authenticated host-local vLLM runtime, full uninstall verifies the exact named container, NemoClaw ownership label, persisted API key, and authentication fingerprint before removing the container by its inspected ID.
When that ownership state is missing, full uninstall removes the reserved `nemoclaw-vllm` container only when Docker reports its NemoClaw managed label and a valid container ID.
An unlabeled container or malformed inspection remains in place and stops the remaining uninstall steps.
For managed llama.cpp, full uninstall verifies the exact named container and network ownership before removing both resources by their inspected IDs.
These host-local checks run before NemoClaw deletes their state.
If Docker is unavailable or a resource does not match its persisted ownership state, uninstall exits nonzero before the remaining uninstall steps and preserves that state for recovery.
Host-local cleanup can partially complete before an error.
Restore Docker access or resolve the named ownership conflict, inspect the remaining container and network, and retry uninstall.
Managed llama.cpp and vLLM model files remain in the shared Hugging Face cache by default.
Outside portable cleanup, `--delete-models` deletes every model in the local Ollama inventory and all non-credential data in the current user's shared `~/.cache/huggingface/` cache.
This opt-in can delete cached files that other applications installed or use.
It preserves the Hugging Face `token` and `stored_tokens` authentication files.
NemoClaw stops and verifies its managed local and distributed model runtimes before it deletes non-credential data from the local Hugging Face cache.
It does not scan arbitrary directories or delete model caches on remote peers.
When sibling gateway environments remain, uninstall preserves both model stores even if you pass `--delete-models`.
An Ollama inventory error, model deletion error, unsafe cache path, or cache-data deletion error makes uninstall exit nonzero.
Cleanup can partially complete before an error, so resolve the reported error and rerun uninstall.
It does not use the legacy `gateway destroy` command for that gateway.
<AgentOnly variant="openclaw">

Refer to [Declare the OpenShell Gateway Lifecycle Authority](../deployment/gateway-lifecycle-authority).

</AgentOnly>

Outside portable cleanup, uninstall also stops any orphaned `openshell` host processes left behind by previous onboard or destroy cycles, including `openshell sandbox create`, `openshell ssh-proxy`, and SSH sessions spawned by OpenShell.
Earlier releases only stopped `openshell forward` processes, so those orphans accumulated across runs.

Outside portable cleanup, uninstall also stops matching Ollama auth proxy processes before deleting `~/.nemoclaw` state so stale proxy listeners do not block a later reinstall.
When sibling gateways remain, uninstall leaves the shared proxy running for them.

For Hermes setups, uninstall inspects the selected gateway's managed port-forward watcher state, stops each verified watcher process and its sandbox-scoped forward, and leaves sibling gateway state untouched.
If any watcher or forward cleanup cannot be confirmed, uninstall exits nonzero and preserves the selected gateway's watcher state so you can retry cleanup.

Outside portable cleanup, Linux uninstall removes `~/.local/state/nemoclaw` unless you pass `--keep-openshell`, the gateway is externally supervised, or another gateway-port environment remains on the host.
That directory contains NemoClaw-owned Docker-driver gateway configuration and SQLite data, audit logs, VM-driver state, and standalone-fallback gateway PID files.
Uninstall preserves it when the managed or externally supervised gateway process remains because that process depends on the state.
When another gateway-port environment remains, uninstall removes only the selected gateway port's subdirectory of that directory and keeps the other ports' subdirectories.
Run `$$nemoclaw uninstall --all-gateway-ports` to remove every gateway port on the host.
Keep a declared external gateway state directory outside that NemoClaw-owned path.
Uninstall does not otherwise target the declared external directory.

| Flag | Effect |
|---|---|
| `--yes` | Skip the confirmation prompt |
| `--keep-openshell` | Leave OpenShell binaries, NemoClaw-managed gateway service files, and local gateway state in place, and do not stop the host gateway process |
| `--delete-models` | Outside portable cleanup, delete every model reported by the host's local Ollama inventory and all non-credential data in the current user's shared `~/.cache/huggingface/` cache after managed model runtimes stop. Hugging Face authentication files remain. Portable cleanup preserves both model stores and every Podman image. |
| `--destroy-user-data` | Also remove preserved user data (`rebuild-backups/`, `backups/`, `sandboxes.json`). Removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified. When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package. Portable cleanup still retains its recovery record until later completed onboarding durably supersedes it. |
| `--all-gateway-ports` | Uninstall every gateway port on the host, not only the port `NEMOCLAW_GATEWAY_PORT` selects |
| `--gateway <name>` | Optional consistency check; must match the name derived from `NEMOCLAW_GATEWAY_PORT` |

```bash
$$nemoclaw uninstall [--yes] [--keep-openshell] [--delete-models] [--destroy-user-data] [--all-gateway-ports] [--gateway <name>]
```

`NEMOCLAW_GATEWAY_PORT` selects the gateway instance and state root to uninstall.
Port `8080` selects `nemoclaw` and the shared `~/.nemoclaw/` root; a non-default port selects `nemoclaw-<port>` and `~/.nemoclaw/gateways/<port>/`.
For example, `NEMOCLAW_GATEWAY_PORT=9123 $$nemoclaw uninstall` selects `nemoclaw-9123`.
The compatibility `--gateway` flag cannot select another instance: when present, it must match the name derived from `NEMOCLAW_GATEWAY_PORT`, or uninstall exits before cleanup.
Default-port uninstall removes NemoClaw-managed entries in `openshell/gateway.env`.
For a NemoClaw-managed authority, it also removes only NemoClaw's marked Linux gateway unit.
It preserves upstream Linux package units, the macOS Homebrew service, and unrelated environment entries.
Gateway-scoped cleanup removes that gateway's OpenShell resources first, then the marked Linux unit.
The OpenShell gateway service therefore keeps running while uninstall deletes the selected gateway's sandboxes.
If OpenShell resource cleanup fails, uninstall exits nonzero and preserves the marked Linux unit and gateway process.
If marked Linux unit cleanup fails, uninstall exits nonzero before it scans for or stops a remaining gateway process or continues with later Docker and gateway-state cleanup.
OpenShell resource and Linux unit cleanup can partially complete before either failure.
After selected sandbox cleanup succeeds, uninstall removes those entries from `sandboxes.json` before gateway registration and Linux unit cleanup.
If a later step fails, the retry skips the completed sandbox deletions and resumes the remaining cleanup.
Resolve the reported error.
Inspect the remaining gateways with `openshell gateway list`.
Rerun `NEMOCLAW_GATEWAY_PORT=<port> $$nemoclaw uninstall` with the gateway port from the failed uninstall.
For an externally supervised authority, uninstall preserves the selected local gateway state in both full and gateway-scoped cleanup.
It also preserves the gateway process, supervisor resources, marked Linux unit, Docker resources, OpenShell binaries, and the declared external state directory.
A custom-port uninstall does not stop or remove the default gateway service or its environment file.
Uninstall does not stop an `openshell-gateway` process that another non-root user owns and that this installation did not record.
It names the owner and process ID, leaves that process running, and continues with the remaining cleanup.
If no other cleanup fails, uninstall exits with status `0` even though that process can keep its port in use.
Uninstall still tries to stop a `root`-owned process and the gateway process that this installation recorded.
If either stop fails, uninstall reports the process without printing a reusable privileged kill command.
Do not signal a PID from saved output.
Immediately before a privileged stop, verify that the live process owner and `openshell-gateway` command line match the exact gateway name and port.
Also prove that the PID file, runtime marker, and loaded sandbox namespace still match the selected state directory.
Rerun uninstall after the process stops.
A gateway-scoped uninstall and every `--all-gateway-ports` pass exit nonzero after that failure.
A single full uninstall reports the process and continues.
Before each sandbox deletion during scoped Docker cleanup, NemoClaw proves the selected configuration and running gateway identity again and passes the selected gateway name to OpenShell.
The configuration and running process must use the state-root-specific OpenShell sandbox namespace that NemoClaw generated.
For a NemoClaw-managed gateway, the live proof also binds the process owner, PID file, runtime marker, and command line to the exact gateway name and port.
For an externally supervised gateway, NemoClaw proves the configured state.
It binds the supervisor's current main process to its owner, loaded sandbox namespace, declared executable, selected gateway name, and selected port.
When NemoClaw can prove an owner-private, generated configuration and complete JWT bundle that predate state-root scoping, restart keeps the legacy gateway ID, JWT bundle, and Docker driver's `default` namespace.
That compatibility keeps the gateway able to find existing containers and keeps their non-expiring sandbox JWT issuer valid.
NemoClaw regenerates the other gateway settings from the current runtime configuration.
For a proven legacy Podman gateway, NemoClaw preserves the gateway ID that existing sandbox JWTs use; the supported Podman schema has no `sandbox_namespace` setting to preserve.
If the existing identity is ambiguous or unsafe, or durable gateway state remains without its configuration, restart fails closed without rewriting the configuration or JWT bundle.
Fresh state roots and already scoped configurations continue to use the state-root-specific identity.
The legacy `default` namespace is not isolated across gateways, so it cannot satisfy the scoped-uninstall proof while sibling gateways remain.
Scoped uninstall stops before it deletes a sandbox, registry row, or gateway registration and preserves the selected gateway's runtime evidence and local state.
Because the supported OpenShell Podman schema does not expose `sandbox_namespace`, scoped Podman uninstall fails closed before signaling and preserves the gateway runtime evidence and local state.
Full single-gateway Podman uninstall for the portable experimental profile uses exact receipt-owned durable retirement and preserves shared OpenShell providers, the gateway service and process, binaries, configuration, model stores, and Podman images under the [portable authority, retry, and preservation contract](../manage-sandboxes/operate-sandboxes/uninstall-nemoclaw).
For Docker, if any proof is absent, uninstall exits nonzero before it signals the host gateway.
NemoClaw preserves the gateway runtime evidence and local state.
Keep that state intact.
For an already scoped gateway with stale runtime evidence, restore it through the supported install or onboarding recovery flow, verify the generated identity, and retry.
A proven legacy gateway is not silently converted by onboarding.
To retire one, first remove sibling gateways through their own proven scoped cleanup, verify that only the legacy gateway remains, and then use the full single-gateway uninstall path.
For an ambiguous or incomplete identity, stop the gateway and restore the exact generated `openshell-gateway.toml` and complete `jwt/` directory from a dedicated host-level backup path, represented here as `<gateway-identity-backup>`.
The backup must have been captured from that gateway's exact state directory before the failure and kept under the owning user's exclusive access.
Keep the `<gateway-identity-backup>` directory and its nested `jwt/` directory at mode `0700`, and keep the configuration and JWT files at mode `0600`.
The default gateway stores them under `~/.local/state/nemoclaw/openshell-docker-gateway/`; a non-default gateway uses `~/.local/state/nemoclaw/openshell-docker-gateway-<port>/`.
Restore them as the owning user.
Keep the gateway state root and its `jwt/` directory at mode `0700`, and do not grant group or other access to the configuration or JWT files.
NemoClaw does not reconstruct gateway identity from sandbox snapshots or `backup-all`; if no matching gateway-state backup exists, keep the state intact rather than attempting a scoped cleanup.
Verify every gateway with `openshell gateway list`.
Retain `<gateway-identity-backup>` only until that command reports the restored gateway and the affected existing sandboxes authenticate successfully.
Then remove that dedicated backup directory as the owning user and verify its absence by replacing the placeholder in `test ! -e '<gateway-identity-backup>'` with the full backup path.
If verification fails, keep the backup under the same access restrictions and stop.
Do not add `sandbox_namespace` manually to a live gateway configuration because the running process can still be using its previous namespace.

##### Uninstalling Every Gateway Port

A single uninstall is scoped to one gateway port, so the other ports on the host keep running and keep their ports bound.
When uninstall detects other gateway-port environments, it names each one, gives the `NEMOCLAW_GATEWAY_PORT=<port>` command that removes one of them, and points at the whole-host sweep.
A gateway environment whose port cannot be read is reported as an unidentified environment rather than omitted.

`--all-gateway-ports`, or `NEMOCLAW_UNINSTALL_ALL_GATEWAY_PORTS=1`, uninstalls all of them in one run.
The sweep enumerates the default state root and the non-default roots under `~/.nemoclaw/gateways/`.
When the sweep finds more than one port, it confirms once against the resulting port list, then uninstalls each other port before the port `NEMOCLAW_GATEWAY_PORT` selects.
When it finds only the selected port, it uses the standard uninstall confirmation without a port list and runs that port once.
Each port runs as its own uninstall so that every port-scoped value, including the state root, registry file, gateway name, and Docker resource names, resolves from that port rather than from the calling environment.
Outside portable cleanup, the selected port runs last so its pass can remove the shared host resources once no other environment remains.
`--delete-models`, `--destroy-user-data`, and `--keep-openshell` apply to every port, subject to the portable preservation contract; `--gateway` remains a check against the selected port only.
A failure to enumerate the gateway state roots safely stops the sweep before any port uninstall begins.
The sweep cannot select an unidentified environment until its gateway port can be determined.
A port that fails to uninstall is reported, the sweep continues, and the exit code is nonzero.
That port still counts as a live sibling, so the final pass falls back to gateway-scoped cleanup and preserves the shared host resources.
Cleanup that completed before a port failure is not rolled back.
Resolve the reported error, inspect the remaining gateways with `openshell gateway list`, and rerun the sweep or the named per-port command.

##### User-data preservation under `~/.nemoclaw/`

To avoid uninstall destroying host-side user data, uninstall preserves the following entries in the selected gateway's state root by default.
The default gateway uses `~/.nemoclaw/`; a non-default gateway uses `~/.nemoclaw/gateways/<port>/`.

| Entry | What it holds |
|---|---|
| `rebuild-backups/` | Host-side snapshots that `$$nemoclaw <name> snapshot create` and `$$nemoclaw backup-all` write. `$$nemoclaw <name> snapshot restore` reads them back after you reinstall. |
| `backups/` | Host-side workspace backups that `scripts/backup-workspace.sh` writes. Refer to [Transfer State Manually](../manage-sandboxes/state-and-backups/transfer-state-manually). |
| `sandboxes.json` | Host-side sandbox registry. NemoClaw uses it to map sandbox names back to their persistence directories when you reinstall. |

Outside portable cleanup, when uninstall confirms that no sibling gateways remain, it also removes shared host resources such as the gateway source clone, runtime state, and the Ollama auth proxy PID file.
When sibling gateways remain, it removes only the selected gateway's resources and port-scoped state while preserving those shared host resources.
With `--destroy-user-data`, that scoped path removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified (for example odd `~/.nemoclaw/gateways/` entries or an unreadable gateway list). When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package and the other shared host resources.
If the OpenShell command is unavailable or its gateway list cannot be read, uninstall cannot confirm that the selected gateway is the last one, so it uses the same scoped path and preserves the shared resources.
When the command itself is unavailable, uninstall exits nonzero before OpenShell cleanup so you can restore the command and retry.

`--yes` deliberately remains non-destructive for user data.
It only acknowledges the global `Proceed?` confirmation prompt and still preserves the listed entries.
Removing the preserved entries always requires an explicit opt-in flag (`--destroy-user-data`) or the matching env var (`NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1`).
Existing automation using `--yes` therefore retains its safe behaviour and never loses host-side state by accident.

Decision matrix:

| Context | Behaviour |
|---|---|
| Interactive TTY, preserved entries present, no env override | Prompts `Also remove them? [y/N]`. Default `N` keeps the entries. |
| Interactive TTY, user answers `y` | Removes the preserved entries in the selected gateway's state root; outside portable cleanup, a single-gateway uninstall also removes the remaining shared state. Portable cleanup preserves shared OpenShell resources and its retirement record. |
| Non-interactive (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or non-TTY shell) | Preserves the entries and prints a one-line notice. |
| `--destroy-user-data` | Skips the secondary user-data prompt and removes the preserved entries in the selected gateway's state root. Removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified. When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package. The global `Proceed?` confirmation still applies unless `--yes` is also passed. |
| `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` | Skips the secondary user-data prompt and removes the preserved entries. Removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified. When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package. The global `Proceed?` confirmation still applies unless `--yes` is also passed. |

The preserved entries survive uninstall as inert files on disk.
Reinstall NemoClaw and re-onboard the sandbox before `$$nemoclaw <name> snapshot restore` can use them.

The preserved `sandboxes.json` file does not make the recorded sandboxes recoverable on its own.
Uninstall deletes the selected sandboxes and attempts to remove the local gateway registration.
Outside portable cleanup, after uninstall confirms that no sibling gateways remain, it also deletes provider registrations.
Outside portable cleanup, a NemoClaw-managed gateway also removes the Docker image.
For an externally supervised gateway, it preserves Docker resources, but the registry still cannot recover deleted sandbox and provider resources.
Uninstall warns about this at preserve time.
After reinstalling, the installer reports such records as not found on their recorded gateway instead of claiming they were recovered; run `$$nemoclaw <name> destroy` to clear a stranded record, then `$$nemoclaw onboard` to rebuild it.
Pass `--destroy-user-data` at uninstall time if you prefer to purge the registry along with its dependencies.

#### `$$nemoclaw uninstall` vs. the hosted `uninstall.sh`

Both forms execute the same `uninstall.sh` with the same flags, but differ in where the script comes from and how much they trust the network.
Use `$$nemoclaw uninstall` by default.
Use the hosted `curl … | bash` form only when the CLI is broken or already partially removed.

|  | `$$nemoclaw uninstall` | `curl … \| bash` (Quickstart) |
|---|---|---|
| **Source of the script** | Local `uninstall.sh` shipped with the installed npm package. | Pulled live from `refs/heads/main` on GitHub. |
| **Version pinning** | Pinned to the version of NemoClaw you installed. | Whatever is on `main` right now; may be newer than your installed CLI. |
| **Network trust** | No network fetch at uninstall time; runs a vetted local file via `bash`. | Pipes a remote script straight to `bash` with no review step. |
| **Robustness** | Requires the npm package to be discoverable so the CLI can find the local script. | Works even if the `$$nemoclaw` CLI is missing, broken, or partially uninstalled. |
| **Recommended for** | Routine uninstalls. | Recovery when the CLI is unavailable. |

## Internal Commands

NemoClaw registers a hidden `internal` command namespace. These commands are
compatibility entrypoints for repo-owned scripts, such as the installer, the
uninstaller, DNS setup, and developer tooling. They are not part of the
supported public CLI surface.

Each command class sets `hidden = true`, so the commands stay out of
`$$nemoclaw --help`. They remain registered and routable, which is why they are
listed here for reference. Treat their names, flags, and output as
implementation details. They exist to back `install.sh`, `uninstall.sh`, and
related automation, and they may change or be removed without notice. Most run
indirectly through those scripts rather than being typed by hand.

For contributor guidance on how these command files are structured, refer to
`src/commands/internal/README.md`.

| Command | Owning script context | Purpose |
|---------|-----------------------|---------|
| `$$nemoclaw internal installer plan` | `install.sh` | Build a deterministic installer plan from environment and probe inputs without applying it. |
| `$$nemoclaw internal installer normalize-env` | `install.sh` | Normalize installer ref and provider environment values without applying installation changes. |
| `$$nemoclaw internal installer resolve-release-tag` | `install.sh` | Resolve the installer ref using the same precedence as `install.sh`. |
| `$$nemoclaw internal uninstall plan` | `uninstall.sh` / `$$nemoclaw uninstall` | Build a deterministic uninstall plan without applying it. |
| `$$nemoclaw internal uninstall run-plan` | `uninstall.sh` / `$$nemoclaw uninstall` | Remove host-side NemoClaw resources from a previously built plan. |
| `$$nemoclaw internal uninstall classify-shim` | `uninstall.sh` / `$$nemoclaw uninstall` | Classify whether a shim path is safe for the uninstaller to remove. |
| `$$nemoclaw internal dns setup-proxy` | onboarding / sandbox setup | Configure the DNS forwarder bridge inside a sandbox pod. |
| `$$nemoclaw internal dns fix-coredns` | onboarding / sandbox setup | Patch CoreDNS to use a non-loopback upstream resolver. |
| `$$nemoclaw internal dev npm-link-or-shim` | `scripts/npm-link-or-shim.sh` (development) | Run `npm link`, falling back to a user-local NemoClaw development shim. |

These commands do not appear in the command-level parity check, which compares
`$$nemoclaw --help` against the public command headings in this reference; hidden
commands are excluded from both. The table above is the canonical reference for
the script-backed family.
The experimental adapter is documented separately because it has no owning script.

`$$nemoclaw internal voice-gateway serve` is registered for the OpenClaw-only experimental adapter described below.
Hermes and Deep Agents Code do not have an equivalent adapter.

<AgentOnly variant="openclaw">

#### $$nemoclaw internal voice-gateway serve

<Warning>

This hidden command is an experimental implementation detail, not a supported NemoClaw product surface or public protocol.
Do not expose its listener through a port forward, proxy, or public ingress.

</Warning>

This foreground command runs a private HTTP adapter that streams newline-delimited JSON (NDJSON) responses.
It accepts one authenticated runtime deployment and at most one active voice session.
Each voice session accepts one committed text turn.
NemoClaw selects the runtime profile, sandbox, and OpenClaw agent from command-line configuration.
The runtime cannot select an agent, OpenClaw session key, upstream URL, or forwarding destination.

The command requires the exact feature gate `NEMOCLAW_EXPERIMENTAL_VOICE_GATEWAY=1`.
Any other value stops the command before argument parsing, credential reads, or listener creation.
Other experimental feature gates do not enable this command.

Before starting the adapter, the bounded voice-gateway launcher opens two owner-only regular files without following symbolic links and maps only these inherited file descriptors into the child process:

- Descriptor `3` supplies the deployment credential used during session admission.
- Descriptor `4` supplies the OpenClaw credential with `operator.read` and `operator.write` scopes.

The descriptor numbers are fixed and are not configurable flags.
The command rejects missing, duplicate, non-regular, wrong-owner, group-accessible, malformed, and oversized inputs.
It reads each descriptor once and closes both before accepting traffic.
Both credential values remain in process memory until the voice-gateway process stops.
The launcher does not place credential source paths or values in arguments or environment variables.
It intentionally inherits only credential descriptors `3` and `4` across this exec, then closes its parent copies.
To rotate either credential, stop the command and restart it with newly opened descriptors.
NemoClaw does not send the OpenClaw credential to the runtime.
The trusted caller selects each credential source path and invokes the launcher.
That caller must create, replace, and remove each source file and revoke old credential values.
The launcher opens each source file, maps the inherited child descriptors, and closes its parent copies.
The child validates, reads, and closes descriptors `3` and `4` before it accepts traffic.
Closing the descriptors or stopping the gateway does not remove a source file or revoke its credential.

The launcher is an internal library boundary for trusted external integrations, not another CLI command and not part of normal NemoClaw managed startup.
Callers use the shipped `runVoiceGatewayLaunch()` action with trusted source paths and runtime fields; package-contract coverage launches the real internal command through that production entry point and verifies descriptor cleanup and restart-based credential rotation.
If parent descriptor cleanup fails and bounded termination does not observe child exit, the action throws `VoiceGatewayTerminationUnconfirmedError` with the retained child handle and original cleanup failure.
The trusted caller must recognize that error, terminate and reap its `child`, and confirm exit before starting another gateway.
The launcher emits the following child-process contract with no credential paths or values in its arguments or environment.
Do not run this child command directly because it requires the launcher's descriptor mapping.

```text
NEMOCLAW_EXPERIMENTAL_VOICE_GATEWAY=1 $$nemoclaw internal voice-gateway serve \
  --gateway-url ws://127.0.0.1:18789/ws \
  --runtime-identity <deployment-identity> \
  --runtime-profile <runtime-profile-id> \
  --sandbox <sandbox-name> \
  --agent <openclaw-agent-id> \
  --listen-port 18800
```

The `--gateway-url` value must use `ws://`, an explicit port, the `/ws` path, and a loopback IP address literal.
The URL must not contain credentials, a query string, or a fragment.
The adapter binds only to `127.0.0.1` and uses port `18800` when you omit `--listen-port`.
The JSON diagnostic with `"event":"voice_gateway"` and `"state":"listening"` confirms that the adapter acquired the configured loopback listener.

The runtime must keep the raw session grant in process memory.
NemoClaw keeps only the digest needed for constant-time grant validation.
When the session closes or expires, the runtime must discard the raw grant, and NemoClaw removes its validation digest from active session state.
The process owns the OpenClaw session binding, turn state, and response correlation.
It clears that state when the session closes or expires and when the foreground process stops.
Normal onboarding and managed startup do not start or supervise this command.

The adapter exchanges committed text and normalized response events only.
It does not implement audio, WebRTC, RTVI, voice activity detection, speech recognition, speech synthesis, playback, or runtime-specific UI behavior.
It also does not establish VoiceClaw, ElevenLabs, Hermes, or general voice support.

</AgentOnly>
<AgentOnly variant="hermes,deepagents">

The experimental voice gateway has no Hermes or Deep Agents Code equivalent.

</AgentOnly>

## Environment Variables

NemoClaw reads the following environment variables to configure service ports, onboarding behavior, and lifecycle defaults.
Set them before running `$$nemoclaw onboard` or any command that starts services.
All ports must be non-privileged integers between 1024 and 65535, unless a variable's own description gives a narrower range.

### CLI Logging

The centralized CLI logger writes its output to `stderr` and uses `info` verbosity by default.
These controls affect leveled logger output; they do not suppress command results or command-specific output that has not migrated to the centralized logger.

| Variable | Accepted values | Effect |
|----------|-----------------|--------|
| `NEMOCLAW_LOG_LEVEL` | `error`, `warn`, `info`, or `debug` (case-insensitive; surrounding whitespace is ignored) | Sets the logging threshold. A valid value takes precedence over `NEMOCLAW_DEBUG`. An invalid, blank, or unset value falls through to `NEMOCLAW_DEBUG`. |
| `NEMOCLAW_DEBUG` | `1`, `true`, `y`, or `yes` (case-insensitive) | Enables `debug` logging when `NEMOCLAW_LOG_LEVEL` does not contain a valid value. |

The environment precedence is `NEMOCLAW_LOG_LEVEL`, then `NEMOCLAW_DEBUG`, followed by the default `info` level.
The `error` level prints errors only, `warn` also prints warnings, `info` also prints informational messages, and `debug` prints all levels with timestamps.
Use these NemoClaw-specific variables instead of the generic `DEBUG` variable. `DEBUG` is not a NemoClaw logger control and can enable dependency diagnostics that include raw command arguments.

Commands whose parser owns the base logging options also accept the hidden long-form `--debug` and `--quiet` flags, even though these options do not appear in command help.
The flags are mutually exclusive.
`--debug` overrides the environment-derived threshold and selects `debug`, while `--quiet` caps verbosity at `warn` without increasing an environment-derived `error` threshold.
There is no global `-q` logging shorthand.
Passthrough commands do not consume flags intended for the downstream command as host logging options, so use the environment variables when you need unambiguous host logging around a passthrough invocation.

| Variable | Default | Service |
|----------|---------|---------|
| `NEMOCLAW_GATEWAY_PORT` | 8080 | OpenShell gateway port |
| `NEMOCLAW_GATEWAY_BIND_ADDRESS` | 127.0.0.1 | The OpenShell gateway uses this bind address. NemoClaw keeps Docker-driver gateways on loopback while gateway JWT auth is active. |
<AgentOnly variant="openclaw,hermes">
| `NEMOCLAW_DASHBOARD_PORT` | 18789 (auto-derived from `CHAT_UI_URL` port if set) | Dashboard or API forward |
</AgentOnly>
| `NEMOCLAW_VLLM_PORT` | 8000 | vLLM / NIM inference |
| `NEMOCLAW_OLLAMA_PORT` | 11434 | Ollama inference |
| `NEMOCLAW_OLLAMA_PROXY_PORT` | 11435 | Ollama auth proxy |
| `NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT` | 11437 | Host-side OpenRouter runtime adapter |
<AgentOnly variant="openclaw,hermes">
| `NEMOCLAW_DASHBOARD_BIND` | *unset* (loopback outside WSL) | Dashboard or API forward bind address. WSL uses an all-interface forward for Windows-host reachability. Set to `0.0.0.0` to opt in to remote bind on other SSH-deployed hosts. |
</AgentOnly>
<AgentOnly variant="openclaw">
| `NEMOCLAW_GATEWAY_WS_HOST` | *unset* (auto-derived inside the sandbox; loopback elsewhere) | Host used for the in-sandbox `OPENCLAW_GATEWAY_URL`; inside the sandbox it defaults to the primary interface address so `sessions_spawn` sub-agents can dial the gateway through the enforced network path. |
</AgentOnly>

If a port value is not a valid integer or falls outside the allowed range, the CLI exits with an error.
`NEMOCLAW_GATEWAY_PORT` also cannot overlap configured service, vLLM, Ollama, Ollama proxy, OpenRouter runtime adapter, or HTTPS Pin Runtime adapter ports, and cannot use reserved auto-allocation ranges or the default inference/proxy ports `8000`, `8081`, `11434`, `11435`, `11437`, and `11438`.
Port `8081` is reserved for authenticated existing-server attachment and the managed llama.cpp runtime.
It cannot be assigned to another configurable NemoClaw service port.
When you select OpenRouter, `NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT` must also be distinct from the gateway, vLLM, Ollama, Ollama proxy, and HTTPS Pin Runtime adapter ports.
When you run multiple NemoClaw gateways with different `NEMOCLAW_GATEWAY_PORT` values, NemoClaw derives a separate gateway name, state directory, and compatibility container name from the port so one gateway does not tear down another.
Only port `8080` uses a NemoClaw-managed Linux systemd user service or macOS Homebrew service.
NemoClaw-managed gateways on custom ports run as detached processes and do not change the default gateway service.
An externally supervised gateway can use any matching configured port and must be recovered through its declared supervisor.
On non-WSL hosts, `NEMOCLAW_OLLAMA_PORT` and `NEMOCLAW_OLLAMA_PROXY_PORT` must be different.
If you run Ollama on port 11435, set `NEMOCLAW_OLLAMA_PROXY_PORT` to another free port before onboarding.

`NEMOCLAW_GATEWAY_BIND_ADDRESS` accepts only `127.0.0.1` and `0.0.0.0`, but NemoClaw rejects `0.0.0.0` for Docker-driver gateways while gateway JWT auth is active.
<AgentOnly variant="openclaw,hermes">
Keep the OpenShell gateway on loopback and use `NEMOCLAW_DASHBOARD_BIND` when you need remote browser/API access.

`NEMOCLAW_DASHBOARD_BIND` controls the dashboard or API port forward bind address.
Outside WSL, the forward stays on `127.0.0.1` (loopback only) by default.
On WSL, NemoClaw binds the host-side forward on all interfaces so the Windows host can reach it, while the ready summary continues to print a loopback dashboard URL.
On non-WSL SSH-deployed hosts, set `NEMOCLAW_DASHBOARD_BIND=0.0.0.0` before `$$nemoclaw onboard` to prepare the sandbox for remote exposure and bind the forward on all interfaces.
Use the same setting for later `$$nemoclaw <sandbox> connect` calls.
A sandbox created without this opt-in must be recreated with `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 $$nemoclaw onboard --recreate-sandbox` before a remote-bind connect is allowed.
Only `0.0.0.0` enables the remote bind; onboarding rejects any other non-empty value.
</AgentOnly>

<AgentOnly variant="openclaw">

When the remote bind is opted in, the dashboard auth flow accepts non-loopback origins.

</AgentOnly>

```bash
export NEMOCLAW_DASHBOARD_PORT=19000
$$nemoclaw onboard
```

These overrides apply to onboarding, status checks, health probes, and the uninstaller.
Defaults are unchanged when no variable is set.
<AgentOnly variant="openclaw,hermes">
If `NEMOCLAW_DASHBOARD_PORT` or the port from `CHAT_UI_URL` is already occupied by another sandbox, onboarding scans `18789` through `18799` and uses the next free dashboard port.
Pass `--control-ui-port <N>` to require a specific port.
</AgentOnly>

<AgentOnly variant="openclaw">

For OpenClaw, `NEMOCLAW_DASHBOARD_PORT` controls the OpenClaw dashboard forward.

</AgentOnly>
<AgentOnly variant="hermes">

For Hermes, `NEMOCLAW_DASHBOARD_PORT` controls the built-in dashboard forward, which defaults to `18789`.
The OpenAI-compatible API is separate and serves `/v1` on a per-sandbox port that defaults to `8642`.
If `8642` is already held by another sandbox or by a non-OpenShell host listener, onboarding scans `8642` through `8652` and uses the next free API port.
Set `NEMOCLAW_HERMES_API_PORT=<N>` before you onboard a new sandbox to pin a port from `8642` through `8652`.
If another sandbox or host listener holds the pinned port, onboarding exits instead of selecting a different port.
The sandbox relay binds the port when the sandbox starts, so set this variable for an existing sandbox only together with `--recreate-sandbox`.
For an existing sandbox, a different value without `--recreate-sandbox` exits before the host forward changes.
Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` only when you want Hermes' optional in-browser TUI tab.

| Variable | Default | Service |
|----------|---------|---------|
| `NEMOCLAW_DASHBOARD_PORT` | 18789 | Hermes built-in dashboard forward port |
| `NEMOCLAW_HERMES_API_PORT` | 8642 | Hermes OpenAI-compatible API forward port |
| `NEMOCLAW_HERMES_DASHBOARD_TUI` | 0 | Optional Hermes in-browser TUI tab |

</AgentOnly>

### Onboarding Configuration

The following variables let you tune onboarding without editing the Dockerfile or passing repeated flags.
Set them before running `$$nemoclaw onboard`.

| Variable | Format | Effect |
|----------|--------|--------|
| `NEMOCLAW_PROVIDER` | provider key (e.g. `build`, `openrouter`, `openai`, `anthropic`, `anthropicCompatible`, `gemini`, `ollama`, `custom`, `vllm`, `nim-local`, `routed`, `hermes-provider`, `llama-cpp`, `install-llama-cpp`, `install-vllm`, `install-ollama`, `install-windows-ollama`, `start-windows-ollama`) | Selects the inference provider during onboarding. The wizard skips the provider menu in both interactive and non-interactive runs when this is set. On a qualified N1x host, only `install-vllm` supplies the explicit Deferred preview intent; another provider stops installation before onboarding. `llama-cpp` selects attachment of an authenticated, operator-managed llama.cpp server on loopback port `8081`. Set `NEMOCLAW_LLAMACPP_LOCAL_TOKEN`; set `NEMOCLAW_MODEL` to the served alias when the server exposes multiple models. `install-llama-cpp` selects the experimental DGX Spark managed path and rejects `NEMOCLAW_MODEL`; use `NEMOCLAW_LLAMACPP_RECIPE` for its declarative selection. If an operator-managed server does not provide consistent native llama.cpp evidence, select `custom`. Aliases: `cloud` → `build`, `open-router` / `openrouterai` → `openrouter`, `nim` → `nim-local`, `hermes` / `nous` / `nous-portal` → `hermes-provider`, `anthropiccompatible` → `anthropicCompatible`. Invalid values fail fast with the list of accepted keys. |
| `NEMOCLAW_LLAMACPP_RECIPE` | repository-owned managed-inference recipe ID | Selects the exact managed llama.cpp recipe when `NEMOCLAW_PROVIDER=install-llama-cpp`, including a compatible lower-priority profile. When unset, NemoClaw selects the unique highest-priority compatible automatic profile. An unknown recipe, an ambiguous selection, or a stale or incompatible readiness report fails before image, model, or runtime effects. |
| `NEMOCLAW_MODEL` | model ID | Selects an explicit model for a non-interactive onboarding run. NemoClaw preserves it across a detected provider switch, even when it matches the recorded provider's default. When this variable is unset during such a switch, NemoClaw ignores the `NEMOCLAW_PROVIDER_MODEL` compatibility fallback and uses normal provider model selection. |
| `NEMOCLAW_TOOL_DISCLOSURE` | `progressive` or `direct` | Selects progressive tool discovery or the prior direct-exposure behavior. Defaults to `progressive`; `--tool-disclosure` takes precedence when both are set. |
| `NEMOCLAW_ENDPOINT_URL` | URL | Custom endpoint URL. Used together with `NEMOCLAW_PROVIDER=custom` for OpenAI-compatible endpoints or `NEMOCLAW_PROVIDER=anthropicCompatible` for Anthropic-compatible endpoints. Onboarding rejects a URL that contains userinfo, query, or fragment components. |
| `NEMOCLAW_COMPATIBLE_AUTH_MODE` | `none` or unset | Explicitly selects no authentication for an HTTP OpenAI-compatible endpoint using `localhost`, `127.0.0.1`, or `[::1]` and port `8000`, `11434`, or `11435` during non-interactive onboarding. |
| `NEMOCLAW_TRUSTED_PRIVATE_HOSTS` | comma-separated exact hostnames or IP literals | Allows operator-owned RFC1918, CGNAT, or IPv6 unique local destinations through supported inference, managed MCP, and custom-policy registration paths. Link-local metadata and other reserved ranges remain blocked; DNS resolution and exact address pinning remain active; wildcards are not supported. |
| `NEMOCLAW_TRUSTED_PRIVATE_INFERENCE_HOSTS` | comma-separated exact hostnames or IP literals | Inference-only compatibility alias. Inference onboarding combines entries from this variable and `NEMOCLAW_TRUSTED_PRIVATE_HOSTS`. |
| `NEMOCLAW_PREFERRED_API` | `completions` (currently the only honored value) | Forces the validation probe to use the `/v1/chat/completions` API path instead of the newer `/v1/responses` API. |
| `NEMOCLAW_INFERENCE_INPUTS` | comma-separated list of `text` and/or `image` | Declares model input modalities for vision-capable models. Validated strictly; unknown tokens are ignored. |
| `NEMOCLAW_OLLAMA_REQUIRE_TOOLS` | `0` to disable, anything else to keep the default | When set to `0`, skips the Ollama tool-calling capability check during local-inference onboarding. |
| `NEMOCLAW_OLLAMA_INSTALL_MODE` | `system`, `user`, or empty/unset | Pins the Linux Ollama install location. Refer to the Linux Ollama install mode details below. |
| `NEMOCLAW_PROXY_HOST` | hostname or IP | Overrides the sandbox-side outbound HTTP proxy host. Defaults to `10.200.0.1`. |
| `NEMOCLAW_PROXY_PORT` | integer port | Overrides the sandbox-side outbound HTTP proxy port. Defaults to `3128`. |
<AgentOnly variant="openclaw">
| `NEMOCLAW_OPENCLAW_OTEL` | `1` to enable | Enables OpenClaw conversation diagnostics export through the `diagnostics-otel` plugin. Disabled by default. |
| `NEMOCLAW_OPENCLAW_OTEL_ENDPOINT` | OTLP/HTTP URL | Sets the OpenTelemetry collector endpoint for OpenClaw diagnostics. Defaults to `http://host.openshell.internal:4318` when `NEMOCLAW_OPENCLAW_OTEL=1`. |
| `NEMOCLAW_OPENCLAW_OTEL_SERVICE_NAME` | service name | Sets the OTEL `service.name` for OpenClaw gateway spans. Defaults to `openclaw-gateway`. |
| `NEMOCLAW_OPENCLAW_OTEL_SAMPLE_RATE` | `0.0` to `1.0` | Sets OpenClaw's root-span sample rate for conversation diagnostics. Defaults to `1.0`. |
</AgentOnly>
| `NEMOCLAW_OPENSHELL_BIN` | path | Overrides the `openshell` binary the CLI invokes. Defaults to `openshell` (resolved via `PATH`). |
| `NEMOCLAW_SANDBOX_NAME` | sandbox name | Preferred environment override for the default sandbox. Used by onboarding defaults and host-level commands such as `list`, `status`, `tunnel`, `services`, and `debug`. |
| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. |
| `SANDBOX_NAME` | sandbox name | Compatibility spelling used after `NEMOCLAW_SANDBOX_NAME` and `NEMOCLAW_SANDBOX`. |
| `NEMOCLAW_INSTALL_REF` | git ref | For internal installer commands: the git ref to install from. A nonempty value takes precedence over `NEMOCLAW_INSTALL_TAG`. Overridden by the `--install-ref` flag. |
| `NEMOCLAW_INSTALL_TAG` | release tag | For internal installer commands: the release tag to install when `NEMOCLAW_INSTALL_REF` is unset or empty. Defaults to the admin-promoted `lkg` tag when unset. Overridden by the `--install-tag` flag. |
| `NEMOCLAW_ENABLE_LOCAL_MODEL_PROFILE` | `1` to enable | Enables the fixed vLLM local model profile. Requires `NEMOCLAW_LOCAL_MODEL_RUNTIME=vllm`. Direct `$$nemoclaw onboard` use also requires `NEMOCLAW_NON_INTERACTIVE=1`. The hosted installer makes onboarding non-interactive, disables Express selection, and sets this value automatically when it receives `--local-model-runtime=vllm`. |
| `NEMOCLAW_LOCAL_MODEL_RUNTIME` | `vllm` | Selects the fixed vLLM local model profile. Requires `NEMOCLAW_ENABLE_LOCAL_MODEL_PROFILE=1`; direct onboarding also requires `NEMOCLAW_NON_INTERACTIVE=1`. The hosted installer sets this value from `--local-model-runtime=vllm`. |
| `NEMOCLAW_VLLM_MODEL` | registry slug or Hugging Face model ID | Selects the model the managed-vLLM install path serves and remains authoritative during DGX Station installer setup. Recognized slugs: `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `muse-glimmer-30b`, `nemotron-3-nano-4b`, `deepseek-v4-flash`, `nemotron-3-ultra-550b-a55b`, `deepseek-r1-distill-70b`. The `muse-glimmer-30b` profile remains Experimental after bounded verification of its pinned post-merge runtime image on one physical DGX Spark. NemoClaw does not enable vision or DFlash speculative decoding for this profile. Station Express selects `nemotron-3-ultra-550b-a55b`; a qualified reciprocal pair uses the distributed topology, while no qualifying pair retains the single-Station Ultra topology. Outside Station Express, unset uses the per-platform profile default. Gated models (for example, `deepseek-r1-distill-70b`) require `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`. |
| `NEMOCLAW_DGX_STATION_PEER` | SSH host or `user@host` | Selects one exact, already-trusted DGX Station peer for Nemotron 3 Ultra pair qualification. The peer must match the reciprocal private `/30` rail and hardware checks; an explicit peer failure stops setup instead of falling back. NemoClaw does not enroll SSH trust or accept a port or SSH option in this value. When unset, DGX Station installer discovery checks only the two deterministic `/30` counterpart addresses. A peer cannot be combined with an explicit non-Ultra model; conflicting explicit selections fail before pair preparation. |
| `NEMOCLAW_DGX_STATION_SSH_BINDING` | opaque installer-managed token | Carries the qualified peer endpoint and host-key binding from DGX Station pair preparation into the current managed-vLLM install. The installer creates and clears this token; operators should not set or persist it. Missing, changed, or mismatched binding state fails before peer SSH or Docker work. |
| `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` | JSON array of non-blank strings | Appends advanced operator-owned tokens to the managed `vllm serve` command after NemoClaw's registry defaults. Example: `["--max-num-seqs","2"]`. Malformed JSON, non-string tokens, or blank tokens fail before Docker work starts. |
<AgentOnly variant="openclaw">
| `NEMOCLAW_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; refer to [Understand Runtime Changes](../manage-sandboxes/configure-sandboxes/understand-runtime-changes). |
</AgentOnly>
| `NEMOCLAW_MODEL_ROUTER_PYTHON` | absolute path | Pins the host Python interpreter used to create the Model Router virtual environment. Strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to another python. Relative command names such as `python3.12` are rejected. When unset, NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, retains every interpreter whose version is in `[3.10, 3.14)` and whose `ensurepip`, `pyexpat`, `ssl`, and `venv` stdlib modules import cleanly, and tries `python -m venv` on each in priority order until one succeeds. Set the pin when the auto-discovered interpreter is broken (for example, Homebrew `python@3.14` with a `pyexpat` dlopen mismatch on macOS). |

<AgentOnly variant="openclaw">

OpenClaw-specific onboarding configuration:

| Variable | Format | Effect |
|----------|--------|--------|
| `NEMOCLAW_WEB_SEARCH_PROVIDER` | `brave`, `tavily`, or `none` | Selects Brave Search or Tavily Search in non-interactive onboarding, or disables web search explicitly. When unset, `BRAVE_API_KEY` implicitly selects Brave before `TAVILY_API_KEY` can implicitly select Tavily. |
| `BRAVE_API_KEY` | Brave Search API key | Supplies and implicitly selects Brave Search when no web search provider is set. NemoClaw validates the key and stores it in OpenShell rather than the sandbox. |
| `TAVILY_API_KEY` | Tavily Search API key | Supplies and implicitly selects Tavily Search when no provider is set and no Brave key is available. NemoClaw validates the key and stores it in OpenShell rather than the sandbox. |
| `NEMOCLAW_AGENT_TIMEOUT` | positive integer (seconds) | Build-time setting that overrides `agents.defaults.timeoutSeconds` and `models.providers.<provider-id>.timeoutSeconds` in the built OpenClaw config. Set it before onboarding builds the sandbox image. Setting it only for a later `$$nemoclaw <name> agent` invocation does not change the existing image. Raise for slow inference. |
| `NEMOCLAW_MCP_SHADOW_DIAGNOSTICS` | literal `1` to enable | Forwards opt-in successful Streamable HTTP MCP timing diagnostics to a newly created or rebuilt OpenClaw sandbox. It does not change timeouts, retries, requests, or responses. Unset it and rebuild after evidence collection to restore failure-only logging. Other values are ignored. |
| `NEMOCLAW_AUTO_PAIR_SLOW_INTERVAL_SECS` | positive number of seconds | Sets the post-pairing poll cadence for the in-sandbox OpenClaw auto-pair watcher. Defaults to `5` so late allowlisted CLI and browser scope upgrades are approved before clients time out. Raise only on load-sensitive gateways. |
| `NEMOCLAW_AUTO_PAIR_FAST_REENTRY_POLLS` | positive integer | Sets how many fast polls run after the watcher observes a fresh allowlisted scope-upgrade request. Defaults to `5`; set lower only when you need to reduce gateway polling. |
| `NEMOCLAW_AUTO_PAIR_FAST_REENTRY_INTERVAL_SECS` | positive number of seconds | Sets the fast-reentry interval after a fresh allowlisted scope-upgrade request. Defaults to `1`. |
| `NEMOCLAW_CONTEXT_WINDOW` | positive integer (tokens) | Overrides the model's context-window value in the built OpenClaw config. |
| `NEMOCLAW_MAX_TOKENS` | positive integer (tokens) | Overrides the model's `maxTokens` in the built OpenClaw config. |
| `NEMOCLAW_REASONING` | `true` or `false` | Overrides the model's reasoning-mode flag in the built OpenClaw config. |
| `NEMOCLAW_REASONING_EFFORT` | `low`, `medium`, `high`, or `default` | Applies only to the `compatible-endpoint` provider with the `openai-completions` API. A `low`, `medium`, or `high` value writes `params.extra_body.reasoning_effort`; unset or `default` leaves the endpoint's own default in place. Onboarding parses every explicit value before provider effects and rejects an invalid value or provider/API mismatch before route, policy, sandbox, or registry mutation. During `inference set`, NemoClaw rejects every explicit value, including `default`, before mutation unless the resulting route is compatible. Without an explicit effort input, switching to another provider or API family clears a recorded effort. An ordinary restart preserves the persisted runtime state instead of replaying the image's original value. |
| `NEMOCLAW_AGENT_HEARTBEAT_EVERY` | duration with `s`, `m`, or `h` suffix (for example `30m`, `1h`, or `0m`) | Overrides `agents.defaults.heartbeat.every` in the built OpenClaw config. Set `0m` to disable periodic agent turns. |
| `NEMOCLAW_EXTRA_AGENTS_JSON` | JSON array of OpenClaw secondary-agent entries | Adds secondary agents to `agents.list`. Refer to [Extra OpenClaw agents](#extra-openclaw-agents) for the entry schema, path constraints, and validation rules. |

</AgentOnly>
<AgentOnly variant="hermes">

Hermes-specific onboarding configuration:

| Variable | Format | Effect |
|----------|--------|--------|
| `NEMOCLAW_WEB_SEARCH_PROVIDER` | `tavily` or `none` | Selects Tavily Search in non-interactive onboarding or disables web search explicitly. When unset, `TAVILY_API_KEY` implicitly selects Tavily. |
| `TAVILY_API_KEY` | Tavily Search API key | Supplies and implicitly selects Tavily Search when no web search provider is set. NemoClaw validates the key and stores it in OpenShell rather than the sandbox. |
| `NEMOCLAW_HERMES_AUTH_METHOD` | `oauth` | Selects Hermes Provider authentication in non-interactive onboarding. Valid values: `oauth`, `nous-portal-oauth`, `api-key`, `nous-api-key`. |
| `NEMOCLAW_HERMES_AUTH` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Back-compatible alias for Hermes Provider authentication selection. |
| `NEMOCLAW_NOUS_AUTH_METHOD` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Nous-specific alias for Hermes Provider authentication selection. |
| `NEMOCLAW_HERMES_TOOL_GATEWAYS` | comma-separated list | Selects managed Hermes tool gateways in non-interactive onboarding. Valid values are `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`; the `nous-` prefix is optional. Unknown values fail before sandbox creation. |
| `NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS` | comma-separated list | Back-compatible alias for `NEMOCLAW_HERMES_TOOL_GATEWAYS`. |
| `NEMOCLAW_CONTEXT_WINDOW` | positive integer, at least `64000` tokens | Overrides `model.context_length` in the built Hermes config. Fresh and resumed Local Ollama onboarding, including sandbox rebuilds, must verify a loaded runtime context at least as large as this value. |
| `NEMOCLAW_EXTRA_PLACEHOLDER_KEYS` | whitespace- or comma-separated list of upper-snake env keys | Adds operator-supplied OpenShell provider rows so per-profile credentials such as `TELEGRAM_BOT_TOKEN_AGENT_A` flow through the same out-of-process placeholder injection that the canonical channel tokens use, instead of being baked into each Hermes profile `.env` as raw text. Refer to [Extra placeholder keys](#extra-placeholder-keys) for the entry shape and validation rules. |

</AgentOnly>

<AgentOnly variant="hermes">

#### Extra placeholder keys

Set `NEMOCLAW_EXTRA_PLACEHOLDER_KEYS` before running `$$nemoclaw onboard` when one container hosts multiple Hermes profiles and each profile needs its own messaging-bridge credential.

```bash
export NEMOCLAW_EXTRA_PLACEHOLDER_KEYS="TELEGRAM_BOT_TOKEN_AGENT_A TELEGRAM_BOT_TOKEN_AGENT_B"
export TELEGRAM_BOT_TOKEN_AGENT_A=<bot-A-token>
export TELEGRAM_BOT_TOKEN_AGENT_B=<bot-B-token>
$$nemoclaw onboard --agent hermes
```

For each entry, NemoClaw registers a generic OpenShell provider row that resolves the named env to its operator-supplied value at egress time.
The Hermes profile `.env` files are operator-owned: write `${TELEGRAM_BOT_TOKEN_AGENT_A}` (or the matching placeholder for each entry) into the per-profile `.env` so the in-sandbox Hermes process inherits the OpenShell placeholder instead of a raw token.
NemoClaw never reads, writes, or rewrites these `.env` files; verify after onboarding that each profile's `.env` references the placeholder and that no raw bot token value sits on disk.

Entries are split on whitespace and commas and must match `^[A-Z][A-Z0-9_]{0,127}$`.
Each entry must extend a canonical channel envKey with a non-empty `_<suffix>` (for example `TELEGRAM_BOT_TOKEN_AGENT_A`); the canonical envKeys are `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN`, `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`, `WECHAT_BOT_TOKEN`, `BRAVE_API_KEY`, and `TAVILY_API_KEY`.
Bare canonical envKeys, the control env itself, and arbitrary host secret names (`GITHUB_TOKEN`, `AWS_SECRET_ACCESS_KEY`, `KUBECONFIG`, and similar) are refused so they cannot leak into the sandbox provider gateway.
Duplicates are dropped silently.
The list is capped at 32 entries per sandbox.
Offending tokens emit one warning each and are skipped.

If a referenced env is unset at onboard time, the matching provider row is registered with a null token; the `upsertMessagingProviders` helper then skips the row, so no placeholder is attached to the OpenShell gateway and no Hermes profile can resolve it.
Export the credential before running `$$nemoclaw onboard` for that profile.

</AgentOnly>

<AgentOnly variant="openclaw">

#### Extra OpenClaw agents

Set `NEMOCLAW_EXTRA_AGENTS_JSON` to either a JSON array of secondary-agent entries, or an object payload of the form `{"agents": [...], "defaults": {...}, "main": {...}}`, to bake them into `agents.list[]` at image build time.
Each entry must declare `id` and `tools`; `workspace`, `agentDir`, `subagents`, `description`, and `model` are optional.
The generator always writes the canonical `main` entry first with `default: true`, so secondary agents cannot displace the primary agent.
Malformed JSON or invalid entries fail the image build with a structured error.

Field rules:

- `id` must match `^[a-z][a-z0-9_-]{0,31}$` and must not be `main`.
- `workspace` defaults to `/sandbox/.openclaw/workspace-<id>`; when set, it must be an absolute path that resolves to that value.
- `agentDir` defaults to `/sandbox/.openclaw/agents/<id>`; when set, it must be an absolute path that resolves to that value.
- `tools` must declare a non-empty `allow[]` or `deny[]`; nothing is implicitly granted.
- `model`, when set, must be a `"provider/model"` string whose provider portion matches the primary onboard provider.
- `default: true` is rejected because the primary agent is the only default.
- Allowed entry fields: `id`, `workspace`, `agentDir`, `tools`, `subagents`, `description`, `model`. Any other key fails the image build (no implicit credential or env pass-through).
- Allowed `tools` fields: `profile`, `allow`, `deny`. Allowed per-agent `subagents` fields: `delegationMode`, `allowAgents`, `model`, `thinking`, `requireAgentId`. Any other nested key fails the image build.

OpenClaw accepts `subagents.maxSpawnDepth` only on `agents.defaults.subagents`, never inside a per-agent `subagents` object.
The value must be an integer between `1` and `5` (OpenClaw's accepted range); to set it, use the object payload shape and pass it under `defaults`:

```json
{
  "agents": [
    {
      "id": "research",
      "tools": {
        "profile": "minimal",
        "allow": ["web_search", "web_fetch", "read", "write"],
        "deny": ["exec", "gateway"]
      }
    }
  ],
  "defaults": {
    "subagents": { "maxSpawnDepth": 1 }
  }
}
```

Array-shape example (paths defaulted):

```json
[
  {
    "id": "research",
    "tools": {
      "profile": "minimal",
      "allow": ["web_search", "web_fetch", "read", "write"],
      "deny": ["exec", "gateway"]
    }
  }
]
```

</AgentOnly>

#### Linux Ollama install mode details

Set `NEMOCLAW_OLLAMA_INSTALL_MODE=system` to run the official `https://ollama.com/install.sh` installer, which uses sudo, writes to `/usr/local`, and configures systemd.
Set `NEMOCLAW_OLLAMA_INSTALL_MODE=user` to extract the release tarball to `${HOME}/.local` without sudo and launch the daemon manually without systemd persistence.
Leave `NEMOCLAW_OLLAMA_INSTALL_MODE` empty or unset to let NemoClaw auto-detect the mode.
Auto-detection selects `system` when the current user is root or passwordless `sudo` works.
Auto-detection selects `user` in non-interactive runs without passwordless `sudo`.
An interactive shell falls back to `system` so the official installer can prompt for the password.
NemoClaw rejects any other value.
On upgrades, NemoClaw rejects `user` because a user-local install cannot replace the system daemon on `:11434`.
On upgrades, NemoClaw also rejects `system` under `NEMOCLAW_NON_INTERACTIVE=1` when passwordless `sudo` is unavailable because the installer would hang on a hidden sudo prompt.
The run exits with an actionable diagnostic instead.

### Onboarding Behavior Flags

The following flags toggle optional behaviors during onboarding.
Set them before running `$$nemoclaw onboard`.

| Variable | Format | Effect |
|----------|--------|--------|
| `NEMOCLAW_YES` | `1` to enable | Auto-accepts confirmation prompts (`--yes` equivalent) including in helpers like the Ollama proxy auth setup, but does not change managed-vLLM storage-warning handling. Express and other non-interactive setup stop after a verified insufficient-capacity warning, interactive setup still requires an explicit `y` or `yes`, and an inconclusive model-cache check stops non-interactive setup with guidance to rerun interactively. |
| `NEMOCLAW_OLLAMA_NO_AUTOSTART` | `1` to enable | Skips the wizard's eager Ollama auto-start during inference-provider selection (equivalent to passing `--no-ollama-autostart`). When set and Ollama is not running on `localhost:11434`, an agent that uses the legacy `16384`-token context floor, currently OpenClaw, prints a warning and selects the default fallback model instead of spawning `ollama serve`. An agent that requires a larger verified runtime context, currently Hermes at `64000` tokens, returns to interactive provider selection or exits when the Ollama provider is pinned or onboarding is non-interactive. The flag covers only the provider-selection step; later setup steps (auth proxy, validation, model warm) still expect a reachable Ollama. On Linux hosts with a systemd Ollama unit, the loopback-override path may still restart the daemon before this gate runs. |
| `NEMOCLAW_NON_INTERACTIVE_SUDO_MODE` | `prompt` or empty/unset | When set to `prompt`, allows non-interactive onboarding to use prompt-capable `sudo` for host setup steps that require elevation, which can ask for a password. Empty/unset is the default and uses `sudo -n`, which fails instead of asking for a password. Any other value is rejected. |
| `NEMOCLAW_NO_EXPRESS` | `1` to enable | Installer-only. Skips the DGX Spark, DGX Station, and Windows WSL express prompt, then continues with the normal interactive onboarding flow. On N1x, setting this variable alone stops installation before onboarding. Combine it with `NEMOCLAW_PROVIDER=install-vllm` only when you intend to bypass the preview prompt with explicit Deferred managed-vLLM intent. |
| `NEMOCLAW_EXPERIMENTAL` | `1` to enable | Surfaces experimental providers and flows in onboarding. |
| `NEMOCLAW_IGNORE_RUNTIME_RESOURCES` | `1` to enable | Suppresses the under-provisioned runtime warning during preflight. Use only when you know the sandbox host meets the minimums. |
| `NEMOCLAW_DISABLE_OVERLAY_FIX` | `1` to enable | Skips the Docker overlay-fix step during sandbox build. For environments where the fix is incompatible. |
| `NEMOCLAW_OVERLAY_SNAPSHOTTER` | snapshotter name | Selects the containerd overlay snapshotter for sandbox builds. Empty (default) preserves containerd's choice. |
<AgentOnly variant="openclaw,hermes">
| `NEMOCLAW_SKIP_TELEGRAM_REACHABILITY` | `1` to enable | Skips the Telegram bot reachability probe during onboard (useful in restricted networks). |
| `NEMOCLAW_SKIP_SLACK_AUTH_VALIDATION` | `1`, `true`, `yes`, or `on` to enable | Skips the live Slack `auth.test` and `apps.connections.open` credential probes during onboard and `channels add slack`. Use only in restricted networks or hermetic test environments; Slack token format checks still apply. |
</AgentOnly>
| `NEMOCLAW_RESOURCE_PROFILE` | profile name or `default` | Selects a sandbox CPU/RAM resource profile from the blueprint during onboarding. `default` means no resource preference, so NemoClaw passes no OpenShell CPU or memory flags. Unknown names fail fast. |
| `NEMOCLAW_CPU` | percentage or Kubernetes CPU quantity | Overrides the selected profile's CPU size passed to OpenShell `--cpu`. Percentages resolve against detected capacity. |
| `NEMOCLAW_RAM` | percentage or Kubernetes memory quantity | Overrides the selected profile's memory size passed to OpenShell `--memory`. Percentages resolve against detected capacity. |
| `NEMOCLAW_SANDBOX_GPU` | `auto`, `1`, or `0` | Controls sandbox GPU passthrough during onboarding. `auto` enables GPU passthrough when an NVIDIA GPU is detected, `1` requires GPU passthrough, and `0` forces CPU-only sandbox creation. |
| `NEMOCLAW_SANDBOX_GPU_DEVICE` | OpenShell GPU device selector | Selects the GPU device passed with `openshell sandbox create --gpu-device`. Requires explicit sandbox GPU enablement with `NEMOCLAW_SANDBOX_GPU=1` (or `--sandbox-gpu` for CLI-driven onboarding); otherwise onboarding rejects the selector instead of treating it as an implicit opt-in. |
| `NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH` | `1`, `true`, `yes`, or `on` to enable | Bypasses recorded sandbox base-image resolution metadata during onboarding, recreation, and rebuild. NemoClaw reruns candidate resolution but can still use a compatible image from Docker's local image store. Versioned release candidates that exist locally but fail validation are refreshed from the registry once during normal resolution. This setting does not discard onboarding session state. |
| `NEMOCLAW_SANDBOX_BASE_LOCAL_BUILD` | unset or `auto` (default); `1`, `true`, `yes`, or `on` to enable; `0`, `false`, `no`, or `off` to disable | Controls whether base-image resolution may build a compatible image locally. The default allows builds during normal CLI runs and disables them when `NODE_ENV=test` or `VITEST=true`. When source inputs or a missing/incompatible release-version base require a fresh build, disabling local builds makes resolution fail instead of using an unproven image. |
| `NEMOCLAW_DOCKER_GPU_PATCH` | unset, `auto`, `fallback`, `1`, or `0`; other legacy nonzero values remain accepted through `v0.0.x` and will be removed in `v0.1.0` | Selects Linux Docker-driver GPU routing. Unset, `auto`, or `0` uses native OpenShell GPU injection on ordinary native Linux. `fallback` explicitly opts into one native attempt followed by one bounded compatibility retry when trusted host evidence identifies a GPU-routing failure. `1` and legacy nonzero values select the compatibility patch from the outset. Docker Desktop WSL and Jetson/Tegra use the compatibility path by default; Docker Desktop WSL ignores `0`, while Jetson/Tegra accepts `0` only as a troubleshooting override that bypasses device-group propagation. Portable OpenClaw onboarding requires native OpenShell GPU injection and does not use this setting. |
| `NEMOCLAW_OPENSHELL_GATEWAY_CONTAINER_PATCH` | `1` to enable; disabled by default | This setting explicitly opts into the Linux gateway compatibility container for an older host ABI or a diagnostic run; use it only on a trusted local host because it uses host networking and mounts the Docker socket read-only even though the socket still exposes the privileged Docker API; prefer OpenShell 0.0.101's directly supported glibc 2.39+ path; see [Gateway Compatibility Container](/user-guide/openclaw/security/security-controls/gateway-authentication-controls#gateway-compatibility-container) for the container boundary and removal conditions. |
| `NEMOCLAW_OPENSHELL_GATEWAY_BIN` | path | Advanced override for the `openshell-gateway` binary used by Linux Docker-driver startup. For the default port, the installer accepts the binary under an absolute `XDG_BIN_HOME` when set, otherwise `~/.local/bin/openshell-gateway`; it also accepts `/usr/local/bin/openshell-gateway` or `/usr/bin/openshell-gateway`. Another path fails service staging. The macOS Homebrew service uses the formula's binary. Defaults to the binary next to `openshell`, then common install paths. |
| `NEMOCLAW_OPENSHELL_SANDBOX_BIN` | path | Advanced override for the `openshell-sandbox` binary used by Linux Docker-driver startup. The macOS Homebrew service uses the formula's driver layout. Defaults to the binary next to `openshell`, then common install paths. |
| `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR` | path | Advanced override for the Linux Docker-driver gateway SQLite state directory and standalone-fallback PID file. Defaults to `~/.local/state/nemoclaw/openshell-docker-gateway`. |
| `NEMOCLAW_AUTO_FIX_FIREWALL` | `1` to enable | Opts in to automatic UFW remediation when Linux Docker-driver sandbox containers cannot reach the host gateway after a proven TCP failure. NemoClaw runs `sudo -n` only, validates the narrow Docker bridge subnet → gateway IP:port rule before invoking UFW, re-probes after applying it, and otherwise falls back to the printed manual command. |
<AgentOnly variant="openclaw,hermes">
| `NEMOCLAW_WECHAT_QUIET` | `1` to enable | Silences the `[wechat]` diagnostic lines printed during the host-side WeChat QR login (poll status, IDC redirects, swallowed gateway errors), which are visible by default while the experimental WeChat path stabilizes; set `1` once the flow is reliable in your environment. |
</AgentOnly>

<AgentOnly variant="openclaw">

Set `NEMOCLAW_SANDBOX_BASE_IMAGE_REF` to an OpenClaw sandbox-base tag or digest to override base-image resolution during onboarding.
Remote overrides must use the official NVIDIA sandbox-base repository and resolve to a repository digest.
NemoClaw accepts local bases only when it builds and pins them during onboarding; a local image reference supplied through this environment variable is rejected because it has no trusted build capability.

</AgentOnly>

<AgentOnly variant="deepagents">

Set `NEMOCLAW_LANGCHAIN_DEEPAGENTS_CODE_SANDBOX_BASE_IMAGE_REF` to a LangChain Deep Agents Code sandbox-base tag or digest to override base-image resolution during onboarding.
NemoClaw requires environment overrides to use the official remote repository and resolve to a repository digest, then validates the requested image against the manifest-required `deepagents-code` package version before using it.
NemoClaw accepts local bases only when it builds and pins them during onboarding.

</AgentOnly>

<AgentOnly variant="hermes">

Set `NEMOCLAW_HERMES_SANDBOX_BASE_IMAGE_REF` to a Hermes sandbox-base tag or digest to override base-image resolution during onboarding.
NemoClaw requires environment overrides to use the official remote repository and resolve to a repository digest, validates the requested image for the required MCP runtime, and keeps the final image bound to that trusted base.
NemoClaw accepts local bases only when it builds and pins them during onboarding.

</AgentOnly>

### Onboard Profiling Traces

Set `NEMOCLAW_TRACE=1` before `$$nemoclaw onboard` to write an OpenTelemetry-style JSON trace for the run.
If you do not set a trace path, NemoClaw writes a timestamped file under `.e2e/traces/` in the current working directory.
Use `NEMOCLAW_TRACE_DIR` to choose the output directory, or `NEMOCLAW_TRACE_FILE` to choose the output file.

```bash
NEMOCLAW_TRACE=1 $$nemoclaw onboard
NEMOCLAW_TRACE_DIR=/tmp/nemoclaw-traces $$nemoclaw onboard
NEMOCLAW_TRACE_FILE=/tmp/nemoclaw-onboard-trace.json $$nemoclaw onboard
```

Trace artifacts include onboard phase timing, sandbox and service readiness waits, policy application, inference validation probes, curl probe results, and sandbox build progress events.
Secret-like metadata such as API keys, bearer tokens, cookies, and credentials is redacted before the file is written.

<AgentOnly variant="deepagents">

### Deep Agents Code OTLP Traces

Pass `--observability` during Deep Agents onboarding to enable backend-neutral runtime traces for Deep Agents Code.
This feature is separate from `NEMOCLAW_TRACE`, which records NemoClaw onboarding phases, and from the OpenClaw diagnostics plugin.

The sandbox sends OTLP/HTTP protobuf requests only to `http://host.openshell.internal:4318/v1/traces`.
The managed exporter uses standard OTLP transport headers but does not accept operator-supplied custom or authentication headers.
A host operator must run the receiver on port `4318` and configure any Jaeger, Phoenix, LangSmith, or other backend exporter on the collector side.
Changing the host collector's exporter does not require a sandbox rebuild or policy change.
Collector and exporter failures are non-fatal to agent work.

Native LangSmith tracing and ambient OTLP configuration remain disabled in the sandbox.
The explicit opt-in can export bounded prompts, responses, tool arguments, tool results, and operational metadata, so operators must treat trace payloads as sensitive application data.
The collector must enforce the operator's filtering and redaction requirements before remote forwarding because the local policy applies to the managed Python interpreter and does not provide authenticated tenant identity.
For a runnable LangSmith collector setup, refer to [Set Up Deep Agents Trace Export](/user-guide/deepagents/monitoring/set-up-deepagents-trace-export).
For the receiver trust contract, refer to [Understand Deep Agents Trace Export](/user-guide/deepagents/monitoring/understand-deepagents-trace-export).

</AgentOnly>

<AgentOnly variant="openclaw">

### OpenClaw Conversation OTEL Diagnostics

Set `NEMOCLAW_OPENCLAW_OTEL=1` before onboarding or rebuilding an OpenClaw sandbox to enable runtime conversation traces through OpenClaw's `diagnostics-otel` plugin.
This is separate from `NEMOCLAW_TRACE`, which records NemoClaw onboarding phases to a local JSON file.
NemoClaw configures OpenClaw for OTLP/HTTP protobuf traces only by default: metrics and logs are disabled, and prompt/tool content capture is not enabled.

For a local Jaeger collector:

```bash
docker run --rm --name nemoclaw-jaeger \
    -e COLLECTOR_OTLP_ENABLED=true \
    -p 16686:16686 \
    -p 4318:4318 \
    jaegertracing/all-in-one:1.57
NEMOCLAW_OPENCLAW_OTEL=1 $$nemoclaw onboard
```

Onboarding automatically applies the `openclaw-diagnostics-otel-local` preset at sandbox create and again during the policy step when `NEMOCLAW_OPENCLAW_OTEL=1`, so OTLP export is allowed before the gateway's first trace flush.
If you enabled OTEL after an existing sandbox was created, run `$$nemoclaw <sandbox-name> policy add openclaw-diagnostics-otel-local --yes` or recreate the sandbox with OTEL enabled at build time.

Then open `http://localhost:16686` and select the `openclaw-gateway` service.
The built-in `openclaw-diagnostics-otel-local` preset allows only `POST /v1/traces` (and subpaths) to `host.openshell.internal:4318` from `openclaw` and `node`.
For a remote collector, create a custom preset for the collector host and port instead of using the local host-gateway preset.

### OpenClaw MCP Tool Discovery Timeout

Set `NEMOCLAW_MCP_TOOLS_LIST_TIMEOUT_MS` before onboarding or rebuilding an OpenClaw sandbox to override its `tools/list` timeout.
The setting accepts an integer from `1500` through `10000` milliseconds.
When unset or blank, NemoClaw adds no override; OpenClaw uses a server-specific request timeout when configured and otherwise uses its 1,500 ms fallback.
The override applies to catalog `tools/list` requests for every MCP server in that sandbox and takes precedence over a server-specific request timeout.
It does not change connection timeouts or the separate MCP tool-call request timeout, which defaults to 60,000 ms.
NemoClaw rejects an invalid value before the sandbox create step, including the replacement create step during rebuild.

For an existing sandbox, apply a 3,000 ms timeout:

```bash
export NEMOCLAW_MCP_TOOLS_LIST_TIMEOUT_MS=3000
$$nemoclaw <sandbox> rebuild
```

OpenClaw writes `mcp_tools_list_timeout_override_ms=3000` when the MCP runtime loads.
Refer to [Troubleshoot MCP Servers](troubleshoot-mcp-servers#adjust-the-tool-discovery-timeout) for the incremental test and rollback procedure.

</AgentOnly>

### Probe Timeouts

The following variables tune how long internal probes wait before giving up.
Defaults are sized for typical hardware; override only if you see false-positive timeouts.

| Variable | Default | Effect |
|----------|---------|--------|
| `NEMOCLAW_MCP_PROVIDER_SYNC_TIMEOUT_SECONDS` | `30` | Maximum time to wait for an OpenShell MCP provider credential revision to become active or fully revoked inside the sandbox. Integer seconds; raise only when provider synchronization is unusually slow. |
| `NEMOCLAW_PORTABLE_PODMAN_STARTUP_TIMEOUT_MS` | `60000` | Maximum cold-start time for portable rootless Podman socket activation and the first real API response. Set an integer from `15000` through `300000` milliseconds. This setting does not change the fixed 10,000 ms steady-state API deadline. |
| `NEMOCLAW_SANDBOX_EXEC_TIMEOUT_MS` | per call site (typically `15000`) | Overrides the default timeout for `openshell sandbox exec` calls issued by recovery and lifecycle helpers. Integer milliseconds; non-positive or non-numeric values fall back to the per-call-site default. |
| `NEMOCLAW_STATUS_PROBE_TIMEOUT_MS` | built-in default | Overrides the timeout for the OpenShell status probe used by `$$nemoclaw <name> status`. Integer milliseconds; non-positive or non-numeric values fall back to the default. |
| `NEMOCLAW_WSL_GPU_PROOF_TIMEOUT_MS` | `180000` | Maximum time for the bounded Docker CUDA workload on an eligible ARM64 Linux host. A positive finite number of milliseconds overrides the default. Invalid, infinite, zero, and negative values use the default. |

### Onboard and Sandbox Readiness Timeouts

The following environment variables tune onboard-time and recovery wall-clock limits.
Set the onboarding variables before running `$$nemoclaw onboard` if a slow connection or large model pull risks tripping the default.

| Variable | Default | Purpose |
|----------|---------|---------|
| `NEMOCLAW_OLLAMA_PULL_TIMEOUT` | `1800` (30 minutes) | Wall-clock timeout for `ollama pull` during onboard, in seconds. Accepts integer or float values. Already-downloaded layers are kept; re-running the pull resumes them. |
| `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` | `180` | Wall-clock timeout for the inference-server validation probe during onboard, in seconds. Raise on slow networks or for very large prompts. |
| `NEMOCLAW_SANDBOX_READY_TIMEOUT` | `180` | Wall-clock timeout for post-create readiness, in seconds. Raise the timeout when the sandbox image build, gateway upload, or in-sandbox boot exceeds the default (typical on 70B+ models, first-time gateway uploads over slow links, or DGX Station / remote-VM first runs). Ordinary onboarding deletes the partially created sandbox when the deadline expires and prints the retry hint. Portable OpenClaw onboarding instead preserves the sandbox when NemoClaw cannot verify its exact runtime identity. |
| `NEMOCLAW_SANDBOX_READY_ERROR_DEBOUNCE` | `30` | Consecutive `Error`-phase polls the post-create readiness wait tolerates before treating `Error` as terminal. Polling starts at 250ms and backs off to a 2-second cap, while `NEMOCLAW_SANDBOX_READY_TIMEOUT` remains the overall deadline. The gateway can briefly report a just-created sandbox in `Error` while it re-registers the sandbox (seen on DGX Spark); the debounce lets that transient recover to `Ready`. `Failed` and `CrashLoopBackOff` always fail immediately. Set to `1` to restore fast-fail on the first `Error` poll. |
| `NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS` | `30`, `90`, or `120`, depending on the recovery phase | Wall-clock timeout for OpenShell command re-registration after policy application, plus gateway health and re-registration during managed OpenClaw or Hermes recovery. A valid finite, nonnegative value overrides the internal budget for the current recovery phase. |

<AgentOnly variant="openclaw,hermes">

For newly created OpenClaw and Hermes sandboxes, `NEMOCLAW_SANDBOX_READY_TIMEOUT` also covers the durable sandbox ID and no-op command checks that follow the OpenShell `Ready` state.

</AgentOnly>

An unset, blank, invalid, or negative `NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS` value uses 30 seconds for OpenClaw gateway health and 90 seconds for Hermes gateway health.
Recreated-sandbox OpenShell registration uses 120 seconds when the recovery path does not supply another budget.

<AgentOnly variant="openclaw,hermes">

For managed recovery, `NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS` covers OpenShell re-registration before state restoration and replacement commit.
When the deadline expires, NemoClaw attempts to roll back the replacement and leaves the primary dashboard or API host forward stopped.

</AgentOnly>

```bash
export NEMOCLAW_OLLAMA_PULL_TIMEOUT=3600
export NEMOCLAW_SANDBOX_READY_TIMEOUT=600
$$nemoclaw onboard
```

<AgentOnly variant="openclaw,hermes">

Set the recovery override before a `start` or `recover` command that can recreate the sandbox.

```bash
export NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS=300
$$nemoclaw <sandbox-name> recover
```

</AgentOnly>

If the Ollama pull or post-create readiness timeout fires, onboarding emits the elapsed budget plus a hint to raise the relevant variable.
The Ollama pull preserves its partial download for the next attempt.
The ordinary post-create readiness wait deletes the orphaned sandbox first so the next `$$nemoclaw onboard` starts without that partially created sandbox.

<AgentOnly variant="openclaw">

For portable OpenClaw onboarding, NemoClaw instead leaves the sandbox in place when it cannot verify the exact runtime identity.
Inspect it with `openshell sandbox list` and `$$nemoclaw <name> status`, then follow the recovery guidance from `status`.

</AgentOnly>

A post-policy re-registration failure leaves the sandbox in place and reports that OpenShell did not re-register it.

### Lifecycle Behavior Flags

The following flags change defaults for commands that manage existing sandboxes.

| Variable | Format | Effect |
|----------|--------|--------|
| `NEMOCLAW_CLEANUP_GATEWAY` | `1`, `true`, or `yes` to enable; `0`, `false`, or `no` to disable | Overrides the platform default (macOS unattended: cleanup; Linux/Windows: preserve) for whether `$$nemoclaw <name> destroy` removes the shared gateway when destroying the last sandbox. Command-line `--cleanup-gateway` and `--no-cleanup-gateway` still take precedence. |
<AgentOnly variant="openclaw,hermes">
| `NEMOCLAW_CONFIG_ACCEPT_NEW_PATH` | Exactly `"1"` to opt in (`true`, `yes`, `on` are not accepted) | Allows `$$nemoclaw <name> config set` to write a dotpath that does not already exist in the sandbox config, without the interactive confirmation. Equivalent to passing `--config-accept-new-path`, and it takes precedence over `NEMOCLAW_NON_INTERACTIVE=1`. Without it, a run without a TTY refuses the write instead. |
</AgentOnly>
| `NEMOCLAW_CONFIRM_LEGACY_MANAGED_RECREATE` | Exact JSON array of sandbox names | Confirms to the installer that the exact listed set of pre-fingerprint OpenClaw or Hermes sandboxes used NemoClaw-managed images, allowing recovery onto the current managed image. The normalized names must exactly match the installer's printed array. Set it only after verifying every named sandbox. Recorded custom-image evidence remains blocked. |
| `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR` | `1` to enable | Skips automatic DNS-proxy mutation for stale `inference.local` routes during `$$nemoclaw <name> connect` and `$$nemoclaw <name> connect --probe-only`. The command still probes the route and exits non-zero when the provider-specific requirement fails. An `ollama-local` route still requires a healthy authenticated proxy and HTTP 2xx from `inference.local/v1/models`. Use only as a troubleshooting escape hatch. |
<AgentOnly variant="openclaw">
| `NEMOCLAW_PORTABLE_OLLAMA_REENROLL` | Exactly `1` for one recovery run | After you verify `${HOME}/.local/bin/ollama`, explicitly records that regular executable as NemoClaw-managed for a portable experimental-profile sandbox whose recorded provider is `ollama-local`. Use this once for a user-local Ollama that NemoClaw installed before ownership receipts existed. It never claims a system Ollama, symlink, non-executable file, or non-Ollama sandbox. |
</AgentOnly>
| `NEMOCLAW_DISABLE_SUPERVISOR_RELAUNCH` | `1` to enable | Skips the automatic trusted container recreation during `$$nemoclaw <name> recover` when two managed scans find no supervisor while PID 1 remains stable. Use only as a troubleshooting escape hatch; recovery then falls back to the rebuild or re-onboard guidance. |
| `NEMOCLAW_SHIELDS_ACCEPT_LEGACY_BASELINE` | `1` to opt in | Allows advanced immutable-config verification to trust the current on-disk bytes for older or partial content baselines. Use only after you have rebuilt or manually inspected the sandbox state and accepted that the baseline is operator-approved. |
| `NEMOCLAW_SHIELDS_SETTLE_MS` | milliseconds (default `750`, clamped to `0` to `10000`) | Settle window NemoClaw waits after re-applying a config lockdown (during shields auto-restore and `$$nemoclaw <name> shields up` drift remediation) before re-confirming the lock still holds. Detects when an in-sandbox reconciler changes config file permissions after lockdown and re-applies the lock; if NemoClaw cannot re-confirm the lock within the retry budget, shields stay down. This narrows the window in which a reconciler can revert permissions rather than eliminating it. The best-effort `chattr +i` immutable bit remains the only fully durable lock. Raise it on hosts where the gateway settles slowly. |
| `NEMOCLAW_SKIP_UNREACHABLE_SANDBOX_BACKUP` | Exactly `1` to opt in (`true`, `yes`, `0` are not accepted) | Applies to standalone `$$nemoclaw backup-all` runs. Skips running sandboxes whose in-sandbox SSH endpoint does not answer. It does not relax the installer's strict pre-upgrade backup, which still aborts if any registered sandbox is skipped or fails. Any uncommitted state since the last successful backup is not included in the skipped backup. |
| `NEMOCLAW_UNINSTALL_ALL_GATEWAY_PORTS` | `1` to opt in | Makes `$$nemoclaw uninstall` remove every gateway port on the host instead of only the port `NEMOCLAW_GATEWAY_PORT` selects. Equivalent to passing the `--all-gateway-ports` flag; the whole-host `Proceed?` confirmation still applies unless `--yes` is also passed. Each port runs as its own uninstall, and the variable is dropped from those runs so the sweep cannot re-enter itself. |
| `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA` | `1` to opt in | Acknowledges data loss during `$$nemoclaw uninstall` and removes the otherwise-preserved entries (`rebuild-backups/`, `backups/`, `sandboxes.json`) under `~/.nemoclaw/`. Removes installer-managed user-local CLI shims under `~/.local/bin/` only when sibling evidence is unidentified. When a confirmed sibling gateway port remains, those shared shims stay with the shared npm CLI package. Equivalent to passing the `--destroy-user-data` flag; the global `Proceed?` confirmation still applies unless `--yes` is also passed. |

<AgentOnly variant="openclaw">
### Deprecated Brev Deployment

The following variables configure the deprecated `$$nemoclaw deploy` compatibility command.
The maintained remote-server path does not use these variables.
For the current remote-server deployment path, refer to [Deploy to a Headless Server](../deployment/deploy-to-headless-server).

| Variable | Default | Effect |
|----------|---------|--------|
| `NEMOCLAW_BREV_PROVIDER` | `gcp` | Cloud provider for Brev instance creation. |
| `NEMOCLAW_GPU` | `a2-highgpu-1g:nvidia-tesla-a100:1` | GPU specification (instance type and GPU model) for the Brev instance. |
| `NEMOCLAW_DEPLOY_NO_CONNECT` | unset | When set to `1`, skips the automatic `connect` step after the remote deploy completes. |
| `NEMOCLAW_DEPLOY_NO_START_SERVICES` | unset | When set to `1`, skips starting services automatically after the remote deploy. |

</AgentOnly>

### Legacy `$$nemoclaw setup`

Deprecated. Use `$$nemoclaw onboard` instead.
Running `$$nemoclaw setup` now delegates directly to `$$nemoclaw onboard`.

```bash
$$nemoclaw setup
```