diff --git a/.github/workflows/managed-images.yaml b/.github/workflows/managed-images.yaml
index 5a63d35c2a5..a132a03ae01 100644
--- a/.github/workflows/managed-images.yaml
+++ b/.github/workflows/managed-images.yaml
@@ -37,6 +37,7 @@ on:
- "Dockerfile"
- "agents/**"
- "ci/npm-audit-exceptions.json"
+ - "ci/pi-agent-qualification-v1-*.json"
- "ci/reviewed-npm-audit.json"
- "nemoclaw/**"
- "nemoclaw-blueprint/**"
@@ -44,6 +45,7 @@ on:
- "src/lib/actions/sandbox/openshell-child-visible-credentials.v*.json"
- "src/lib/actions/sandbox/mcp-bridge-*.ts"
- "src/lib/actions/sandbox/rebuild-post-restore-phase.ts"
+ - "src/lib/agent/candidate-authority.ts"
- "src/lib/core/json-types.ts"
- "src/lib/core/ports.ts"
- "src/lib/messaging/**"
@@ -1212,11 +1214,12 @@ jobs:
pi-candidate:
name: Build and validate the Pi candidate managed image (${{ matrix.arch }})
- if: github.repository == 'NVIDIA/NemoClaw' && github.event_name == 'pull_request'
+ if: github.repository == 'NVIDIA/NemoClaw' && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
runs-on: ${{ matrix.runner }}
timeout-minutes: 120
permissions:
contents: read
+ packages: write
strategy: &pi_candidate_strategy
fail-fast: false
matrix:
@@ -1231,14 +1234,17 @@ jobs:
BASE_DOCKERFILE: agents/pi/Dockerfile.base
CANDIDATE_IMAGE: nemoclaw-managed-candidate/pi
DOCKERFILE: agents/pi/Dockerfile
- LOCAL_BASE_REFERENCE: nemoclaw-managed-candidate/pi-base:${{ github.sha }}
+ LOCAL_BASE_REFERENCE: nemoclaw-managed-candidate/pi-base:${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
PLATFORM: ${{ matrix.platform }}
PUBLICATION_COHORT: ghrun-${{ github.run_id }}-${{ github.run_attempt }}
REPOSITORY: ghcr.io/nvidia/nemoclaw/pi-sandbox
+ # Qualification receipts compare image sources with the PR head, never GitHub's synthetic merge.
+ SOURCE_REVISION: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
steps: &pi_candidate_steps
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
+ ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
persist-credentials: false
- name: Set up Docker Buildx
id: buildx
@@ -1300,10 +1306,10 @@ jobs:
build-contexts: nemoclaw-pi-base=oci-layout://${{ steps.base.outputs.oci }}
load: true
push: false
- tags: nemoclaw-managed-candidate/pi:${{ github.sha }}
+ tags: nemoclaw-managed-candidate/pi:${{ env.SOURCE_REVISION }}
labels: |
org.opencontainers.image.source=https://github.com/${{ github.repository }}
- org.opencontainers.image.revision=${{ github.sha }}
+ org.opencontainers.image.revision=${{ env.SOURCE_REVISION }}
io.nvidia.nemoclaw.agent=pi
io.nvidia.nemoclaw.managed-image.contract=1
io.nvidia.nemoclaw.managed-image.platform=${{ matrix.platform }}
@@ -1319,7 +1325,7 @@ jobs:
- name: Validate the Pi candidate runtime contract
shell: bash
env:
- IMAGE_REFERENCE: nemoclaw-managed-candidate/pi:${{ github.sha }}
+ IMAGE_REFERENCE: nemoclaw-managed-candidate/pi:${{ env.SOURCE_REVISION }}
run: |
set -euo pipefail
image_json="$(docker image inspect "$IMAGE_REFERENCE")"
@@ -1348,7 +1354,6 @@ jobs:
test -x /usr/local/bin/nemoclaw-managed-bootstrap
'
- name: Log in to GHCR
- if: github.event_name != 'pull_request'
uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
with:
registry: ${{ env.REGISTRY }}
@@ -1358,7 +1363,6 @@ jobs:
# consumer alias, so a published candidate stays reachable by digest alone.
- name: Publish the Pi candidate image by digest
id: publish
- if: github.event_name != 'pull_request'
uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
with:
builder: ${{ steps.buildx.outputs.name }}
@@ -1369,7 +1373,7 @@ jobs:
outputs: type=image,name=ghcr.io/nvidia/nemoclaw/pi-sandbox,push-by-digest=true,name-canonical=true,push=true
labels: |
org.opencontainers.image.source=https://github.com/${{ github.repository }}
- org.opencontainers.image.revision=${{ github.sha }}
+ org.opencontainers.image.revision=${{ env.SOURCE_REVISION }}
io.nvidia.nemoclaw.agent=pi
io.nvidia.nemoclaw.managed-image.contract=1
io.nvidia.nemoclaw.managed-image.platform=${{ matrix.platform }}
@@ -1382,11 +1386,14 @@ jobs:
NEMOCLAW_MANAGED_IMAGE_RUNTIME_USER=root
provenance: false
sbom: false
+ - name: Remove Pi publication credentials
+ if: always()
+ shell: bash
+ run: docker logout ghcr.io
# The publication above rebuilds the image rather than reusing the
# already-validated local one, so revalidate the exact published digest
# before the contract records it as the qualified candidate.
- name: Validate the published Pi candidate digest
- if: github.event_name != 'pull_request'
shell: bash
env:
DIGEST: ${{ steps.publish.outputs.digest }}
@@ -1433,8 +1440,8 @@ jobs:
'
# The checks above bypass /usr/local/bin/nemoclaw-start with a direct
# --entrypoint override, so they never prove the entrypoint itself runs
- # correctly. Start the local pull-request image or exact published digest
- # through its declared entrypoint with no command, matching a real launch,
+ # correctly. Start the published digest through its declared entrypoint
+ # with no command, matching a real launch,
# and prove PID 1 drops to the sandbox user, hardens its resource limits,
# and persists the trusted proxy environment before it holds the sandbox
# open.
@@ -1442,19 +1449,13 @@ jobs:
shell: bash
env:
DIGEST: ${{ steps.publish.outputs.digest }}
- EVENT_NAME: ${{ github.event_name }}
- IMAGE_REFERENCE: nemoclaw-managed-candidate/pi:${{ github.sha }}
run: |
set -euo pipefail
- if [ "$EVENT_NAME" = "pull_request" ]; then
- reference="$IMAGE_REFERENCE"
- else
- if [[ ! "$DIGEST" =~ ^sha256:[0-9a-f]{64}$ ]]; then
- echo "ERROR: the Pi candidate publication did not return an immutable digest." >&2
- exit 1
- fi
- reference="${REPOSITORY}@${DIGEST}"
+ if [[ ! "$DIGEST" =~ ^sha256:[0-9a-f]{64}$ ]]; then
+ echo "ERROR: the Pi candidate publication did not return an immutable digest." >&2
+ exit 1
fi
+ reference="${REPOSITORY}@${DIGEST}"
corporate_ca_dir="$(mktemp -d "$RUNNER_TEMP/pi-candidate-ca.XXXXXX")"
corporate_ca="$corporate_ca_dir/corporate-ca.pem"
openssl req -x509 -newkey rsa:2048 -nodes -days 1 \
@@ -1571,7 +1572,6 @@ jobs:
done
'
- name: Record the exact Pi candidate contract
- if: github.event_name != 'pull_request'
shell: bash
env:
DIGEST: ${{ steps.publish.outputs.digest }}
@@ -1590,7 +1590,7 @@ jobs:
--arg image "$REPOSITORY" \
--arg platform "$PLATFORM" \
--arg release "$release" \
- --arg revision "$GITHUB_SHA" \
+ --arg revision "$SOURCE_REVISION" \
--arg reference "${REPOSITORY}@${DIGEST}" \
'{
contractVersion: 1,
@@ -1615,7 +1615,6 @@ jobs:
# This candidate name is deliberately outside that pattern so a published
# Pi digest cannot enter the atomic release cohort.
- name: Upload the exact Pi candidate contract
- if: github.event_name != 'pull_request'
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: managed-candidate-contract-${{ github.run_id }}-${{ github.run_attempt }}-pi-${{ matrix.arch }}
diff --git a/ci/cli-test-timing-hints.json b/ci/cli-test-timing-hints.json
index 51cbdac4e44..1f990e85f50 100644
--- a/ci/cli-test-timing-hints.json
+++ b/ci/cli-test-timing-hints.json
@@ -158,8 +158,6 @@
"test/mcp/mcp-add-crash-consistency.test.ts": 43147,
"test/mcp/mcp-bridge-destroy-marker-recovery.test.ts": 14345,
"test/mcp/mcp-bridge-servers.test.ts": 15199,
- "test/mcp/mcp-policy-key-ownership.test.ts": 9878,
- "test/mcp/mcp-policy-transition.test.ts": 5011,
"test/mcp/mcp-provider-ownership.test.ts": 9896,
"test/mcp/mcp-tool-discovery-image-contract.test.ts": 8489,
"test/networking/dns-proxy.test.ts": 5827,
@@ -200,12 +198,10 @@
"test/runtime/gateway/recover-port-forward.test.ts": 12821,
"test/runtime/messaging/telegram-diagnostics.test.ts": 5127,
"test/runtime/policy/policies.test.ts": 5377,
- "test/runtime/policy/policy-add-remove-session-sync.test.ts": 10393,
"test/runtime/policy/policy-channel-agent-resolution.test.ts": 8083,
"test/runtime/policy/policy-explain-cli.test.ts": 5249,
"test/runtime/policy/policy-openclaw-npm-compatibility.test.ts": 14295,
"test/runtime/policy/policy-preset-noop-disclosure.test.ts": 9796,
- "test/runtime/policy/policy-tiers-onboard-restricted-stale-otel.test.ts": 5808,
"test/runtime/policy/policy-tiers-onboard.test.ts": 8804,
"test/runtime/policy/portable-policy-failure-finality.test.ts": 8392,
"test/runtime/sandbox/reboot-identity-drift.test.ts": 13632,
diff --git a/ci/onboard-entry-composition-budget.json b/ci/onboard-entry-composition-budget.json
index 8c495e298d3..2db2ee70668 100644
--- a/ci/onboard-entry-composition-budget.json
+++ b/ci/onboard-entry-composition-budget.json
@@ -11,9 +11,8 @@
"runOnboard.finalizationDeps.verifyDeployment.getMessagingChannels": 1
},
"policy": {
- "createOnboardPolicyApplication.getRecordedPolicyTier": 1,
"preflightAuthoritativeRebuildTarget": 1,
- "runOnboard": 5,
+ "runOnboard": 4,
"sandboxCreateIntentResolver.getAgentPolicyPath": 1
},
"provider": {
diff --git a/ci/pi-agent-qualification-v1-linux-amd64.json b/ci/pi-agent-qualification-v1-linux-amd64.json
index 57d88671b9e..8ff11fbbcf7 100644
--- a/ci/pi-agent-qualification-v1-linux-amd64.json
+++ b/ci/pi-agent-qualification-v1-linux-amd64.json
@@ -3,13 +3,13 @@
"agent": "pi",
"platform": "linux/amd64",
"image": "ghcr.io/nvidia/nemoclaw/pi-sandbox",
- "digest": "sha256:4a50a8ce74d76a6002a1cd0fe65b329528e0e3713c221535b3cfd56237a4fdf0",
- "reference": "ghcr.io/nvidia/nemoclaw/pi-sandbox@sha256:4a50a8ce74d76a6002a1cd0fe65b329528e0e3713c221535b3cfd56237a4fdf0",
+ "digest": "sha256:492f2161f206644dd82c7206675e0b78f47da4f6c9a4fce23f38a4e2ef4e9b0f",
+ "reference": "ghcr.io/nvidia/nemoclaw/pi-sandbox@sha256:492f2161f206644dd82c7206675e0b78f47da4f6c9a4fce23f38a4e2ef4e9b0f",
"source": {
"repository": "NVIDIA/NemoClaw",
- "revision": "d92acac1c40364702eaae92a169a2b06d1bfda4b",
+ "revision": "f53e91c199a36b1d19cca29ff0c950d9807ebbe1",
"release": "v0.1.0",
- "cohort": "ghrun-32678646532-1"
+ "cohort": "ghrun-33220887790-1"
},
"startupProfileContractVersion": 1,
"capabilityContractVersion": 1
diff --git a/ci/pi-agent-qualification-v1-linux-arm64.json b/ci/pi-agent-qualification-v1-linux-arm64.json
index 8c39d462fcf..3fb50a14161 100644
--- a/ci/pi-agent-qualification-v1-linux-arm64.json
+++ b/ci/pi-agent-qualification-v1-linux-arm64.json
@@ -3,13 +3,13 @@
"agent": "pi",
"platform": "linux/arm64",
"image": "ghcr.io/nvidia/nemoclaw/pi-sandbox",
- "digest": "sha256:2f859158f229776f6b5ff441cf4a59432cfb2c37096e4ec879fdcb88ac3e57c3",
- "reference": "ghcr.io/nvidia/nemoclaw/pi-sandbox@sha256:2f859158f229776f6b5ff441cf4a59432cfb2c37096e4ec879fdcb88ac3e57c3",
+ "digest": "sha256:40de3fc971d91b174ba2bc2193c45b6e3c536f3cb28746b0af97a57e0a1ec543",
+ "reference": "ghcr.io/nvidia/nemoclaw/pi-sandbox@sha256:40de3fc971d91b174ba2bc2193c45b6e3c536f3cb28746b0af97a57e0a1ec543",
"source": {
"repository": "NVIDIA/NemoClaw",
- "revision": "d92acac1c40364702eaae92a169a2b06d1bfda4b",
+ "revision": "f53e91c199a36b1d19cca29ff0c950d9807ebbe1",
"release": "v0.1.0",
- "cohort": "ghrun-32678646532-1"
+ "cohort": "ghrun-33220887790-1"
},
"startupProfileContractVersion": 1,
"capabilityContractVersion": 1
diff --git a/ci/source-architecture-budget.json b/ci/source-architecture-budget.json
index 87b60637a41..04f22a30ab2 100644
--- a/ci/source-architecture-budget.json
+++ b/ci/source-architecture-budget.json
@@ -3,7 +3,7 @@
"fanIn": {
"defaultMax": 20,
"maxByFile": {
- "src/lib/actions/sandbox/mcp-bridge-contracts.ts": 26,
+ "src/lib/actions/sandbox/mcp-bridge-contracts.ts": 25,
"src/lib/actions/sandbox/process-recovery.ts": 27,
"src/lib/adapters/docker/index.ts": 43,
"src/lib/adapters/openshell/client.ts": 20,
@@ -11,24 +11,23 @@
"src/lib/adapters/openshell/runtime.ts": 55,
"src/lib/adapters/openshell/timeouts.ts": 38,
"src/lib/agent/defs.ts": 33,
- "src/lib/cli/branding.ts": 86,
+ "src/lib/cli/branding.ts": 85,
"src/lib/cli/nemoclaw-oclif-command.ts": 107,
"src/lib/cli/terminal-style.ts": 43,
"src/lib/core/json-types.ts": 37,
"src/lib/core/ports.ts": 89,
"src/lib/core/shell-quote.ts": 28,
"src/lib/core/url-utils.ts": 30,
- "src/lib/core/wait.ts": 38,
+ "src/lib/core/wait.ts": 37,
"src/lib/credentials/store.ts": 46,
"src/lib/inference/config.ts": 30,
- "src/lib/inference/web-search.ts": 21,
"src/lib/messaging/channels/index.ts": 25,
"src/lib/onboard/gateway-binding.ts": 53,
"src/lib/runner.ts": 86,
"src/lib/security/redact.ts": 54,
- "src/lib/state/onboard-session.ts": 36,
"src/lib/state/mcp-lifecycle-lock.ts": 21,
- "src/lib/state/registry.ts": 100,
+ "src/lib/state/onboard-session.ts": 35,
+ "src/lib/state/registry.ts": 97,
"src/lib/state/state-root.ts": 21,
"src/lib/subprocess-env.ts": 24,
"src/lib/validation.ts": 24
@@ -40,7 +39,7 @@
"src/lib/actions/inference-set.ts": 32,
"src/lib/actions/sandbox/connect.ts": 43,
"src/lib/actions/sandbox/destroy.ts": 29,
- "src/lib/actions/sandbox/doctor.ts": 29,
+ "src/lib/actions/sandbox/doctor.ts": 27,
"src/lib/actions/sandbox/gateway-state.ts": 21,
"src/lib/actions/sandbox/status-snapshot.ts": 19,
"src/lib/actions/sandbox/policy-channel.ts": 30,
@@ -51,7 +50,7 @@
"src/lib/inference/local.ts": 22,
"src/lib/inference/onboard-probes.ts": 21,
"src/lib/inference/vllm.ts": 21,
- "src/lib/onboard.ts": 201,
+ "src/lib/onboard.ts": 193,
"src/lib/onboard/machine/handlers/sandbox.ts": 21,
"src/lib/policy/index.ts": 23,
"src/lib/sandbox/config.ts": 22,
@@ -60,9 +59,9 @@
},
"allowedCycles": [],
"maxRootFiles": {
- "src/lib/onboard": 308,
+ "src/lib/onboard": 306,
"src/lib/actions": 19,
- "src/lib/actions/sandbox": 183,
+ "src/lib/actions/sandbox": 182,
"src/lib/state": 39,
"src/lib/inference": 63,
"scripts": 42
diff --git a/ci/test-file-size-budget.json b/ci/test-file-size-budget.json
index 8fb9442b5d0..cf40c21910c 100644
--- a/ci/test-file-size-budget.json
+++ b/ci/test-file-size-budget.json
@@ -8,7 +8,7 @@
"test/generation/generate-openclaw-config.test.ts": 1898,
"test/installer-integration/install-preflight.test.ts": 3025,
"test/agents/openclaw/runtime/nemoclaw-start.test.ts": 4626,
- "test/onboarding/onboard-messaging.test.ts": 1976,
+ "test/onboarding/onboard-messaging.test.ts": 1971,
"test/onboarding/onboard-selection.test.ts": 4176
}
}
diff --git a/docs/about/how-it-works.mdx b/docs/about/how-it-works.mdx
index 3fcf4c7b6cf..7146875e2ff 100644
--- a/docs/about/how-it-works.mdx
+++ b/docs/about/how-it-works.mdx
@@ -5,20 +5,23 @@ title: "NemoClaw Architecture Overview"
sidebar-title: "Architecture Overview"
description: "Learn how NemoClaw combines a host CLI, agent integration layer, versioned blueprint, and OpenShell gateway to operate supported agents."
description-agent: "Describes how NemoClaw works internally: host CLI, agent integration layer, blueprint runner, OpenShell orchestration, lifecycle state, managed integrations, inference routing, and protection layers. Use for sandbox lifecycle and architecture mechanics; not for product definition (Overview) or multi-project placement (Ecosystem)."
-keywords: ["how nemoclaw works", "nemoclaw sandbox lifecycle blueprint", "nemoclaw managed mcp architecture"]
+keywords:
+ [
+ "how nemoclaw works",
+ "nemoclaw sandbox lifecycle blueprint",
+ "nemoclaw managed mcp architecture",
+ ]
content:
type: "concept"
---
-This page explains how NemoClaw runs supported agent runtimes inside OpenShell sandboxes.
-It covers the host CLI, OpenShell gateway, agent integration layer, lifecycle state, managed Model Context Protocol (MCP) servers and other integrations, and protection layers.
-NemoClaw does not replace OpenShell or the selected agent runtime.
-It packages them as a repeatable setup with a versioned blueprint, agent-specific configuration, managed inference, network policy, and lifecycle operations.
+This page explains how NemoClaw runs supported agent runtimes inside OpenShell sandboxes. It covers the host CLI, OpenShell gateway, agent integration layer, lifecycle state, managed Model Context Protocol (MCP) servers and other integrations, and protection layers.
+
+NemoClaw does not replace OpenShell or the selected agent runtime. It packages them as a repeatable setup with a versioned blueprint, agent-specific configuration, managed inference, network policy, and lifecycle operations.
## High-Level Flow
-NemoClaw keeps operator control on the host while OpenShell enforces the sandbox boundary.
-The OpenShell gateway coordinates sandbox lifecycle, credentials, network policy, inference routes, and approved integration traffic.
+NemoClaw keeps operator control on the host while OpenShell enforces the sandbox boundary. The OpenShell gateway coordinates sandbox lifecycle, credentials, network policy, inference routes, and approved integration traffic.
```mermaid
flowchart LR
@@ -27,7 +30,7 @@ flowchart LR
GATEWAY["OpenShell gateway lifecycle, credentials, policy, routing"]:::gateway
SANDBOX["OpenShell sandbox agent runtime and integration layer"]:::sandbox
INTERFACE["Agent interface runtime-specific interaction path"]:::users
- STATE["Managed state and artifacts registry, workspace, policy records, snapshots"]:::state
+ STATE["Managed state and artifacts registry, workspace, logs, snapshots"]:::state
INFERENCE["Inference providers supported hosted or local inference"]:::inference
INTEGRATIONS["Approved integrations MCP servers and package services"]:::integrations
@@ -54,7 +57,7 @@ flowchart LR
The diagram has the following components:
| Component | Role in the flow |
-|-------|------------------|
+| --- | --- |
| Users and operators | Install and operate NemoClaw from the host, then interact through the selected agent interface. |
| NemoClaw host CLI | Collects configuration, runs readiness checks and onboarding, resolves the blueprint, and operates managed resources. |
| OpenShell gateway | Coordinates sandbox lifecycle, credentials, networking, policy enforcement, inference routing, and approved integration egress. |
@@ -62,7 +65,7 @@ The diagram has the following components:
| Agent interface | Provides the interaction path exposed by the selected agent runtime. |
| Inference providers | Receive managed inference requests through the OpenShell gateway. |
| Approved integrations | Receive policy-approved requests to MCP servers, package indexes, and other configured services. |
-| Managed state and artifacts | Preserve registry records, workspace files, policy records, logs, and manifest-declared snapshot content across supported lifecycle operations. |
+| Managed state and artifacts | Preserve non-policy registry records, workspace files, logs, and manifest-declared snapshot content; OpenShell alone stores sandbox policy. |
For repository layout, file paths, and deeper diagrams, refer to [Architecture](../reference/architecture).
@@ -70,26 +73,19 @@ For repository layout, file paths, and deeper diagrams, refer to [Architecture](
NemoClaw follows these architecture principles.
-Versioned blueprint
-: The blueprint runner resolves a versioned blueprint and verifies its digest before it changes managed resources.
+Versioned blueprint : The blueprint runner resolves a versioned blueprint and verifies its digest before it changes managed resources.
-Host credential custody
-: OpenShell stores inference provider credentials and managed MCP bearer values outside the sandbox and replaces placeholders at approved request boundaries.
+Host credential custody : OpenShell stores inference provider credentials and managed MCP bearer values outside the sandbox and replaces placeholders at approved request boundaries.
-Agent-specific integration
-: Each supported agent runtime receives the configuration, wrappers, plugin, or adapter required for its documented workflow.
+Agent-specific integration : Each supported agent runtime receives the configuration, wrappers, plugin, or adapter required for its documented workflow.
-Resumable lifecycle
-: NemoClaw records lifecycle progress and reconciles managed resources after supported interruptions or partial operations.
+Resumable lifecycle : NemoClaw records lifecycle progress and reconciles managed resources after supported interruptions or partial operations.
-Manifest-declared state
-: Rebuild, snapshot, and restore operations preserve only the state declared for the selected agent runtime.
- Each agent manifest and operation defines which credential-bearing files to exclude.
+Manifest-declared state : Rebuild, snapshot, and restore operations preserve only the state declared for the selected agent runtime. Each agent manifest and operation defines which credential-bearing files to exclude.
-Host-configured messaging credentials also use OpenShell credential delivery.
-Some messaging integrations, such as QR-paired WhatsApp, retain explicitly declared session credentials inside the sandbox so supported lifecycle operations can preserve them.
+Host-configured messaging credentials also use OpenShell credential delivery. Some messaging integrations, such as QR-paired WhatsApp, retain explicitly declared session credentials inside the sandbox so supported lifecycle operations can preserve them.
@@ -98,11 +94,10 @@ Some messaging integrations, such as QR-paired WhatsApp, retain explicitly decla
NemoClaw separates host orchestration, agent-specific behavior, and sandbox definition.
- The _host CLI_ runs readiness checks and onboarding, validates provider choices, records lifecycle state, and operates OpenShell resources.
+
-- The _OpenClaw integration layer_ includes a TypeScript plugin that runs inside the sandbox.
- It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks.
- Runtime context is prepended as system guidance, so sandbox and policy instructions stay active without appearing in the visible chat transcript.
+- The _OpenClaw integration layer_ includes a TypeScript plugin that runs inside the sandbox. It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks. Runtime context is prepended as system guidance, so sandbox and policy instructions stay active without appearing in the visible chat transcript.
@@ -112,8 +107,7 @@ NemoClaw separates host orchestration, agent-specific behavior, and sandbox defi
-- The _Deep Agents integration layer_ writes managed runtime configuration under `/sandbox/.deepagents`.
- It includes `config.toml`, managed MCP projection state, and the inference route used by `dcode`.
+- The _Deep Agents integration layer_ writes managed runtime configuration under `/sandbox/.deepagents`. It includes `config.toml`, managed MCP projection state, and the inference route used by `dcode`.
- The _blueprint_ is a versioned YAML package with the sandbox image, agent manifest, network policy, inference profile, and supporting assets.
@@ -123,15 +117,11 @@ This separation keeps host orchestration, agent-specific assets, and the sandbox
## Readiness and Sandbox Creation
-Run `$$nemoclaw host probe` when you need a read-only system readiness report before onboarding.
-The report combines host and gateway observations, capabilities, qualifications, findings, evidence, and CLI provenance without changing system state.
-Onboarding consumes the same stable host and gateway entities and applies its explicit admission policy.
-It revalidates live facts after permitted preparation and when a saved onboarding session resumes.
+Run `$$nemoclaw host probe` when you need a read-only system readiness report before onboarding. The report combines host and gateway observations, capabilities, qualifications, findings, evidence, and CLI provenance without changing system state. Onboarding consumes the same stable host and gateway entities and applies its explicit admission policy. It revalidates live facts after permitted preparation and when a saved onboarding session resumes.
When you run `$$nemoclaw onboard`, the host CLI and blueprint runner complete these operations:
-1. NemoClaw resolves gateway lifecycle authority and rejects blocking system readiness results before managed resource effects.
- A container-backed WSL GPU proof can run only after this admission check; explicit CPU-only intent skips it.
+1. NemoClaw resolves gateway lifecycle authority and rejects blocking system readiness results before managed resource effects. A container-backed WSL GPU proof can run only after this admission check; explicit CPU-only intent skips it.
2. NemoClaw resolves the blueprint, checks version compatibility, and verifies the digest.
3. Onboarding validates the selected inference provider, credentials, agent settings, and platform requirements.
4. The runner determines which gateway, provider, policy, sandbox, and integration resources to create or update.
@@ -144,7 +134,7 @@ After the sandbox starts, the selected agent uses its managed configuration and
NemoClaw operates the sandbox and its manifest-declared state through host-side commands.
| Operation | Result |
-|---|---|
+| --- | --- |
| Inspect | `host probe`, `status`, and `logs` report system, sandbox, agent-runtime, inference, and recovery information without replacing the sandbox. |
| Configure | Inference, policy, managed MCP, and supported agent-runtime integration commands update the applicable managed resources. |
| Rebuild | Recreates the sandbox from the recorded configuration and restores supported agent state through a recorded transaction. |
@@ -156,37 +146,31 @@ Refer to [Recover and Rebuild Sandboxes](../manage-sandboxes/operate-sandboxes/r
## Inference Routing
-Managed agent runtimes send model requests to `inference.local` instead of an upstream endpoint.
-During onboarding, NemoClaw validates the selected provider and model, configures the OpenShell inference route, and writes the matching model reference into the managed agent configuration.
-OpenShell keeps the provider credential outside the sandbox and sends approved requests to the upstream endpoint.
-When you select the Model Router provider, `inference.local` routes to a host-side router that chooses from the configured NVIDIA model pool for each request.
+Managed agent runtimes send model requests to `inference.local` instead of an upstream endpoint. During onboarding, NemoClaw validates the selected provider and model, configures the OpenShell inference route, and writes the matching model reference into the managed agent configuration. OpenShell keeps the provider credential outside the sandbox and sends approved requests to the upstream endpoint. When you select the Model Router provider, `inference.local` routes to a host-side router that chooses from the configured NVIDIA model pool for each request.
+
-For Hermes, `$$nemoclaw inference set` updates `/sandbox/.hermes/config.yaml` at runtime without rebuilding the sandbox.
+ For Hermes, `$$nemoclaw inference set` updates `/sandbox/.hermes/config.yaml` at runtime without
+ rebuilding the sandbox.
-For Deep Agents, the managed `dcode` runtime reads the OpenAI-compatible route that NemoClaw writes into `/sandbox/.deepagents/config.toml`.
+ For Deep Agents, the managed `dcode` runtime reads the OpenAI-compatible route that NemoClaw
+ writes into `/sandbox/.deepagents/config.toml`.
## Managed Integrations
NemoClaw connects supported external services through OpenShell providers, network policy, and agent-specific adapters.
-Managed MCP supports authenticated HTTPS Streamable HTTP MCP servers for OpenClaw, Hermes, and Deep Agents Code.
-NemoClaw stores the credential name and ownership metadata, while OpenShell stores the raw value outside the sandbox.
-The agent adapter receives a credential placeholder that OpenShell replaces only at the approved egress boundary.
+Managed MCP supports authenticated HTTPS Streamable HTTP MCP servers for OpenClaw, Hermes, and Deep Agents Code. NemoClaw stores the credential name and ownership metadata, while OpenShell stores the raw value outside the sandbox. The agent adapter receives a credential placeholder that OpenShell replaces only at the approved egress boundary.
-Messaging channels use agent-specific channel manifests, credential delivery, network policy, and lifecycle commands.
-Some experimental webhook channels also require a route-restricted host-side public endpoint.
-Refer to [Choose Messaging Channels](../manage-sandboxes/messaging-channels/choose-messaging-channels) for agent and channel status.
+Messaging channels use agent-specific channel manifests, credential delivery, network policy, and lifecycle commands. Some experimental webhook channels also require a route-restricted host-side public endpoint. Refer to [Choose Messaging Channels](../manage-sandboxes/messaging-channels/choose-messaging-channels) for agent and channel status.
-Deep Agents Code can also opt into bounded trace export to an operator-managed host collector.
-Native LangSmith tracing and ambient OpenTelemetry exporter configuration remain disabled inside the sandbox.
-Refer to [Understand Deep Agents Trace Export](../monitoring/understand-deepagents-trace-export) for the data and receiver trust boundaries.
+Deep Agents Code can also opt into bounded trace export to an operator-managed host collector. Native LangSmith tracing and ambient OpenTelemetry exporter configuration remain disabled inside the sandbox. Refer to [Understand Deep Agents Trace Export](../monitoring/understand-deepagents-trace-export) for the data and receiver trust boundaries.
@@ -197,18 +181,15 @@ Refer to [About Managed MCP Servers](../manage-sandboxes/mcp-servers/about-manag
The sandbox starts with a baseline policy that controls network egress, filesystem access, process privileges, and inference routing.
| Layer | What it protects | When it applies |
-|---|---|---|
+| --- | --- | --- |
| Network | Blocks unauthorized outbound connections. | Hot-reloadable at runtime. |
| Filesystem | Restricts system paths to read-only; `/sandbox` and `/tmp` are writable. | Locked at sandbox creation. |
| Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. |
| Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. |
-When the agent tries to reach an unapproved host, OpenShell blocks the request and surfaces it in the terminal user interface (TUI) for operator approval.
-Approved endpoints persist within the current sandbox instance but are not saved to the baseline policy file.
-NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether policy denial, DNS, timeout, TLS, or filesystem access caused a failure.
+When the agent tries to reach an unapproved host, OpenShell blocks the request and surfaces it in the terminal user interface (TUI) for operator approval. Approved endpoints persist within the current sandbox instance but are not saved to the baseline policy file. NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether policy denial, DNS, timeout, TLS, or filesystem access caused a failure.
-Host and platform limitations can change how individual controls apply.
-Refer to [Platform Support](../reference/platform-support) and [Security Best Practices](../security/best-practices) before you treat a control as an environment-wide guarantee.
+Host and platform limitations can change how individual controls apply. Refer to [Platform Support](../reference/platform-support) and [Security Best Practices](../security/best-practices) before you treat a control as an environment-wide guarantee.
## Next Steps
diff --git a/docs/deployment/deploy-to-headless-server.mdx b/docs/deployment/deploy-to-headless-server.mdx
index 4e2dc401c74..e58e543dcac 100644
--- a/docs/deployment/deploy-to-headless-server.mdx
+++ b/docs/deployment/deploy-to-headless-server.mdx
@@ -11,34 +11,33 @@ content:
skill:
priority: 20
---
-Run NemoClaw on a remote Linux server through SSH without exposing the OpenShell gateway or dashboard to the network.
-This guide covers unattended onboarding, verified readiness, routine updates, and manual recovery after a host reboot.
+
+Run NemoClaw on a remote Linux server through SSH without exposing the OpenShell gateway or dashboard to the network. This guide covers unattended onboarding, verified readiness, routine updates, and manual recovery after a host reboot.
-A Linux VM that you provision through Brev is one example of a headless server.
-These instructions also apply to Linux hosts on other clouds, VPS services, or on-premises infrastructure.
-NemoClaw setup starts after server provisioning and does not depend on Brev or its web UI.
+ A Linux VM that you provision through Brev is one example of a headless server. These instructions
+ also apply to Linux hosts on other clouds, VPS services, or on-premises infrastructure. NemoClaw
+ setup starts after server provisioning and does not depend on Brev or its web UI.
-NemoClaw does not guarantee that Docker, the OpenShell gateway, sandboxes, tunnels, or host forwards start automatically after a host reboot.
-Use the [manual recovery sequence](#recover-after-a-host-reboot) after each reboot.
-Do not install an unofficial service unit as a substitute for this sequence.
+ NemoClaw does not guarantee that Docker, the OpenShell gateway, sandboxes, tunnels, or host
+ forwards start automatically after a host reboot. Use the [manual recovery
+ sequence](#recover-after-a-host-reboot) after each reboot. Do not install an unofficial service
+ unit as a substitute for this sequence.
## Check the Server
-Use a Linux host that meets the supported [NemoClaw prerequisites](../get-started/prerequisites).
-The primary tested server path is Linux with Docker.
+Use a Linux host that meets the supported [NemoClaw prerequisites](../get-started/prerequisites). The primary tested server path is Linux with Docker.
-| Resource | Minimum | Recommended |
-|---|---:|---:|
-| CPU | 4 vCPU | 4 or more vCPU |
-| RAM | 8 GB | 16 GB |
-| Free disk | 20 GB | 40 GB |
+| Resource | Minimum | Recommended |
+| --------- | ------: | -------------: |
+| CPU | 4 vCPU | 4 or more vCPU |
+| RAM | 8 GB | 16 GB |
+| Free disk | 20 GB | 40 GB |
-The image build, Docker daemon, and OpenShell gateway can exhaust a smaller host during onboarding.
-If the host has less than 8 GB of RAM, configure at least 8 GB of swap before onboarding.
+The image build, Docker daemon, and OpenShell gateway can exhaust a smaller host during onboarding. If the host has less than 8 GB of RAM, configure at least 8 GB of swap before onboarding.
Run these checks from the remote host:
@@ -53,17 +52,13 @@ free -h
swapon --show
```
-`docker info` must succeed for the same account that runs NemoClaw.
-Membership in the `docker` group grants root-level control of the Docker daemon, so grant it only to trusted accounts.
+`docker info` must succeed for the same account that runs NemoClaw. Membership in the `docker` group grants root-level control of the Docker daemon, so grant it only to trusted accounts.
-The host firewall must allow the outbound DNS, HTTPS, image-registry, package-registry, and inference-provider traffic selected during onboarding.
-The OpenShell policy controls traffic from the sandbox and does not replace the host firewall.
-Keep inbound dashboard and OpenShell gateway ports closed when you use SSH forwarding.
+The host firewall must allow the outbound DNS, HTTPS, image-registry, package-registry, and inference-provider traffic selected during onboarding. The OpenShell policy controls traffic from the sandbox and does not replace the host firewall. Keep inbound dashboard and OpenShell gateway ports closed when you use SSH forwarding.
## Keep Remote Access on Loopback
-The OpenShell gateway binds to `127.0.0.1` by default.
-Dashboard and API forwards also stay on loopback outside WSL unless you explicitly change the bind setting.
+The OpenShell gateway binds to `127.0.0.1` by default. Dashboard and API forwards also stay on loopback outside WSL unless you explicitly change the bind setting.
Connect to the server from your workstation:
@@ -73,40 +68,32 @@ ssh @
-After onboarding, keep the server-side forward on loopback and create a second SSH tunnel from your workstation.
-The default dashboard port is `18789`, but NemoClaw can select the next free port through `18799`.
-Use the port printed by `$$nemoclaw headless-agent dashboard-url`.
+After onboarding, keep the server-side forward on loopback and create a second SSH tunnel from your workstation. The default dashboard port is `18789`, but NemoClaw can select the next free port through `18799`. Use the port printed by `$$nemoclaw headless-agent dashboard-url`.
```bash
ssh -N -L 18789:127.0.0.1:18789 @
```
-Then open the loopback URL printed by `$$nemoclaw headless-agent dashboard-url --quiet` on your workstation.
-Replace both `18789` values when NemoClaw selected another port.
+Then open the loopback URL printed by `$$nemoclaw headless-agent dashboard-url --quiet` on your workstation. Replace both `18789` values when NemoClaw selected another port.
-Deep Agents Code is a terminal runtime and has no dashboard port.
-Run `$$nemoclaw launch headless-agent` through the SSH session to start `dcode` in that session.
-Use `$$nemoclaw headless-agent connect` instead when you want a sandbox shell.
+Deep Agents Code is a terminal runtime and has no dashboard port. Run `$$nemoclaw launch headless-agent` through the SSH session to start `dcode` in that session. Use `$$nemoclaw headless-agent connect` instead when you want a sandbox shell.
-Do not open port `8080` for remote access.
-Do not bind the dashboard to every interface when an SSH tunnel meets the access requirement.
+Do not open port `8080` for remote access. Do not bind the dashboard to every interface when an SSH tunnel meets the access requirement.
## Protect a Long Onboarding Run
-Run onboarding inside a `tmux` or `screen` session so an SSH disconnect does not terminate the host process.
-To start a `tmux` session, run:
+Run onboarding inside a `tmux` or `screen` session so an SSH disconnect does not terminate the host process. To start a `tmux` session, run:
```bash
tmux new-session -s nemoclaw-onboard
```
-Detach with `Ctrl-b`, then `d` while onboarding continues.
-After you reconnect through SSH, reattach to the session:
+Detach with `Ctrl-b`, then `d` while onboarding continues. After you reconnect through SSH, reattach to the session:
```bash
tmux attach-session -t nemoclaw-onboard
@@ -118,15 +105,13 @@ To use `screen` instead, start a session:
screen -S nemoclaw-onboard
```
-Detach with `Ctrl-a`, then `d` while onboarding continues.
-After you reconnect through SSH, reattach to the session:
+Detach with `Ctrl-a`, then `d` while onboarding continues. After you reconnect through SSH, reattach to the session:
```bash
screen -r nemoclaw-onboard
```
-Do not enable shell tracing with `set -x` in a session that contains credentials.
-Do not save the session transcript when it can contain a dashboard URL or token.
+Do not enable shell tracing with `set -x` in a session that contains credentials. Do not save the session transcript when it can contain a dashboard URL or token.
If the onboarding process exited after it saved a resumable session, export the same required credential variables and resume it:
@@ -136,18 +121,11 @@ NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 \
$$nemoclaw onboard --resume --yes-i-accept-third-party-software --yes
```
-`--resume` uses the provider, model, sandbox name, agent, and completed non-secret choices from the saved session.
-Raw credentials are not stored in the onboarding session.
-If resume reports a missing credential variable, inject that variable again and repeat the command.
-Use `--fresh` only when you intend to discard the saved onboarding session and start again.
+`--resume` uses the provider, model, sandbox name, agent, and completed non-secret choices from the saved session. Raw credentials are not stored in the onboarding session. If resume reports a missing credential variable, inject that variable again and repeat the command. Use `--fresh` only when you intend to discard the saved onboarding session and start again.
## Run Unattended Onboarding
-Select a reviewed NemoClaw commit and set its full 40-character SHA before unattended installation.
-The example uses that SHA in both the immutable bootstrap URL and `NEMOCLAW_INSTALL_REF`, so the bootstrap and cloned installer payload come from the same repository state.
-Do not use the mutable `lkg` or `latest` references as the primary install source for a persistent server.
-Inject provider credentials from your secret manager into the host environment before you run this example.
-The example fails before the network install if the commit SHA or `NVIDIA_INFERENCE_API_KEY` is missing or invalid.
+Select a reviewed NemoClaw commit and set its full 40-character SHA before unattended installation. The example uses that SHA in both the immutable bootstrap URL and `NEMOCLAW_INSTALL_REF`, so the bootstrap and cloned installer payload come from the same repository state. Do not use the mutable `lkg` or `latest` references as the primary install source for a persistent server. Inject provider credentials from your secret manager into the host environment before you run this example. The example fails before the network install if the commit SHA or `NVIDIA_INFERENCE_API_KEY` is missing or invalid.
@@ -195,20 +173,16 @@ curl -fsSL "https://raw.githubusercontent.com/NVIDIA/NemoClaw/${NEMOCLAW_INSTALL
bash
```
-Pass every onboarding `NEMOCLAW_*` value on the `bash` side of the pipeline so the downloaded installer can read it.
-The commit pin also appears in the bootstrap URL so no mutable tag selects the code that enters the pipeline.
-Do not put a credential before `curl`, in a command-line argument, or in a committed script.
-Unset the credential from the interactive shell after onboarding completes:
+Pass every onboarding `NEMOCLAW_*` value on the `bash` side of the pipeline so the downloaded installer can read it. The commit pin also appears in the bootstrap URL so no mutable tag selects the code that enters the pipeline. Do not put a credential before `curl`, in a command-line argument, or in a committed script. Unset the credential from the interactive shell after onboarding completes:
```bash
unset NVIDIA_INFERENCE_API_KEY
```
-Use the matching credential variable when you select another provider.
-Refer to the [CLI commands reference](../reference/commands#nemoclaw-onboard) for provider-specific variables and accepted values.
+Use the matching credential variable when you select another provider. Refer to the [CLI commands reference](../reference/commands#nemoclaw-onboard) for provider-specific variables and accepted values.
| Variable | Requirement | Secret | Purpose |
-|---|---|---|---|
+| --- | --- | --- | --- |
| `NEMOCLAW_NON_INTERACTIVE=1` | Required for unattended use | No | Disables interactive onboarding prompts. |
| `NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1` | Required for unattended use | No | Records explicit acceptance for the current run. |
| `NEMOCLAW_AGENT` | Required when the agent must not use the default | No | Selects `openclaw`, `hermes`, or `langchain-deepagents-code`. |
@@ -222,9 +196,7 @@ Refer to the [CLI commands reference](../reference/commands#nemoclaw-onboard) fo
## Verify Readiness
-Do not use process presence as the sandbox-ready signal.
-The authoritative OpenShell signal is the row for `headless-agent` in phase `Ready` or `Running`.
-The substring `NotReady` is not a ready state.
+Do not use process presence as the sandbox-ready signal. The authoritative OpenShell signal is the row for `headless-agent` in phase `Ready` or `Running`. The substring `NotReady` is not a ready state.
Run each verification on the remote host:
@@ -234,25 +206,17 @@ $$nemoclaw headless-agent status
$$nemoclaw headless-agent connect --probe-only
```
-`$$nemoclaw headless-agent status` exits nonzero when the sandbox, gateway, local container, or authoritative inference route is not verified.
-Its main `Inference` line probes `https://inference.local/v1/models` from inside the sandbox, then sends one inference request over the same route when that probe reports the route reachable.
-The line reports `healthy` when the route served the request, `unauthorized` when the route rejected it with HTTP `401` or `403`, and `unhealthy` when the route returned HTTP `500` through `599`.
+`$$nemoclaw headless-agent status` exits nonzero when the sandbox, gateway, local container, or authoritative inference route is not verified. Its main `Inference` line probes `https://inference.local/v1/models` from inside the sandbox, then sends one inference request over the same route when that probe reports the route reachable. The line reports `healthy` when the route served the request, `unauthorized` when the route rejected it with HTTP `401` or `403`, and `unhealthy` when the route returned HTTP `500` through `599`.
+
-During an SSH session, `status` points to `$$nemoclaw headless-agent dashboard-url` only when the agent gateway is running and loopback dashboard access needs a port forward.
-The printed command quotes the sandbox name so that the shell treats it as one argument.
+During an SSH session, `status` points to `$$nemoclaw headless-agent dashboard-url` only when the agent gateway is running and loopback dashboard access needs a port forward. The printed command quotes the sandbox name so that the shell treats it as one argument.
-`connect --probe-only` waits up to 300 seconds by default for a cold sandbox to become ready.
-It then verifies or repairs the in-sandbox agent process and host forwards without opening a shell.
-It does not restart or replace the shared host OpenShell gateway.
+`connect --probe-only` waits up to 300 seconds by default for a cold sandbox to become ready. It then verifies or repairs the in-sandbox agent process and host forwards without opening a shell. It does not restart or replace the shared host OpenShell gateway.
-The command prints one `Probe timing:` line with elapsed milliseconds for `readiness`, `authority`, `lifecycle`, `gateway`, `processes`, `forward`, `inference`, `pairing`, and `publication` stages.
-Use the stage values to identify where a slow or failed deployment spent its time.
-The line also reports lifecycle and forward actions and names the failed stage when available.
-Timing collection is diagnostic and fail-open.
-The command exit status remains the readiness decision: status `0` means the complete probe passed, and any nonzero status means the host is not ready for launch.
+The command prints one `Probe timing:` line with elapsed milliseconds for `readiness`, `authority`, `lifecycle`, `gateway`, `processes`, `forward`, `inference`, `pairing`, and `publication` stages. Use the stage values to identify where a slow or failed deployment spent its time. The line also reports lifecycle and forward actions and names the failed stage when available. Timing collection is diagnostic and fail-open. The command exit status remains the readiness decision: status `0` means the complete probe passed, and any nonzero status means the host is not ready for launch.
Readiness requires all of these results:
@@ -262,8 +226,7 @@ Readiness requires all of these results:
## Access the Dashboard and API
-Retrieve dashboard URLs and API tokens only when you need them.
-Do not write either value to logs, shell history, support bundles, or version control.
+Retrieve dashboard URLs and API tokens only when you need them. Do not write either value to logs, shell history, support bundles, or version control.
@@ -273,8 +236,7 @@ Print the complete authenticated dashboard URL:
$$nemoclaw headless-agent dashboard-url --quiet
```
-Use the raw gateway token only for automation that cannot use the tokenized dashboard URL.
-This example authenticates the supported Control UI configuration endpoint on the server loopback interface:
+Use the raw gateway token only for automation that cannot use the tokenized dashboard URL. This example authenticates the supported Control UI configuration endpoint on the server loopback interface:
```bash
TOKEN=$($$nemoclaw headless-agent gateway-token --quiet)
@@ -283,8 +245,7 @@ curl -fsS -H "Authorization: Bearer $TOKEN" \
unset TOKEN
```
-An unauthenticated request to this endpoint returns `401`.
-The static path `controlui.bootstrap.config.json` does not exist and returns `404`.
+An unauthenticated request to this endpoint returns `401`. The static path `controlui.bootstrap.config.json` does not exist and returns `404`.
@@ -295,11 +256,7 @@ Print the Hermes dashboard URL:
$$nemoclaw headless-agent dashboard-url --quiet
```
-The Hermes OpenAI-compatible API uses the loopback forward on the sandbox's own API port, which onboarding allocates from `8642` through `8652`.
-Run `openshell forward list` and select the `headless-agent` row whose local port is in that range.
-Replace `` below with that port.
-For a Hermes sandbox, `gateway-token` is agent-aware and retrieves `API_SERVER_KEY` through the registered `bearer_token` web-auth contract.
-Use it as a bearer token, then clear the shell variable:
+The Hermes OpenAI-compatible API uses the loopback forward on the sandbox's own API port, which onboarding allocates from `8642` through `8652`. Run `openshell forward list` and select the `headless-agent` row whose local port is in that range. Replace `` below with that port. For a Hermes sandbox, `gateway-token` is agent-aware and retrieves `API_SERVER_KEY` through the registered `bearer_token` web-auth contract. Use it as a bearer token, then clear the shell variable:
```bash
TOKEN=$($$nemoclaw headless-agent gateway-token --quiet)
@@ -311,23 +268,18 @@ unset TOKEN
-Deep Agents Code does not expose a dashboard URL or gateway token.
-Model traffic uses the OpenShell-managed `inference.local` route.
+Deep Agents Code does not expose a dashboard URL or gateway token. Model traffic uses the OpenShell-managed `inference.local` route.
-OpenClaw generates a new gateway token when the sandbox container starts with mutable configuration.
-If Shields are up, a non-root start preserves the sealed token because the sandbox user cannot replace the protected configuration.
-Retrieve the dashboard URL or token again after the container starts or a replacement sandbox is created.
+OpenClaw generates a new gateway token when the sandbox container starts with mutable configuration. If Shields are up, a non-root start preserves the sealed token because the sandbox user cannot replace the protected configuration. Retrieve the dashboard URL or token again after the container starts or a replacement sandbox is created.
-Hermes preserves its `API_SERVER_KEY` when the same sandbox container restarts.
-A replacement sandbox generates a new `API_SERVER_KEY`.
-Retrieve the dashboard URL or token again after a replacement sandbox is created.
+Hermes preserves its `API_SERVER_KEY` when the same sandbox container restarts. A replacement sandbox generates a new `API_SERVER_KEY`. Retrieve the dashboard URL or token again after a replacement sandbox is created.
@@ -336,16 +288,14 @@ Retrieve the dashboard URL or token again after a replacement sandbox is created
NemoClaw separates provider credentials, host metadata, and sandbox state.
| Boundary | Stored data | Rebuild behavior |
-|---|---|---|
+| --- | --- | --- |
| OpenShell gateway | Provider credentials and provider registrations | Reused when the gateway and provider binding remain available. Raw values cannot be read back. |
-| `~/.nemoclaw/` on the host | Sandbox registry, provider names, policy metadata, and onboarding session state | Preserved by normal updates. The directory contains metadata, not provider credential values. |
+| `~/.nemoclaw/` on the host | Sandbox registry, provider names, and onboarding session state | Preserved by normal updates. The directory contains no sandbox policy or provider credential values. |
| Agent configuration in the sandbox | Generated inference routes, OpenShell resolver placeholders, and agent-specific settings | Regenerated from host registry and OpenShell state. Generated files are not a credential store. |
| Manifest-defined sandbox state | Agent workspace, memory, skills, and agent-specific durable files | Snapshotted and restored according to the selected agent manifest. |
| Arbitrary environment and profile edits | Direct shell exports and edits outside the manifest contract | Not guaranteed. Export host variables again and use documented host commands for durable configuration. |
-NemoClaw holds an environment-supplied provider credential in memory while it registers the value with OpenShell.
-The sandbox receives a resolver placeholder, and OpenShell substitutes the raw value at egress.
-For details, refer to [Credential Storage](../security/credential-storage).
+NemoClaw holds an environment-supplied provider credential in memory while it registers the value with OpenShell. The sandbox receives a resolver placeholder, and OpenShell substitutes the raw value at egress. For details, refer to [Credential Storage](../security/credential-storage).
Install a declarative agent skill through the supported host command:
@@ -353,13 +303,11 @@ Install a declarative agent skill through the supported host command:
$$nemoclaw headless-agent skill install ./my-skill/
```
-The skill directory must contain `SKILL.md` with a `name` field in its YAML frontmatter.
-Do not assume that packages, shell exports, or profile edits made by a skill survive a rebuild.
+The skill directory must contain `SKILL.md` with a `name` field in its YAML frontmatter. Do not assume that packages, shell exports, or profile edits made by a skill survive a rebuild.
## Add a Least-Privilege Policy
-Use an additive custom preset when the sandbox needs a destination that the current policy does not allow.
-Scope the host, port, method, path, and executable to the smallest required set.
+Use an additive custom preset when the sandbox needs a destination that the current policy does not allow. Scope the host, port, method, path, and executable to the smallest required set.
Save a reviewed preset as `./presets/internal-status.yaml`, preview it, then apply it without a prompt:
@@ -369,15 +317,9 @@ $$nemoclaw headless-agent policy add --from-file ./presets/internal-status.yaml
$$nemoclaw headless-agent policy list
```
-`--yes` skips the confirmation prompt but does not skip schema, destination, or SSRF validation.
-NemoClaw records the full validated YAML content in the sandbox registry.
-Snapshot restore and rebuild replay that recorded preset even when the original host file is unavailable.
-Keep the source YAML in your configuration repository so operators can review and change it.
-For the preset schema and removal workflow, refer to [Network Policies](../reference/network-policies).
+`--yes` skips the confirmation prompt but does not skip schema, destination, or SSRF validation. NemoClaw merges the validated content into the current OpenShell policy and stores no second copy in the sandbox registry. Snapshot clone and rebuild carry the complete current OpenShell policy forward. Keep the source YAML in your configuration repository so operators can review and intentionally reapply changes. For the preset schema and removal workflow, refer to [Network Policies](../reference/network-policies).
-An SSH command without `-t`, a service unit, and a CI job have no terminal on stdin, so the preset picker cannot run there.
-Pass the preset name, `--from-file`, or `--from-dir` in such a session.
-`policy add` and `policy remove` skip their confirmation prompts without a terminal on stdin, so neither needs `--yes` or `NEMOCLAW_NON_INTERACTIVE=1`.
+An SSH command without `-t`, a service unit, and a CI job have no terminal on stdin, so the preset picker cannot run there. Pass the preset name, `--from-file`, or `--from-dir` in such a session. `policy add` and `policy remove` skip their confirmation prompts without a terminal on stdin, so neither needs `--yes` or `NEMOCLAW_NON_INTERACTIVE=1`.
## Plan for Updates and Rebuilds
@@ -396,30 +338,31 @@ curl -fsSL "https://raw.githubusercontent.com/NVIDIA/NemoClaw/${NEMOCLAW_INSTALL
$$nemoclaw upgrade-sandboxes --check
```
-Use a newly reviewed commit SHA for each planned update instead of relying on the mutable installer default.
-The installer requires current backups before it changes an existing managed installation.
-Use `$$nemoclaw headless-agent rebuild` when you need the current agent image while preserving supported state.
+Use a newly reviewed commit SHA for each planned update instead of relying on the mutable installer default. The installer requires current backups before it changes an existing managed installation. Use `$$nemoclaw headless-agent rebuild` when you need the current agent image while preserving supported state.
| Item | Same-container restart | Snapshot and restore | Rebuild or sandbox upgrade |
-|---|---|---|---|
+| --- | --- | --- | --- |
| Provider configuration | Preserved | Provider names are recorded, but raw credentials are not in the snapshot | Regenerated from registry and OpenShell provider state |
-| Custom preset YAML applied with `policy add` | Preserved in registry | Stored content is included in snapshot metadata | Replayed from stored content |
+| Current OpenShell policy, including custom presets and host edits | Remains in OpenShell | Read live for a clone handoff, not stored in snapshot metadata | Read live and handed to replacement creation |
| Manifest-defined user and agent state | Preserved | Preserved | Preserved when backup and restore succeed |
| Arbitrary files outside manifest state | Usually remain in the same writable layer | Not preserved | Not preserved |
| Manually installed system or global packages | Usually remain in the same writable layer | Not preserved | Not preserved |
| Direct edits to generated profile, config, or environment files | May remain until regeneration | Agent-specific and usually excluded or filtered | Regenerated or filtered by the current manifest |
+
-| OpenClaw gateway token | Rotated when the container starts with mutable configuration; preserved for a non-root start while Shields are up | Not captured; a replacement sandbox generates a new token | Rotated for the replacement sandbox |
+ | OpenClaw gateway token | Rotated when the container starts with mutable configuration; preserved
+ for a non-root start while Shields are up | Not captured; a replacement sandbox generates a new
+ token | Rotated for the replacement sandbox |
-| Hermes `API_SERVER_KEY` | Preserved | Not captured; a replacement sandbox generates a new token | Rotated for the replacement sandbox |
+ | Hermes `API_SERVER_KEY` | Preserved | Not captured; a replacement sandbox generates a new token
+ | Rotated for the replacement sandbox |
-| Host tunnel process | Not applicable to a container restart | Not preserved | Not preserved |
-| Dashboard, API, messaging, and agent forwards | Preserved only while their host processes remain active | Re-established during supported recovery | Re-established and verified after rebuild |
+| Host tunnel process | Not applicable to a container restart | Not preserved | Not preserved | |
+Dashboard, API, messaging, and agent forwards | Preserved only while their host processes remain
+active | Re-established during supported recovery | Re-established and verified after rebuild |
-Snapshot only the state that the current agent manifest declares.
-Download any required file outside that contract before a destructive operation.
-Refer to [Understand Sandbox State](../manage-sandboxes/state-and-backups/understand-sandbox-state) and [Create and Restore Snapshots](../manage-sandboxes/state-and-backups/create-and-restore-snapshots) for agent-specific exclusions.
+Snapshot only the state that the current agent manifest declares. Download any required file outside that contract before a destructive operation. Refer to [Understand Sandbox State](../manage-sandboxes/state-and-backups/understand-sandbox-state) and [Create and Restore Snapshots](../manage-sandboxes/state-and-backups/create-and-restore-snapshots) for agent-specific exclusions.
## Recover After a Host Reboot
@@ -460,26 +403,23 @@ If the sandbox is ready but the in-sandbox agent gateway or host forward remains
$$nemoclaw headless-agent recover
```
-`recover`, `start`, and `connect --probe-only` do not restart the shared host OpenShell gateway.
-If they report a host gateway RPC error, follow the printed host gateway recovery guidance.
+`recover`, `start`, and `connect --probe-only` do not restart the shared host OpenShell gateway. If they report a host gateway RPC error, follow the printed host gateway recovery guidance.
-Deep Agents Code has no in-sandbox gateway to recover.
-If status reports a degraded terminal runtime after the sandbox becomes ready, rebuild the sandbox.
+Deep Agents Code has no in-sandbox gateway to recover. If status reports a degraded terminal runtime after the sandbox becomes ready, rebuild the sandbox.
-If the registry entry remains but the sandbox container is missing, rebuild from recorded metadata and the latest valid snapshot:
+If the registry entry remains but the sandbox container is missing, rebuild cannot recover the sandbox because its authoritative OpenShell policy and live workspace are gone. Remove the stale local entry and create a clean replacement:
```bash
-$$nemoclaw headless-agent rebuild --yes
+$$nemoclaw headless-agent destroy --yes
+$$nemoclaw onboard
```
-Do not destroy the registry entry before this recovery attempt because rebuild needs that metadata.
-If you intentionally deleted the sandbox and want a new installation, destroy the stale registry entry and run onboarding again.
-For failure-specific recovery boundaries, refer to [Recover and Rebuild Sandboxes](../manage-sandboxes/operate-sandboxes/recover-and-rebuild-sandboxes).
+The missing sandbox's state cannot be recovered unless you have a separate snapshot. After onboarding, restore that snapshot explicitly. For failure-specific recovery boundaries, refer to [Recover and Rebuild Sandboxes](../manage-sandboxes/operate-sandboxes/recover-and-rebuild-sandboxes).
@@ -493,20 +433,15 @@ Use the failure layer from `$$nemoclaw headless-agent status` before you choose
### Onboarding Was Interrupted
-Reattach to the `tmux` or `screen` session first.
-If the process exited with a resumable session, inject the required credentials and use `onboard --resume`.
-Do not use `--fresh` unless discarding the saved choices and progress is intentional.
+Reattach to the `tmux` or `screen` session first. If the process exited with a resumable session, inject the required credentials and use `onboard --resume`. Do not use `--fresh` unless discarding the saved choices and progress is intentional.
### The Sandbox Is Missing or Not Ready
-Run `openshell sandbox list` and inspect the row for `headless-agent`.
-`NotReady` does not satisfy readiness.
-Run `$$nemoclaw headless-agent status`, then use its `start`, `connect --probe-only`, or `rebuild --yes` guidance.
+Run `openshell sandbox list` and inspect the row for `headless-agent`. `NotReady` does not satisfy readiness. Run `$$nemoclaw headless-agent status`, then use its `start`, `connect --probe-only`, or `rebuild --yes` guidance.
### Inference Returns HTTP 5xx
-An HTTP status from `500` through `599` makes the authoritative `inference.local` route unhealthy.
-Check the configured provider and host egress, then run:
+An HTTP status from `500` through `599` makes the authoritative `inference.local` route unhealthy. Check the configured provider and host egress, then run:
```bash
$$nemoclaw headless-agent doctor
@@ -520,9 +455,7 @@ Do not treat a running agent process as proof that inference works.
### Dashboard or Token Retrieval Fails
-Run `$$nemoclaw headless-agent status` and `connect --probe-only` before retrieving the URL or token again.
-The token command exits nonzero when the sandbox is not registered, not running, or cannot expose its agent-specific token.
-Do not paste a token into diagnostics.
+Run `$$nemoclaw headless-agent status` and `connect --probe-only` before retrieving the URL or token again. The token command exits nonzero when the sandbox is not registered, not running, or cannot expose its agent-specific token. Do not paste a token into diagnostics.
diff --git a/docs/get-started/quickstart-langchain-deepagents-code.mdx b/docs/get-started/quickstart-langchain-deepagents-code.mdx
index 33d767d9880..3880965337f 100644
--- a/docs/get-started/quickstart-langchain-deepagents-code.mdx
+++ b/docs/get-started/quickstart-langchain-deepagents-code.mdx
@@ -5,7 +5,13 @@ title: "Quickstart with LangChain Deep Agents Code"
sidebar-title: "Quickstart with Deep Agents"
description: "Install NemoClaw, launch a LangChain Deep Agents Code sandbox, and run your first prompt."
description-agent: "Installs NemoClaw, launches a LangChain Deep Agents Code sandbox, and runs the first prompt. Use when installing or testing dcode for the first time."
-keywords: ["langchain deep agents code nemoclaw", "dcode openshell sandbox", "langchain coding agent", "dcode otlp tracing"]
+keywords:
+ [
+ "langchain deep agents code nemoclaw",
+ "dcode openshell sandbox",
+ "langchain coding agent",
+ "dcode otlp tracing",
+ ]
topics: ["get-started", "terminal-runtime", "langchain-deepagents-code", "observability"]
tags: ["deep-agents-code", "dcode", "managed-inference", "otlp"]
difficulty: "intermediate"
@@ -15,14 +21,12 @@ content:
type: "get_started"
agent-variants: ["deepagents"]
---
-Create a sandboxed LangChain Deep Agents Code agent, then run your first prompt.
-The `nemo-deepagents` command is an alias for `nemoclaw` with the `langchain-deepagents-code` agent pre-selected.
+
+Create a sandboxed LangChain Deep Agents Code agent, then run your first prompt. The `nemo-deepagents` command is an alias for `nemoclaw` with the `langchain-deepagents-code` agent pre-selected.
## Set Up with the Starter Prompt on Your Coding Agent
-Copy this starter prompt into Cursor, Claude Code, Codex, Copilot, or another local coding agent when you want it to guide the installation.
-The prompt points the agent to [Use NemoClaw Docs with Your Coding Agents](../resources/agent-skills), this quickstart, the Markdown docs, and the optional `nemoclaw-user-guide` skill.
-It asks the agent to confirm LangChain Deep Agents Code before it runs commands that create a sandbox or receive credentials and to use the checked-in local credential helper and form only after you approve the command that receives credentials.
+Copy this starter prompt into Cursor, Claude Code, Codex, Copilot, or another local coding agent when you want it to guide the installation. The prompt points the agent to [Use NemoClaw Docs with Your Coding Agents](../resources/agent-skills), this quickstart, the Markdown docs, and the optional `nemoclaw-user-guide` skill. It asks the agent to confirm LangChain Deep Agents Code before it runs commands that create a sandbox or receive credentials and to use the checked-in local credential helper and form only after you approve the command that receives credentials.
@@ -30,12 +34,9 @@ If you prefer to control setup directly, use [Set Up with the Interactive Instal
## Set Up with the Interactive Installer on Your Terminal
-If you use the coding-agent prompt in the preceding section, you can skip this procedure or keep it as reference.
-The prompt directs your coding agent to this quickstart, so it has the full setup context.
+If you use the coding-agent prompt in the preceding section, you can skip this procedure or keep it as reference. The prompt directs your coding agent to this quickstart, so it has the full setup context.
-
-Review the [Prerequisites](prerequisites) before you begin.
-
+Review the [Prerequisites](prerequisites) before you begin.
@@ -44,6 +45,7 @@ Review the [Prerequisites](prerequisites) before you begin.
```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=langchain-deepagents-code NEMOCLAW_SANDBOX_NAME=my-deepagents bash
```
+
@@ -68,6 +70,7 @@ Review the [Prerequisites](prerequisites) before you begin.
If registry or catalog availability prevents resolution, stock onboarding stops before sandbox creation and does not build a shipped Dockerfile.
Invalid or inconsistent catalog evidence fails closed before sandbox creation.
An explicit `nemo-deepagents onboard --from ` remains a separate custom-image path.
+
@@ -76,6 +79,7 @@ Review the [Prerequisites](prerequisites) before you begin.
```bash
nemo-deepagents my-deepagents status
```
+
@@ -95,6 +99,7 @@ Review the [Prerequisites](prerequisites) before you begin.
nemo-deepagents my-deepagents connect
dcode
```
+
@@ -125,14 +130,14 @@ Use these details when you need more control during setup or after the first san
Refer to [Set Up vLLM](../inference/local-inference/set-up-vllm) for managed model profiles and headless setup.
Refer to [Set Up vLLM on Two DGX Stations](../inference/local-inference/set-up-vllm-on-two-dgx-stations) for the Deferred paired workflow.
Refer to [Platform Support](../reference/platform-support) for current validation status.
+
### Installation and Onboarding Details
-The hosted installer follows the last-known-good (`lkg`) release tag by default, so the install command selects the maintained Deep Agents-capable build without a version override.
-If NemoClaw is already installed, run `nemo-deepagents onboard` to start Deep Agents onboarding directly.
+The hosted installer follows the last-known-good (`lkg`) release tag by default, so the install command selects the maintained Deep Agents-capable build without a version override. If NemoClaw is already installed, run `nemo-deepagents onboard` to start Deep Agents onboarding directly.
You can use the canonical agent ID or a short alias instead of `nemo-deepagents`.
@@ -143,96 +148,43 @@ nemoclaw onboard --agent deepagents
nemoclaw onboard --agent langchain
```
-The wizard asks for an inference provider, model, required credential, and sandbox name before it prints the review summary.
-The review offers these actions:
+The wizard asks for an inference provider, model, required credential, and sandbox name before it prints the review summary. The 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.
-Provider registration, inference setup, policy selection, and sandbox creation then continue forward.
-The default Deep Agents sandbox name is `deepagents-code`.
-Use a distinct name, such as `my-deepagents`, when you run Deep Agents, Hermes, and OpenClaw sandboxes side by side.
-Refer to [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) for provider-specific prompts.
-
-The image installs hash-locked Deep Agents Code `0.1.55` with NVIDIA provider support.
-After the terminal smoke checks, onboarding runs `dcode --version` and compares the result with the version required by the agent manifest.
-Fresh and resumed onboarding exit nonzero instead of reporting the runtime ready when the installed version is too old, uses an incompatible version scheme, or cannot be verified.
-If the version check fails, review the reported version error and run `nemo-deepagents rebuild` before resuming onboarding.
-NemoClaw writes `/sandbox/.deepagents/config.toml` with an OpenAI-compatible provider pointed at `https://inference.local/v1`, uses a scoped placeholder API key for that managed route, and sets `use_responses_api = false` for Chat Completions compatibility.
-When onboarding records a reasoning effort on a `compatible-endpoint` route that uses `openai-completions`, managed startup writes that value to a root-owned file and Deep Agents Code model requests carry it as an `extra_body.reasoning_effort` request parameter.
-Leave `NEMOCLAW_REASONING_EFFORT` unset to keep the endpoint's own default.
-Deep Agents Code has no runtime `inference set` path, so re-onboard the sandbox with `nemo-deepagents onboard --fresh --name --recreate-sandbox` to change the recorded effort.
-When you use NVIDIA Endpoints without selecting another model, new Deep Agents Code sandboxes default to `nvidia/nemotron-3-ultra-550b-a55b`.
-For this model, the managed image maps the OpenAI-compatible route to Deep Agents `0.7.5`'s native Nemotron 3 Ultra harness profile, including model-specific tool-calling, filesystem, retry, context, and final-answer safeguards.
-Rebuild existing Deep Agents Code sandboxes after upgrading to NemoClaw v0.0.76 or later so their image includes this profile.
-This agent-specific default does not change the shared Nemotron 3 Super default for OpenClaw and Hermes.
-NemoClaw/OpenShell keeps real provider credentials in credential handling and does not write them into the Deep Agents config file.
-Deep Agents Code reaches `inference.local` through the managed OpenShell L7 proxy rather than direct sandbox DNS.
-The image launcher normalizes the runtime proxy environment for interactive, login-shell, and direct-exec paths and removes inherited proxy credentials and bypass entries before `dcode` starts.
-Managed interactive sessions pre-complete Deep Agents Code's optional first-run onboarding, skip its dependency and model selection screens, then open the TUI with the model selected during NemoClaw onboarding.
-The image includes `ripgrep` and `dos2unix`, and ordinary sessions suppress the optional Tavily warning unless web search is configured or invoked.
+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. Provider registration, inference setup, policy selection, and sandbox creation then continue forward. The default Deep Agents sandbox name is `deepagents-code`. Use a distinct name, such as `my-deepagents`, when you run Deep Agents, Hermes, and OpenClaw sandboxes side by side. Refer to [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) for provider-specific prompts.
-
+The image installs hash-locked Deep Agents Code `0.1.55` with NVIDIA provider support. After the terminal smoke checks, onboarding runs `dcode --version` and compares the result with the version required by the agent manifest. Fresh and resumed onboarding exit nonzero instead of reporting the runtime ready when the installed version is too old, uses an incompatible version scheme, or cannot be verified. If the version check fails, review the reported version error and run `nemo-deepagents rebuild` before resuming onboarding. NemoClaw writes `/sandbox/.deepagents/config.toml` with an OpenAI-compatible provider pointed at `https://inference.local/v1`, uses a scoped placeholder API key for that managed route, and sets `use_responses_api = false` for Chat Completions compatibility. When onboarding records a reasoning effort on a `compatible-endpoint` route that uses `openai-completions`, managed startup writes that value to a root-owned file and Deep Agents Code model requests carry it as an `extra_body.reasoning_effort` request parameter. Leave `NEMOCLAW_REASONING_EFFORT` unset to keep the endpoint's own default. Deep Agents Code has no runtime `inference set` path, so re-onboard the sandbox with `nemo-deepagents onboard --fresh --name --recreate-sandbox` to change the recorded effort. When you use NVIDIA Endpoints without selecting another model, new Deep Agents Code sandboxes default to `nvidia/nemotron-3-ultra-550b-a55b`. For this model, the managed image maps the OpenAI-compatible route to Deep Agents `0.7.5`'s native Nemotron 3 Ultra harness profile, including model-specific tool-calling, filesystem, retry, context, and final-answer safeguards. Rebuild existing Deep Agents Code sandboxes after upgrading to NemoClaw v0.0.76 or later so their image includes this profile. This agent-specific default does not change the shared Nemotron 3 Super default for OpenClaw and Hermes. NemoClaw/OpenShell keeps real provider credentials in credential handling and does not write them into the Deep Agents config file. Deep Agents Code reaches `inference.local` through the managed OpenShell L7 proxy rather than direct sandbox DNS. The image launcher normalizes the runtime proxy environment for interactive, login-shell, and direct-exec paths and removes inherited proxy credentials and bypass entries before `dcode` starts. Managed interactive sessions pre-complete Deep Agents Code's optional first-run onboarding, skip its dependency and model selection screens, then open the TUI with the model selected during NemoClaw onboarding. The image includes `ripgrep` and `dos2unix`, and ordinary sessions suppress the optional Tavily warning unless web search is configured or invoked.
-
-
- Continue with [Run Deep Agents Code](../manage-sandboxes/operate-sandboxes/run-deep-agents-code) for sandbox selection, interactive and headless tasks, the JSON output contract, runtime restrictions, thread auto-approval, and identity checks.
+
+
+ Continue with [Run Deep Agents Code](../manage-sandboxes/operate-sandboxes/run-deep-agents-code)
+ for sandbox selection, interactive and headless tasks, the JSON output contract, runtime
+ restrictions, thread auto-approval, and identity checks.
+
+
### Python Environment
-Deep Agents Code runs from a NemoClaw-managed Python virtual environment at `/opt/venv`.
-The sandbox puts `/opt/venv/bin` on `PATH` before the system Python directories, so `python3` and `pip3` resolve to that managed environment.
-NemoClaw keeps `/opt/venv` read-only to protect the installed harness.
-For project-specific Python dependencies, create a separate virtual environment under `/sandbox` and activate it before installing packages.
+Deep Agents Code runs from a NemoClaw-managed Python virtual environment at `/opt/venv`. The sandbox puts `/opt/venv/bin` on `PATH` before the system Python directories, so `python3` and `pip3` resolve to that managed environment. NemoClaw keeps `/opt/venv` read-only to protect the installed harness. For project-specific Python dependencies, create a separate virtual environment under `/sandbox` and activate it before installing packages.
### State and Backup
-Deep Agents Code state lives under `/sandbox/.deepagents`.
-NemoClaw snapshot and rebuild flows preserve the app state directory and skills when those paths exist.
-During managed re-onboarding, NemoClaw restores only these `config.toml` preferences from backup: boolean `ui.show_scrollbar`, boolean `ui.show_url_open_toast`, boolean `threads.relative_time`, and `threads.sort_order` when it is `updated_at` or `created_at`.
-Freshly generated model routing, update settings, provider metadata, and all other configuration remain authoritative.
-NemoClaw drops all other backup settings, including `ui.theme`, behavior-bearing keys, unknown keys, and security-sensitive keys.
-It recreates the sandbox when its live `dcode identity` output is unreadable or does not match the selected provider and model, then records the selection only after the restored runtime passes the same check.
-Run `nemoclaw snapshot create` after active `dcode` tasks finish.
-For `langchain-deepagents-code` sandboxes, NemoClaw refuses backup when it detects an active `dcode` task or cannot verify that the state tree is idle.
-NemoClaw intentionally does not back up `.deepagents/.env` or the user-owned `.deepagents/.mcp.json` because users may put Tavily, LangSmith, MCP service, or provider credentials there.
-The managed `.deepagents/.nemoclaw-mcp.json` projection is also excluded because NemoClaw reconstructs it from the credential-free registry after recreation.
-Service credentials remain in OpenShell provider state.
-It also does not preserve `hooks.json`; executable Deep Agents Code hooks are disabled in the managed harness.
-If `.deepagents/.state/auth.json` contains upstream credentials, or `.deepagents/.state/chatgpt-auth.json` exists, the managed Deep Agents Code launch paths refuse to start until that credential state is removed.
-Before a managed Deep Agents Code rebuild changes the sandbox, NemoClaw selects its recorded OpenShell gateway, tests the recorded inference route through `https://inference.local`, and prepares the replacement from the recorded provider, model, policy, and build inputs with a pinned base and fingerprinted context.
-Initial failures stop before backup.
-After backup, NemoClaw rechecks the target, route, and retained build inputs before changing MCP state, then checks again after MCP preparation and before stopping inference or deleting the old sandbox.
-If the final check fails, NemoClaw restores the previous MCP state and keeps the existing sandbox intact.
-Rebuild also preserves the standalone Deep Agents Code `tavily` preset, the recorded observability choice unless explicitly overridden, and recorded custom policies from their stored content.
+Deep Agents Code state lives under `/sandbox/.deepagents`. NemoClaw snapshot and rebuild flows preserve the app state directory and skills when those paths exist. During managed re-onboarding, NemoClaw restores only these `config.toml` preferences from backup: boolean `ui.show_scrollbar`, boolean `ui.show_url_open_toast`, boolean `threads.relative_time`, and `threads.sort_order` when it is `updated_at` or `created_at`. Freshly generated model routing, update settings, provider metadata, and all other configuration remain authoritative. NemoClaw drops all other backup settings, including `ui.theme`, behavior-bearing keys, unknown keys, and security-sensitive keys. It recreates the sandbox when its live `dcode identity` output is unreadable or does not match the selected provider and model, then records the selection only after the restored runtime passes the same check. Run `nemoclaw snapshot create` after active `dcode` tasks finish. For `langchain-deepagents-code` sandboxes, NemoClaw refuses backup when it detects an active `dcode` task or cannot verify that the state tree is idle. NemoClaw intentionally does not back up `.deepagents/.env` or the user-owned `.deepagents/.mcp.json` because users may put Tavily, LangSmith, MCP service, or provider credentials there. The managed `.deepagents/.nemoclaw-mcp.json` projection is also excluded because NemoClaw reconstructs it from the credential-free registry after recreation. Service credentials remain in OpenShell provider state. It also does not preserve `hooks.json`; executable Deep Agents Code hooks are disabled in the managed harness. If `.deepagents/.state/auth.json` contains upstream credentials, or `.deepagents/.state/chatgpt-auth.json` exists, the managed Deep Agents Code launch paths refuse to start until that credential state is removed. Before a managed Deep Agents Code rebuild changes the sandbox, NemoClaw selects its recorded OpenShell gateway, tests the recorded inference route through `https://inference.local`, and prepares the replacement from the recorded provider, model, policy, and build inputs with a pinned base and fingerprinted context. Initial failures stop before backup. After backup, NemoClaw rechecks the target, route, and retained build inputs before changing MCP state, then checks again after MCP preparation and before stopping inference or deleting the old sandbox. If the final check fails, NemoClaw restores the previous MCP state and keeps the existing sandbox intact. Rebuild carries the complete current OpenShell policy forward, including Deep Agents Code `tavily`, custom entries, and trusted host-side edits. The recorded observability choice is preserved unless explicitly overridden.
### Optional Tavily Egress
-Deep Agents Code does not currently have a NemoClaw-managed web-search feature.
-If your project code or a manually configured tool needs Tavily, opt the sandbox Python egress path into Tavily explicitly.
-Register the raw key only with the OpenShell gateway on the host, not inside the sandbox, in `.env`, or in Deep Agents config files.
-The gateway injects it at egress instead.
-The managed Deep Agents Code entry points reject credential-shaped process environment values, disable project `.env` and global `/sandbox/.deepagents/.env` loading, and block upstream `/auth`, `/connect`, startup/onboarding credential prompts, model-selector credential prompts, notification-service key prompts, and ChatGPT OAuth.
-These controls apply to Deep Agents Code and do not sanitize arbitrary Python programs in the sandbox.
-Use NemoClaw-managed credential paths when support is available instead of storing service keys inside Deep Agents Code state.
-NemoClaw does not enable Tavily or observability by default for this harness.
-The sandbox policy denies `api.tavily.com` until you opt into Tavily and continues to deny direct `api.smith.langchain.com` egress when you enable observability.
+Deep Agents Code does not currently have a NemoClaw-managed web-search feature. If your project code or a manually configured tool needs Tavily, opt the sandbox Python egress path into Tavily explicitly. Register the raw key only with the OpenShell gateway on the host, not inside the sandbox, in `.env`, or in Deep Agents config files. The gateway injects it at egress instead. The managed Deep Agents Code entry points reject credential-shaped process environment values, disable project `.env` and global `/sandbox/.deepagents/.env` loading, and block upstream `/auth`, `/connect`, startup/onboarding credential prompts, model-selector credential prompts, notification-service key prompts, and ChatGPT OAuth. These controls apply to Deep Agents Code and do not sanitize arbitrary Python programs in the sandbox. Use NemoClaw-managed credential paths when support is available instead of storing service keys inside Deep Agents Code state. NemoClaw does not enable Tavily or observability by default for this harness. The sandbox policy denies `api.tavily.com` until you opt into Tavily and continues to deny direct `api.smith.langchain.com` egress when you enable observability.
-To allow Tavily egress for the target sandbox, apply the maintained `tavily` policy preset, register the credential with the OpenShell gateway, then rebuild the sandbox so the new provider attaches.
-The policy preset is a per-sandbox managed-Python opt-in, but provider registration is gateway-wide: `tavily-search` attaches to every sandbox that you build or rebuild afterward.
+To allow Tavily egress for the target sandbox, apply the maintained `tavily` policy preset, register the credential with the OpenShell gateway, then rebuild the sandbox so the new provider attaches. The policy preset is a per-sandbox managed-Python opt-in, but provider registration is gateway-wide: `tavily-search` attaches to every sandbox that you build or rebuild afterward.
```bash
# Preview the endpoints the preset opens:
@@ -249,11 +201,7 @@ unset TAVILY_API_KEY
nemo-deepagents rebuild
```
-The shared `tavily` preset only opens `POST /search` and `POST /extract` egress to `api.tavily.com:443`.
-Attaching the credential provider alone does not authorize the managed Python interpreter; the explicit policy preset is the interpreter-level opt-in.
-Export `TAVILY_API_KEY` only for registration, then remove it from the host shell; the gateway injects the stored value at egress, and the sandbox never sees the raw value.
-NemoClaw does not bake `TAVILY_API_KEY` into the managed config or image, and the managed wrapper rejects direct service-key injection into `dcode`.
-Because OpenShell attributes the harness's calls to the sandbox `python3` interpreter, this egress is process-wide for sandbox Python rather than a `dcode`-only boundary.
+The shared `tavily` preset only opens `POST /search` and `POST /extract` egress to `api.tavily.com:443`. Attaching the credential provider alone does not authorize the managed Python interpreter; the explicit policy preset is the interpreter-level opt-in. Export `TAVILY_API_KEY` only for registration, then remove it from the host shell; the gateway injects the stored value at egress, and the sandbox never sees the raw value. NemoClaw does not bake `TAVILY_API_KEY` into the managed config or image, and the managed wrapper rejects direct service-key injection into `dcode`. Because OpenShell attributes the harness's calls to the sandbox `python3` interpreter, this egress is process-wide for sandbox Python rather than a `dcode`-only boundary.
Remove the target sandbox's managed-Python opt-in when it is no longer needed.
@@ -261,9 +209,7 @@ Remove the target sandbox's managed-Python opt-in when it is no longer needed.
nemo-deepagents policy remove tavily --yes
```
-This does not unregister the gateway-wide `tavily-search` provider; its credential and Node/curl routes remain available to sandboxes that attach it.
-When no sandbox needs the provider, destroy those sandboxes or detach it from each one with `openshell sandbox provider detach tavily-search`, then remove it globally with `nemo-deepagents credentials reset tavily-search --yes`.
-OpenShell rejects provider deletion while any sandbox still has it attached.
+This does not unregister the gateway-wide `tavily-search` provider; its credential and Node/curl routes remain available to sandboxes that attach it. When no sandbox needs the provider, destroy those sandboxes or detach it from each one with `openshell sandbox provider detach tavily-search`, then remove it globally with `nemo-deepagents credentials reset tavily-search --yes`. OpenShell rejects provider deletion while any sandbox still has it attached.
@@ -297,16 +243,9 @@ nemo-deepagents rebuild
nemo-deepagents snapshot create --name before-change
```
-If you upgrade from a release that persisted LangSmith environment values, rebuild each existing Deep Agents Code sandbox so its image includes the corrected `start.sh`.
-If an existing sandbox displays `Choose a Recommended Model`, rebuild it so its image includes the managed startup behavior.
+If you upgrade from a release that persisted LangSmith environment values, rebuild each existing Deep Agents Code sandbox so its image includes the corrected `start.sh`. If an existing sandbox displays `Choose a Recommended Model`, rebuild it so its image includes the managed startup behavior.
-`status` reports the selected harness as a terminal runtime and prints the interactive/headless command shape.
-If `status` reports `Runtime health: degraded` with an OOM kill count, rebuild the sandbox to restore the terminal runtime.
-Proxy launchers and startup scripts are baked into the sandbox image.
-After upgrading NemoClaw from a release with older Deep Agents Code routing, rebuild each existing sandbox before troubleshooting `inference.local` connectivity.
-NemoClaw v0.0.78 and newer clients fail closed when a pre-v0.0.78 sandbox image lacks the trusted `/usr/local/lib/nemoclaw/dcode-managed-exec` route-probe helper, even when the installed Deep Agents Code version still matches the managed manifest.
-Rebuild the sandbox to install that image-owned helper before retrying `status`, `doctor`, `connect`, or onboarding recovery.
-There is no dashboard port or long-running gateway process for this harness.
+`status` reports the selected harness as a terminal runtime and prints the interactive/headless command shape. If `status` reports `Runtime health: degraded` with an OOM kill count, rebuild the sandbox to restore the terminal runtime. Proxy launchers and startup scripts are baked into the sandbox image. After upgrading NemoClaw from a release with older Deep Agents Code routing, rebuild each existing sandbox before troubleshooting `inference.local` connectivity. NemoClaw v0.0.78 and newer clients fail closed when a pre-v0.0.78 sandbox image lacks the trusted `/usr/local/lib/nemoclaw/dcode-managed-exec` route-probe helper, even when the installed Deep Agents Code version still matches the managed manifest. Rebuild the sandbox to install that image-owned helper before retrying `status`, `doctor`, `connect`, or onboarding recovery. There is no dashboard port or long-running gateway process for this harness.
## Next Steps
diff --git a/docs/manage-sandboxes/backup-restore.mdx b/docs/manage-sandboxes/backup-restore.mdx
index 780e22aee9d..fd06b486a1b 100644
--- a/docs/manage-sandboxes/backup-restore.mdx
+++ b/docs/manage-sandboxes/backup-restore.mdx
@@ -11,8 +11,8 @@ content:
skill:
priority: 20
---
-NemoClaw snapshots preserve manifest-defined sandbox state before destructive or state-changing operations.
-They are the preferred backup and restore path.
+
+NemoClaw snapshots preserve manifest-defined sandbox state before destructive or state-changing operations. They are the preferred backup and restore path.
## When to Create a Snapshot
@@ -34,38 +34,25 @@ They are the preferred backup and restore path.
## Understand Snapshot Contents
-Snapshots capture the manifest-declared snapshot state directories and store them in `~/.nemoclaw/rebuild-backups//`.
-Agent manifests can also declare durable top-level state files.
-Treat snapshot directories as private local data.
+Snapshots capture the manifest-declared snapshot state directories and store them in `~/.nemoclaw/rebuild-backups//`. Agent manifests can also declare durable top-level state files. Treat snapshot directories as private local data.
-
-Inside an OpenClaw sandbox, `~` expands to `/sandbox`, not to the OpenClaw workspace.
-Files such as `~/USER.md` and `~/SOUL.md` are therefore outside OpenClaw's managed state and are not included in snapshots.
-Store them as `$OPENCLAW_WORKSPACE_DIR/USER.md` and `$OPENCLAW_WORKSPACE_DIR/SOUL.md` so snapshot and restore operations preserve them.
-
+
+ Inside an OpenClaw sandbox, `~` expands to `/sandbox`, not to the OpenClaw workspace. Files such
+ as `~/USER.md` and `~/SOUL.md` are therefore outside OpenClaw's managed state and are not
+ included in snapshots. Store them as `$OPENCLAW_WORKSPACE_DIR/USER.md` and
+ `$OPENCLAW_WORKSPACE_DIR/SOUL.md` so snapshot and restore operations preserve them.
+
-Before NemoClaw marks a snapshot complete, it strips recognized credential values from copied JSON, YAML, and `.env` files.
-It preserves recognized dependency lockfiles byte for byte when they contain only dependency metadata.
-This behavior includes installed npm `.package-lock.json` files.
-It omits a recognized lockfile when the file is invalid or contains any of these values:
+Before NemoClaw marks a snapshot complete, it strips recognized credential values from copied JSON, YAML, and `.env` files. It preserves recognized dependency lockfiles byte for byte when they contain only dependency metadata. This behavior includes installed npm `.package-lock.json` files. It omits a recognized lockfile when the file is invalid or contains any of these values:
- A credential field.
- A provider-shaped secret outside a dependency URL.
- URL user information.
- A credential-bearing query parameter.
-Dependency names in lockfile maps do not count as credential fields.
-NemoClaw also preserves valid, credential-free `node_modules/**/package.json` manifests byte for byte because dependency names can match credential field names.
-It omits an installed package manifest when the file contains invalid JSON, a credential or authentication field, a provider-shaped secret, or a credential-bearing URL.
-It continues to sanitize configuration and `.env` files inside installed dependency trees.
-It preserves OpenShell credential placeholders so rebuild can reattach the host-side provider.
-If NemoClaw cannot sanitize a copied configuration or environment file, it omits that file from the snapshot.
-If it cannot remove the unsafe file, snapshot creation returns an error.
-It deletes the incomplete backup when cleanup succeeds and reports when the backup remains.
-This sanitization uses an isolated `python3` helper on POSIX hosts to keep reads, replacements, and removals anchored to opened directory descriptors.
-If a copied file or parent directory changes identity during the operation, snapshot creation fails closed instead of following the changed path.
+Dependency names in lockfile maps do not count as credential fields. NemoClaw also preserves valid, credential-free `node_modules/**/package.json` manifests byte for byte because dependency names can match credential field names. It omits an installed package manifest when the file contains invalid JSON, a credential or authentication field, a provider-shaped secret, or a credential-bearing URL. It continues to sanitize configuration and `.env` files inside installed dependency trees. It preserves OpenShell credential placeholders so rebuild can reattach the host-side provider. If NemoClaw cannot sanitize a copied configuration or environment file, it omits that file from the snapshot. If it cannot remove the unsafe file, snapshot creation returns an error. It deletes the incomplete backup when cleanup succeeds and reports when the backup remains. This sanitization uses an isolated `python3` helper on POSIX hosts to keep reads, replacements, and removals anchored to opened directory descriptors. If a copied file or parent directory changes identity during the operation, snapshot creation fails closed instead of following the changed path.
A previous release sanitized dependency lockfiles and installed package manifests.
@@ -87,29 +74,24 @@ NemoClaw uses SQLite's online backup API and restores these databases through SQ
After it replaces a database, NemoClaw opens a write transaction against the result and fails the restore when the database cannot be written.
Named-profile cron and Discord databases under `.hermes/profiles//` use raw directory capture and can be inconsistent if a write overlaps the snapshot.
-Kanban backup is limited to the backward-compatible default board in `kanban.db`.
-Named boards, attachments, worker logs, scratch workspaces under `.hermes/kanban/`, and external directory or worktree targets are not included; back up that state separately.
+Kanban backup is limited to the backward-compatible default board in `kanban.db`. Named boards, attachments, worker logs, scratch workspaces under `.hermes/kanban/`, and external directory or worktree targets are not included; back up that state separately.
+
+The dashboard profile includes `MEMORY.md` and `USER.md`. The Hermes state database can contain session metadata and message history needed for a faithful restore.
-The dashboard profile includes `MEMORY.md` and `USER.md`.
-The Hermes state database can contain session metadata and message history needed for a faithful restore.
Deep Agents snapshots include manifest-declared state under `/sandbox/.deepagents`, including skills and runtime state, while omitting credential-bearing user files.
NemoClaw refuses to create a snapshot when it detects an active `dcode` task or cannot verify that the Deep Agents state tree is idle.
Wait for active `dcode` work to finish before running `$$nemoclaw snapshot create`.
+
-Snapshots preserve sandbox registry metadata that affects rebuild behavior, including custom policy presets applied with `policy add --from-file` or `policy add --from-dir` and baseline network policy entries excluded with `policy exclude`.
-When you restore a snapshot, NemoClaw replays those recorded custom presets with their stored YAML content, so you do not need the original preset files on disk, and rebuild continues to apply the recorded baseline exclusions.
+Snapshot clone reads the source sandbox policy from OpenShell and passes that complete current OpenShell policy to destination creation through a private temporary handoff. The snapshot manifest and registry contain no custom-preset copy, baseline-exclusion record, or desired-policy replay state.
-The target sandbox's current agent manifest remains authoritative for directory and state-file restore behavior.
-NemoClaw rejects the restore when the snapshot's agent, config directory, any snapshot directory, state-file path, or state-file strategy conflicts with that manifest.
-Restore limits directory cleanup to state directories authorized by both the snapshot and the current manifest.
-It preserves target-only directories and directories whose backup failed.
+The target sandbox's current agent manifest remains authoritative for directory and state-file restore behavior. NemoClaw rejects the restore when the snapshot's agent, config directory, any snapshot directory, state-file path, or state-file strategy conflicts with that manifest. Restore limits directory cleanup to state directories authorized by both the snapshot and the current manifest. It preserves target-only directories and directories whose backup failed.
-For managed images, NemoClaw applies the current manifest's managed config merge rules by default and does not fall back to whole-file replacement.
-For Deep Agents targets, whole-file config replacement is limited to sandboxes created from a custom Dockerfile.
+For managed images, NemoClaw applies the current manifest's managed config merge rules by default and does not fall back to whole-file replacement. For Deep Agents targets, whole-file config replacement is limited to sandboxes created from a custom Dockerfile.
## Create and List Snapshots
@@ -118,14 +100,12 @@ $$nemoclaw my-assistant snapshot create
$$nemoclaw my-assistant snapshot list
```
-`snapshot list` prints a table of version, name, timestamp, and path.
-NemoClaw computes versions (`v1`, `v2`, through `vN`) from timestamp order, so `vN` is always the newest snapshot.
+`snapshot list` prints a table of version, name, timestamp, and path. NemoClaw computes versions (`v1`, `v2`, through `vN`) from timestamp order, so `vN` is always the newest snapshot.
+
+`snapshot create` requires shields to be down. Snapshot creation and restore share the per-sandbox transition lock with the shields auto-restore timer.
-`snapshot create` requires shields to be down.
-Snapshot creation and restore share the per-sandbox transition lock with the shields auto-restore timer.
+If a timed shields-down window expires during snapshot work, the deadline gate blocks new mutations and waits for the exact snapshot owner to finish without signaling it. Snapshot work does not bypass recovery for an expired shields-down window.
-If a timed shields-down window expires during snapshot work, the deadline gate blocks new mutations and waits for the snapshot owner to finish without signaling it.
-Snapshot work does not bypass recovery for an expired shields-down window.
Follow [Timed Shields Windows](../configure-sandboxes/understand-runtime-changes#timed-shields-windows) to correct state-directory failures or complete generation recovery before you rerun `$$nemoclaw snapshot create`.
@@ -142,10 +122,7 @@ Tag a snapshot with a human-readable label:
$$nemoclaw my-assistant snapshot create --name before-upgrade
```
-When a directory or state file cannot be captured, `snapshot create` reports the failed items, removes the incomplete snapshot, and exits nonzero.
-`snapshot list` shows no new entry, so a later restore cannot select a capture that never completed.
-If removal fails, the command reports the listed snapshot path.
-Remove that directory manually before you run `snapshot restore` because the incomplete capture remains selectable.
+When a directory or state file cannot be captured, `snapshot create` reports the failed items, removes the incomplete snapshot, and exits nonzero. `snapshot list` shows no new entry, so a later restore cannot select a capture that never completed. If removal fails, the command reports the listed snapshot path. Remove that directory manually before you run `snapshot restore` because the incomplete capture remains selectable.
## Restore a Snapshot
@@ -155,8 +132,7 @@ Restore the latest snapshot:
$$nemoclaw my-assistant snapshot restore
```
-Pass a version, name, or timestamp to select a specific snapshot.
-Use the complete timestamp from `snapshot list`; a timestamp prefix does not select a snapshot.
+Pass an exact version, name, or timestamp to select a specific snapshot. Use the exact timestamp from `snapshot list`; a timestamp prefix does not select a snapshot.
```bash
$$nemoclaw my-assistant snapshot restore v3
@@ -164,18 +140,7 @@ $$nemoclaw my-assistant snapshot restore before-upgrade
$$nemoclaw my-assistant snapshot restore 2026-04-14T09-40-09-760Z
```
-
-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 policy list`.
-Confirm that the named preset is recorded in the sandbox registry and active on the gateway, or absent from both.
-
+In-place restore does not mutate the OpenShell policy. Cross-sandbox clone reads the source live policy and uses it only as the destination creation handoff.
A running Hermes gateway keeps serving its pre-restore state databases until it reopens them.
@@ -183,26 +148,18 @@ After a restore that includes Hermes state databases, the CLI prints a reminder
Run `$$nemoclaw gateway restart` to make the gateway open the restored databases.
-To clone a snapshot into a different sandbox name, pass `--to `.
-If the destination sandbox already exists, NemoClaw refuses to overwrite it unless you pass `--force`:
+To clone a snapshot into a different sandbox name, pass `--to `. If the destination sandbox already exists, NemoClaw refuses to overwrite it unless you pass `--force`:
```bash
$$nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone
$$nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes
```
-Cross-sandbox restore from a stopped source is available for Docker- and VM-driver sandboxes.
-For a stopped source, its registry entry must record both the sandbox image and a complete inference route; NemoClaw creates the destination from the recorded image.
-NemoClaw stops before creating or replacing the destination when either record is missing, and directs you to run `$$nemoclaw onboard` when no image is recorded.
-For a Kubernetes-driver source, the pod image must remain resolvable through its gateway.
+Cross-sandbox restore from a stopped source is available for Docker- and VM-driver sandboxes. For a stopped source, its registry entry must record both the sandbox image and a complete inference route; NemoClaw creates the destination from the recorded image. NemoClaw stops before creating or replacing the destination when either record is missing, and directs you to run `$$nemoclaw onboard` when no image is recorded. For a Kubernetes-driver source, the pod image must remain resolvable through its gateway.
-For a new destination, NemoClaw waits for the owning gateway to report the sandbox as Ready with a valid live identity.
-It checks that identity again immediately before registration.
-NemoClaw assigns the destination a new lifecycle generation instead of copying the source sandbox's generation.
+For a new destination, NemoClaw waits for the owning gateway to report the sandbox as Ready with a valid live identity. It checks that identity again immediately before registration. NemoClaw assigns the destination a new lifecycle generation instead of copying the source sandbox's generation.
-If the destination is not Ready with the same valid identity, the restore exits nonzero before registration or state restore.
-The OpenShell sandbox remains created but unregistered, so `--force` cannot select it for deletion.
-Run the owner-scoped deletion command printed by the failure:
+If the destination is not Ready with the same valid identity, the restore exits nonzero before registration or state restore. The OpenShell sandbox remains created but unregistered, so `--force` cannot select it for deletion. Run the exact owner-scoped deletion command printed by the failure:
```bash
openshell sandbox delete -g '' ''
@@ -210,13 +167,13 @@ openshell sandbox delete -g '' ''
After OpenShell deletes the destination, rerun the original `snapshot restore --to` command.
-For dashboard-enabled agents, NemoClaw allocates the destination sandbox its own dashboard port instead of reusing the source port.
-If no port is available, restore stops before deleting an existing `--force` destination.
+For dashboard-enabled agents, NemoClaw allocates the destination sandbox its own dashboard port instead of reusing the source port. If no port is available, restore stops before deleting an existing `--force` destination.
-NemoClaw also allocates the destination sandbox its own OpenAI-compatible API port from `8642` through `8652` instead of reusing the source port.
-If no port in that range is free, restore stops before deleting an existing `--force` destination.
-Run `openshell forward list` to read the destination sandbox's API port.
+ NemoClaw also allocates the destination sandbox its own OpenAI-compatible API port from `8642`
+ through `8652` instead of reusing the source port. If no port in that range is free, restore stops
+ before deleting an existing `--force` destination. Run `openshell forward list` to read the
+ destination sandbox's API port.
@@ -225,37 +182,27 @@ If the check fails, the command leaves the destination registered without restor
Correct the reported supervisor failure, then run `$$nemoclaw destroy` or rerun the restore with `--force`.
-The force-overwrite path restores and verifies lockdown on a destination with an active shields timer, then revokes that timer before it deletes the destination.
-It clears the remaining local shields state only after deletion succeeds, before a same-name replacement is created.
+The force-overwrite path restores and verifies lockdown on a destination with an active shields timer, then revokes that timer before it deletes the destination. It clears the remaining local shields state only after deletion succeeds, before a same-name replacement is created.
## Restore Agent Configuration Safely
-The `$$nemoclaw rebuild` command uses the same snapshot mechanism automatically.
-NemoClaw rejects unsafe symlinks and special files inside sandbox state during backup creation.
-It records multiply-linked regular files and archives each path as a separate regular file.
+The `$$nemoclaw rebuild` command uses the same snapshot mechanism automatically. NemoClaw rejects unsafe symlinks and special files inside sandbox state during backup creation. It records multiply-linked regular files and archives each path as a separate regular file.
Snapshot restore performs a targeted repair for legacy `.openclaw-data` symlinks that older images created.
Snapshots also preserve user-owned `openclaw.json` settings.
-During rebuild or restore, NemoClaw merges those settings with the freshly generated runtime config so current provider placeholders, messaging enablement, and gateway state win over stale snapshot values.
-If the restored config cannot be parsed or applied safely, NemoClaw stops the restore instead of replacing the generated config with an unsafe fallback.
+During rebuild or restore, NemoClaw merges those settings with the freshly generated runtime config so current provider placeholders, messaging enablement, and gateway state win over stale snapshot values. If the restored config cannot be parsed or applied safely, NemoClaw stops the restore instead of replacing the generated config with an unsafe fallback.
+
+OpenClaw's device identity keys and paired-device tokens are intentionally excluded from snapshots because backup sanitization scrubs them beyond use. Snapshot state replacement does not overwrite the destination sandbox's gateway pairing files, even when an older snapshot still contains them. After a cross-sandbox restore creates the destination, NemoClaw establishes gateway pairing and verifies it with an authenticated agent run. If verification fails, the restored state remains in the destination and the command exits nonzero. Run `$$nemoclaw connect` to retry pairing before you run an agent. OpenClaw regenerates its device identity on demand.
-OpenClaw's device identity keys and paired-device tokens are intentionally excluded from snapshots because backup sanitization scrubs them beyond use.
-Snapshot state replacement does not overwrite the destination sandbox's gateway pairing files, even when an older snapshot still contains them.
-After a cross-sandbox restore creates the destination, NemoClaw establishes gateway pairing and verifies it with an authenticated agent run.
-If verification fails, the restored state remains in the destination and the command exits nonzero.
-Run `$$nemoclaw connect` to retry pairing before you run an agent.
-OpenClaw regenerates its device identity on demand.
Credential-bearing Hermes files such as `auth.json` are intentionally excluded from snapshots.
NemoClaw-regenerated Hermes config files, including `config.yaml` and `.env`, are also excluded.
NemoClaw recreates model, provider, and messaging credentials from host-side onboarding and OpenShell provider state during rebuild.
-If a Hermes rebuild cannot validate or release its NemoClaw cron restore gate, NemoClaw preserves the state backup.
-If the rebuild already accepted the replacement sandbox, it also preserves the replacement journal.
-New Hermes turns and cron dispatch remain blocked while the gate exists.
+If a Hermes rebuild cannot validate or release its NemoClaw cron restore gate, NemoClaw preserves the state backup. If the rebuild already accepted the replacement sandbox, it also preserves the replacement journal. New Hermes turns and cron dispatch remain blocked while the gate exists.
Do not manually remove the root-owned cron restore marker.
@@ -266,31 +213,26 @@ If an independent Hermes operator drain exists, recovery leaves it active.
After recovery succeeds, rerun `rebuild` with the same replacement settings so NemoClaw can retire the replacement journal.
-After a rebuild restores `dashboard-home` or `profiles`, NemoClaw reruns the dashboard state migration before it reports the restore as complete.
-During rebuild restore, NemoClaw moves disjoint top-level entries from the legacy dashboard directory without replacing entries in the canonical profile.
-If an entry collides or migration otherwise fails, NemoClaw marks the restore incomplete instead of reporting success.
+After a rebuild restores `dashboard-home` or `profiles`, NemoClaw reruns the dashboard state migration before it reports the restore as complete. During rebuild restore, NemoClaw moves disjoint top-level entries from the legacy dashboard directory without replacing entries in the canonical profile. If an entry collides or migration otherwise fails, NemoClaw marks the restore incomplete instead of reporting success.
+
### Excluded Deep Agents State
-Credential-bearing Deep Agents files such as `.deepagents/.env` and user-authored `.deepagents/.mcp.json` are intentionally excluded from snapshots.
-Deep Agents auth state files such as `.deepagents/.state/auth.json` and `.deepagents/.state/chatgpt-auth.json` are also excluded because the managed launcher refuses to start when upstream credential state is present.
+Credential-bearing Deep Agents files such as `.deepagents/.env` and user-authored `.deepagents/.mcp.json` are intentionally excluded from snapshots. Deep Agents auth state files such as `.deepagents/.state/auth.json` and `.deepagents/.state/chatgpt-auth.json` are also excluded because the managed launcher refuses to start when upstream credential state is present.
-The managed `.deepagents/.nemoclaw-mcp.json` projection and `hooks.json` are excluded because NemoClaw reconstructs managed MCP state and disables executable Deep Agents Code hooks in the managed harness.
-NemoClaw recreates the current inference route headers, `models` and `update` tables, managed MCP projection state, and provider credentials from host-side onboarding and OpenShell provider state during rebuild.
+The managed `.deepagents/.nemoclaw-mcp.json` projection and `hooks.json` are excluded because NemoClaw reconstructs managed MCP state and disables executable Deep Agents Code hooks in the managed harness. NemoClaw recreates the current inference route headers, `models` and `update` tables, managed MCP projection state, and provider credentials from host-side onboarding and OpenShell provider state during rebuild.
### Restore Managed Deep Agents Configuration
-For a NemoClaw-managed Deep Agents image, NemoClaw restores only the allowlisted `ui.show_scrollbar`, `ui.show_url_open_toast`, `threads.relative_time`, and `threads.sort_order` preferences from the previous `config.toml` when their values pass validation.
-Unknown, runtime-controlled, executable, and security-sensitive backup keys are dropped instead of replacing freshly generated settings on that managed path.
+For a NemoClaw-managed Deep Agents image, NemoClaw restores only the allowlisted `ui.show_scrollbar`, `ui.show_url_open_toast`, `threads.relative_time`, and `threads.sort_order` preferences from the previous `config.toml` when their values pass validation. Unknown, runtime-controlled, executable, and security-sensitive backup keys are dropped instead of replacing freshly generated settings on that managed path.
-A Deep Agents target created from a custom Dockerfile restores `config.toml` as a whole file because the custom image owns its config schema.
-On the managed key-level restore path, malformed config, missing managed data, an unsafe link, or an unsafe file replacement fails the restore without falling back to a whole-file copy.
+A Deep Agents target created from a custom Dockerfile restores `config.toml` as a whole file because the custom image owns its config schema. On the managed key-level restore path, malformed config, missing managed data, an unsafe link, or an unsafe file replacement fails the restore without falling back to a whole-file copy.
### Validate Before Replacement
-Before a Deep Agents rebuild changes the sandbox, NemoClaw verifies the recorded inference route, provider, model, reasoning settings, web search selection, base image, and policy inputs.
-If a late check fails, NemoClaw restores the previous MCP state and keeps the existing sandbox intact.
+Before a Deep Agents rebuild changes the sandbox, NemoClaw verifies the recorded inference route, provider, model, reasoning settings, web search selection, base image, and policy inputs. If a late check fails, NemoClaw restores the previous MCP state and keeps the existing sandbox intact.
+
## Back Up Every Registered Sandbox
@@ -301,24 +243,11 @@ Run `$$nemoclaw backup-all` before broad maintenance such as `$$nemoclaw update`
$$nemoclaw backup-all
```
-`backup-all` walks the sandboxes registered on the host, creates a snapshot for each eligible running or temporarily started sandbox, and stores the snapshot bundles under `~/.nemoclaw/rebuild-backups//`.
-If a registered docker-driver sandbox's container is stopped, `backup-all` starts the container for the duration of the backup and returns it to its stopped state afterward.
-If the container cannot be returned to the stopped state, the backup run fails and reports that the container was left running.
-If a sandbox is not running and its container cannot be started this way, start the sandbox or its container and rerun `$$nemoclaw backup-all`.
-
-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.
-A sandbox that starts with Shields down remains down.
-If the timer expires during the transaction, the deadline gate blocks new mutations and waits for the 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.
-NemoClaw attempts to restore the previous Shields state before it processes the next sandbox, including when the backup fails.
-If lockdown cannot be restored, `backup-all` stops and does not process the remaining sandboxes.
-For an ordinary relock failure, correct the reported issue and follow the printed recovery command before rerunning `$$nemoclaw backup-all`.
-If NemoClaw reports that Backup Shields policy recovery failed, do not retry Shields up from the mutable live policy.
-Restore a trusted backup, recreate the sandbox, and then rerun `$$nemoclaw backup-all`.
-
-When a backup fails, NemoClaw identifies the affected state item and reports `permission denied`, `tar read error`, or `absent after extraction` when available.
-Use `$$nemoclaw snapshot list` and `$$nemoclaw snapshot restore` to inspect or restore one sandbox's bundles later.
+`backup-all` walks the sandboxes registered on the host, creates a snapshot for each eligible running or temporarily started sandbox, and stores the snapshot bundles under `~/.nemoclaw/rebuild-backups//`. If a registered docker-driver sandbox's container is stopped, `backup-all` starts the container for the duration of the backup and returns it to its stopped state afterward. If the container cannot be returned to the stopped state, the backup run fails and reports that the container was left running. If a sandbox is not running and its container cannot be started this way, start the sandbox or its container and rerun `$$nemoclaw backup-all`.
+
+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. A sandbox that starts with Shields down remains down. 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. NemoClaw attempts to restore the previous Shields state before it processes the next sandbox, including when the backup fails. If lockdown cannot be restored, `backup-all` stops and does not process the remaining sandboxes. For an ordinary relock failure, correct the reported issue and follow the printed recovery command before rerunning `$$nemoclaw backup-all`. If NemoClaw reports that Backup Shields policy recovery failed, do not retry Shields up from the mutable live policy. Restore a trusted backup, recreate the sandbox, and then rerun `$$nemoclaw backup-all`.
+
+When a backup fails, NemoClaw identifies the affected state item and reports `permission denied`, `tar read error`, or `absent after extraction` when available. Use `$$nemoclaw snapshot list` and `$$nemoclaw snapshot restore` to inspect or restore one sandbox's bundles later.
## Related Topics
diff --git a/docs/manage-sandboxes/manage-mcp-servers.mdx b/docs/manage-sandboxes/manage-mcp-servers.mdx
index 61772bdedaa..4cc214d9d3c 100644
--- a/docs/manage-sandboxes/manage-mcp-servers.mdx
+++ b/docs/manage-sandboxes/manage-mcp-servers.mdx
@@ -5,12 +5,21 @@ title: "Manage MCP Servers"
sidebar-title: "Manage MCP Servers"
description: "Inspect advertised tools and DNS pins, probe, rotate, restart, remove, rebuild, and destroy NemoClaw-managed MCP servers."
description-agent: "Explains managed MCP status, DNS pin drift, advertised tool discovery, credential-resolution probes, credential rotation, restart, removal, rebuild restoration, destroy recovery, and lifecycle locking. Use after an MCP server is registered."
-keywords: ["nemoclaw mcp status", "mcp dns pin drift", "mcp tool discovery", "nemoclaw mcp restart", "nemoclaw mcp remove", "mcp credential rotation"]
+keywords:
+ [
+ "nemoclaw mcp status",
+ "mcp dns pin drift",
+ "mcp tool discovery",
+ "nemoclaw mcp restart",
+ "nemoclaw mcp remove",
+ "mcp credential rotation",
+ ]
content:
type: "how_to"
skill:
priority: 50
---
+
Use the host-side MCP commands to inspect and change registered servers.
## List and Inspect Servers
@@ -20,19 +29,13 @@ $$nemoclaw my-sandbox mcp list
$$nemoclaw my-sandbox mcp status github --json
```
-`list --json` and `status --json` never include environment values.
-They report provider presence, provider attachment, whether live policy matches registered policy, environment readiness, and adapter registration state.
+`list --json` and `status --json` never include environment values. They report provider presence, provider attachment, whether live policy matches registered policy, environment readiness, and adapter registration state.
-The per-server `warnings` array reports unsupported stored boundaries, trusted-private DNS pin changes, and credential-resolution findings.
-The `env.missing` field lists recorded host variable names that are currently unset.
+The per-server `warnings` array reports unsupported stored boundaries, trusted-private DNS pin changes, and credential-resolution findings. The `env.missing` field lists recorded host variable names that are currently unset.
-An existing valid provider can remain ready when a host variable is unset because OpenShell retains the credential.
-The JSON value `support.mode: "bridge"` identifies the agent's config-adapter capability, not a host-side traffic bridge.
+An existing valid provider can remain ready when a host variable is unset because OpenShell retains the credential. The JSON value `support.mode: "bridge"` identifies the agent's config-adapter capability, not a host-side traffic bridge.
-For a trusted private server, status resolves the endpoint without changing managed state.
-Text output reports `private address pins: match`, `drift`, or `unresolved`.
-JSON output reports the same value in `trustedPrivateTarget.state` and includes the recorded pins.
-Status never adds a new address to the policy.
+For a trusted private server, status resolves the endpoint without changing managed state. Text output reports `private address pins: match`, `drift`, or `unresolved`. JSON output reports the same value in `trustedPrivateTarget.state` and includes the recorded pins. Status never adds a new address to the policy.
## Discover Advertised Tools
@@ -43,21 +46,13 @@ $$nemoclaw my-sandbox mcp status github --tools
$$nemoclaw my-sandbox mcp status github --tools --json
```
-The shared discovery runtime uses the managed registration's existing OpenShell credential provider and generated policy.
-OpenShell injects the credential at the policy boundary; it is not passed to the runtime through arguments, environment values, or an authorization option.
-The same runtime and thin adapter ancestry are used across OpenClaw, Hermes, and LangChain Deep Agents Code sandboxes.
+The shared discovery runtime uses the managed registration's existing OpenShell credential provider and generated policy. OpenShell injects the credential at the policy boundary; it is not passed to the runtime through arguments, environment values, or an authorization option. The same runtime and thin adapter ancestry are used across OpenClaw, Hermes, and LangChain Deep Agents Code sandboxes.
-Run discovery only against a configured endpoint you trust to advertise names while authenticated.
-The endpoint controls every returned tool name and can derive those names from the request or credential it receives; NemoClaw validates and bounds the returned text but cannot prove that an authenticated endpoint did not encode credential-derived data in an otherwise valid name.
+Run discovery only against a configured endpoint you trust to advertise names while authenticated. The endpoint controls every returned tool name and can derive those names from the request or credential it receives; NemoClaw validates and bounds the returned text but cannot prove that an authenticated endpoint did not encode credential-derived data in an otherwise valid name.
-A discovery result is a point-in-time list from the configured MCP server, not an attestation of the tools visible to the model in an active agent session.
-Agent configuration, progressive disclosure, runtime filters, and session state can further limit model-visible tools.
+A discovery result is a point-in-time list from the configured MCP server, not an attestation of the exact tools visible to the model in an active agent session. Agent configuration, progressive disclosure, runtime filters, and session state can further limit model-visible tools.
-NemoClaw runs the standard MCP `initialize`, `notifications/initialized`, and paginated `tools/list` lifecycle.
-It retains and returns tool names only, never prints the other tool-definition fields returned by `tools/list`, and never calls a tool.
-The client bounds total time, per-request time, cumulative response bytes, pages, tool count, cursor length, and tool-name length.
-It attempts to close the MCP session and transport on both success and failure.
-Cleanup errors do not replace the bounded discovery result.
+NemoClaw runs the standard MCP `initialize`, `notifications/initialized`, and paginated `tools/list` lifecycle. It retains and returns tool names only, never prints the other tool-definition fields returned by `tools/list`, and never calls a tool. The client bounds total time, per-request time, cumulative response bytes, pages, tool count, cursor length, and tool-name length. It attempts to close the MCP session and transport on both success and failure. Cleanup errors do not replace the bounded discovery result.
JSON output adds a per-server `toolDiscovery` object without changing the existing status fields:
@@ -72,44 +67,31 @@ JSON output adds a per-server `toolDiscovery` object without changing the existi
}
```
-Discovery is opt-in and sends authenticated network traffic to the configured endpoint.
-`--tools` requires one server name and suppresses the named-server credential-resolution probe that would otherwise run by default.
-Pass `--probe --tools` when you intentionally want both live checks.
+Discovery is opt-in and sends authenticated network traffic to the configured endpoint. `--tools` requires one server name and suppresses the named-server credential-resolution probe that would otherwise run by default. Pass `--probe --tools` when you intentionally want both live checks.
-An older sandbox image that does not contain the shared discovery client reports that a rebuild is required.
-Run `$$nemoclaw my-sandbox rebuild` and retry the command.
+An older sandbox image that does not contain the shared discovery client reports that a rebuild is required. Run `$$nemoclaw my-sandbox rebuild` and retry the command.
-A discovery failure sets `toolDiscovery.ok` to `false` and leaves the ordinary provider, policy, environment, and adapter status available.
-Bounded partial results set `truncated` to `true` and include a redacted `detail` value.
+A discovery failure sets `toolDiscovery.ok` to `false` and leaves the ordinary provider, policy, environment, and adapter status available. Bounded partial results set `truncated` to `true` and include a redacted `detail` value.
## Verify Credential Resolution
-Provider presence and metadata cannot prove that OpenShell rewrites the recorded resolver placeholder when a request leaves the sandbox.
-`mcp status ` requests a differential wire-level credential-resolution probe by default.
+Provider presence and metadata cannot prove that OpenShell rewrites the recorded resolver placeholder when a request leaves the sandbox. `mcp status ` requests a differential wire-level credential-resolution probe by default.
-Before sending probe traffic, NemoClaw verifies generated policy, expected provider attachment, provider ID, `nemoclaw-mcp-v1` type, valid resource version, and exactly one matching credential key.
-If readiness does not match, it reports `ok: null` with `probe skipped` and sends no request.
+Before sending probe traffic, NemoClaw verifies exact generated policy, expected provider attachment, provider ID, `nemoclaw-mcp-v1` type, valid resource version, and exactly one matching credential key. If readiness does not match, it reports `ok: null` with `probe skipped` and sends no request.
-When readiness passes, the probe sends the same idempotent MCP `initialize` request twice from inside the sandbox through the adapter runtime.
-One request carries the real placeholder header, and the control request carries a deliberately unresolvable literal bearer.
+When readiness passes, the probe sends the same idempotent MCP `initialize` request twice from inside the sandbox through the adapter runtime. One request carries the real placeholder header, and the control request carries a deliberately unresolvable literal bearer.
-A working rewrite makes the two requests reach the endpoint with different bearers.
-Only a placeholder HTTP 2xx paired with a rejected control verifies resolution because an accepted request proves a valid credential was on the wire.
+A working rewrite makes the two requests reach the endpoint with different bearers. Only a placeholder HTTP 2xx paired with a rejected control verifies resolution because an accepted request proves a valid credential was on the wire.
-Every non-2xx placeholder outcome is inconclusive.
-Identical HTTP 400, 401, or 403 rejections tell you to verify the stored credential first.
+Every non-2xx placeholder outcome is inconclusive. Identical HTTP 400, 401, or 403 rejections tell you to verify the stored credential first.
-For HTTP 401 or 403, a confirmed-valid credential means the host is not rewriting placeholders.
-HTTP 400 remains inconclusive because the endpoint may reject the probe request itself.
+For HTTP 401 or 403, a confirmed-valid credential means the host is not rewriting placeholders. HTTP 400 remains inconclusive because the endpoint may reject the probe request itself.
-The probe never captures or prints endpoint response bodies.
-It refuses to run against a persisted URL that no longer satisfies the authenticated-endpoint boundary.
+The probe never captures or prints endpoint response bodies. It refuses to run against a persisted URL that no longer satisfies the authenticated-endpoint boundary.
-The verdict appears as `provider.credentialResolution` in JSON and as a `credential resolution:` line in text output.
-Pass `--no-probe` to skip the probe or `--probe` to request it for every server in multi-server status.
+The verdict appears as `provider.credentialResolution` in JSON and as a `credential resolution:` line in text output. Pass `--no-probe` to skip the probe or `--probe` to request it for every server in multi-server status.
-The bare `mcp list` and `mcp status` forms never probe, so they stay fast.
-Endpoint outages, policy denials, timeouts, unreachable sandboxes, and endpoints that accept both probes report `ok: null` with evidence in `detail`.
+The bare `mcp list` and `mcp status` forms never probe, so they stay fast. Endpoint outages, policy denials, timeouts, unreachable sandboxes, and endpoints that accept both probes report `ok: null` with evidence in `detail`.
## Rotate a Credential
@@ -121,31 +103,21 @@ $$nemoclaw my-sandbox mcp restart github
unset GITHUB_MCP_TOKEN
```
-`restart` imports or verifies the endpointless `nemoclaw-mcp-v1` profile, applies the generated policy without a credential binding, updates or reuses the provider, and attaches it.
-It then applies the endpoint-bound policy, waits for credential readiness, and refreshes the adapter.
-An ambiguous or failed update is not treated as successful merely because another writer advanced the provider revision.
+`restart` imports or verifies the endpointless `nemoclaw-mcp-v1` profile, applies the generated policy without a credential binding, updates or reuses the provider, and attaches it. It then applies the endpoint-bound policy, waits for credential readiness, and refreshes the adapter. An ambiguous or failed update is not treated as successful merely because another writer advanced the provider revision.
-For a trusted-private entry, restart replays the address pins recorded by `mcp add`.
-It does not resolve that endpoint again or widen its policy from ambient DNS.
-For a public entry, restart resolves the hostname again and refreshes the generated policy with the current validated public addresses.
+For a trusted-private entry, restart replays the exact address pins recorded by `mcp add`. It does not resolve that endpoint again or widen its policy from ambient DNS. For a public entry, restart resolves the hostname again and refreshes the generated policy with the current validated public addresses.
-The raw value passes only through the OpenShell provider command's process environment and is not added to argv, NemoClaw state, or sandbox config.
-Revoke the old credential upstream after restart succeeds.
+The raw value passes only through the OpenShell provider command's process environment and is not added to argv, NemoClaw state, or sandbox config. Revoke the old credential upstream after restart succeeds.
If the provider was deleted, restart recreates it from the exported value.
-When the host variable is unset, restart reuses an existing provider whose current ID and credential-key metadata match the registry and whose type is `nemoclaw-mcp-v1`.
-If the provider is missing, export the recorded variable before retrying.
-If the provider has the profile-less legacy `generic` type, remove the server and add it again with the recorded variable exported.
-Restart and rebuild refuse to activate that provider because OpenShell cannot bind it to an endpoint.
+When the host variable is unset, restart reuses an existing provider whose current ID and credential-key metadata match the registry and whose type is `nemoclaw-mcp-v1`. If the provider is missing, export the recorded variable before retrying. If the provider has the profile-less legacy `generic` type, remove the server and add it again with the recorded variable exported. Restart and rebuild refuse to activate that provider because OpenShell cannot bind it to an endpoint.
-Running restart without a server name refreshes every managed server.
-Export only the variables whose credentials you intend to replace.
+Running restart without a server name refreshes every managed server. Export only the variables whose credentials you intend to replace.
## Change Endpoint Pins
-For a trusted-private server, review every destination change before NemoClaw records new pins.
-Neither status, restart, rebuild, nor restore changes the recorded address set.
+For a trusted-private server, review every destination change before NemoClaw records new pins. Neither status, restart, rebuild, nor restore changes the recorded address set.
If the endpoint moves to another address, remove and re-add the server:
@@ -159,8 +131,7 @@ $$nemoclaw my-sandbox mcp add local-tools \
unset LOCAL_MCP_TOKEN
```
-Removing the server deletes the registry-owned provider, policy, and adapter state after the existing ownership checks pass.
-The re-add performs a new DNS preflight and records the reviewed address set.
+Removing the server deletes the exact provider and adapter state recorded for that bridge and removes its generated key from the current OpenShell policy. The re-add performs a new DNS preflight and records the reviewed exact address set.
## Remove a Server
@@ -168,70 +139,43 @@ The re-add performs a new DNS preflight and records the reviewed address set.
$$nemoclaw my-sandbox mcp remove github
```
-Removing a server blocks new requests and reconnects but does not terminate a response or SSE stream that is already open.
-For immediate revocation, revoke the upstream credential first, then run `$$nemoclaw rebuild --yes` or destroy the sandbox to terminate an existing stream.
+Removing a server blocks new requests and reconnects but does not terminate a response or SSE stream that is already open. For immediate revocation, revoke the upstream credential first, then run `$$nemoclaw rebuild --yes` or destroy the sandbox to terminate an existing stream.
-`remove --force` may remove a modified same-name adapter entry so an operator can clear local config.
-Provider deletion still requires the recorded provider ID and credential key plus an accepted managed provider type.
-Legacy `generic` providers are accepted only for cleanup.
+`remove --force` may remove a modified same-name adapter entry so an operator can clear local config. Provider deletion still requires the recorded provider ID and credential key plus an accepted managed provider type. Exact legacy `generic` providers are accepted only for cleanup.
-Policy deletion still requires live policy content to equal the recorded owned content.
-Force never claims an unowned or drifted provider or same-key live policy.
+Policy deletion still requires exact owned content. Force never claims an unowned or drifted provider or same-key live policy.
-For an ordinary managed entry, NemoClaw cleans up the adapter, removes the live policy only when it equals the recorded owned policy, and then detaches its provider because OpenShell rejects detach while `credential_binding.provider` still references that provider.
-For a stored legacy entry whose credential name is no longer accepted, it first detaches the provider so adapter cleanup cannot start with that credential attached.
-It deletes the provider only after detach and credential-removal checks succeed.
+For an ordinary managed entry, NemoClaw cleans up the adapter, removes the exact owned policy, and then detaches its provider because OpenShell rejects detach while `credential_binding.provider` still references that provider. For a stored legacy entry whose credential name is no longer accepted, it first detaches the exact provider so adapter cleanup cannot start with that credential attached. It deletes the provider only after detach and credential-removal checks succeed.
-If cleanup leaves a residual, the command exits nonzero and preserves the registry entry so cleanup can be retried.
-It never detaches the provider from other sandboxes.
+If cleanup leaves a residual, the command exits nonzero and preserves the registry entry so cleanup can be retried. It never detaches the provider from other sandboxes.
## Rebuild with Managed MCP State
-`rebuild` preserves providers that match the recorded ID and credential-key metadata and the active `nemoclaw-mcp-v1` type.
-It removes adapter entries and live policies that equal the recorded owned policies, then detaches providers before replacing the sandbox.
-Before changing each managed adapter, a fresh sandbox process must expose a revision-scoped OpenShell credential placeholder for that adapter.
-If an observation is absent, unscoped, or unavailable, NemoClaw leaves the affected adapter and every provider unchanged.
-It attempts to restore adapter entries prepared earlier in the operation and reports rollback failures.
-It does not substitute the provider resource version for the credential revision.
-Follow the reported [credential-revision recovery](../../reference/troubleshoot-mcp-servers#rebuild-or-destroy-cannot-prove-a-credential-revision), then retry rebuild.
-Restoration applies the credential-free policy, reattaches each provider, applies the endpoint-bound policy, waits for credential readiness, and restores adapters.
-For a trusted-private entry, the restored policy uses the recorded address pins and does not widen them from current DNS answers.
-Public entries continue to resolve and validate their endpoint addresses during restoration.
+`rebuild` preserves providers that match the recorded ID and credential-key metadata and the active `nemoclaw-mcp-v1` type. It removes adapter entries and exact owned policies, then detaches providers before replacing the sandbox. Before changing each managed adapter, a fresh sandbox process must expose a revision-scoped OpenShell credential placeholder for that adapter. If an observation is absent, unscoped, or unavailable, NemoClaw leaves the affected adapter and every provider unchanged. It attempts to restore adapter entries prepared earlier in the operation and reports rollback failures. It does not substitute the provider resource version for the credential revision. Follow the reported [credential-revision recovery](../../reference/troubleshoot-mcp-servers#rebuild-or-destroy-cannot-prove-a-credential-revision), then retry rebuild. Restoration applies the credential-free policy, reattaches each provider, applies the endpoint-bound policy, waits for credential readiness, and restores adapters. For a trusted-private entry, the restored policy uses the recorded exact address pins and does not widen them from current DNS answers. Public entries continue to resolve and validate their endpoint addresses during restoration.
NemoClaw revalidates the prepared Deep Agents replacement after MCP preparation and before stopping inference or deleting the old sandbox.
If that check fails, it restores prior MCP attachment and adapter state and keeps the old sandbox.
-For a Deep Agents v1 image, remove, rebuild, and destroy scrub only the matching registry-owned legacy entry from `.deepagents/.mcp.json`.
-Other user servers and unrelated top-level content remain unchanged.
+For a Deep Agents v1 image, remove, rebuild, and destroy scrub only the matching registry-owned legacy entry from `.deepagents/.mcp.json`. Other user servers and unrelated top-level content remain unchanged.
The replacement image must expose managed MCP capability v2 before NemoClaw restores MCP runtime state.
+
-If sandbox replacement fails, NemoClaw attempts to restore the previous attachment and adapter state at the path used by the surviving image.
-A later `mcp restart` can retry an incomplete post-rebuild restore.
+If sandbox replacement fails, NemoClaw attempts to restore the previous attachment and adapter state at the path used by the surviving image. A later `mcp restart` can retry an incomplete post-rebuild restore.
## Destroy a Sandbox with MCP State
-Destroy removes adapter entries and live policies that equal the recorded owned policies, then detaches providers that match recorded metadata before asking OpenShell to delete the sandbox.
-Before changing each managed adapter, a fresh sandbox process must expose a revision-scoped OpenShell credential placeholder for that adapter.
-If an observation is absent, unscoped, or unavailable, NemoClaw leaves the affected adapter and every provider unchanged.
-It attempts to restore adapter entries prepared earlier in the operation and reports rollback failures.
-Follow the reported [credential-revision recovery](../../reference/troubleshoot-mcp-servers#rebuild-or-destroy-cannot-prove-a-credential-revision), then retry destroy.
-If deletion is refused, NemoClaw attempts to restore previous MCP state, reports rollback failures, and preserves recovery state.
-Provider deletion and registry cleanup happen only after OpenShell confirms the sandbox is gone.
+Destroy removes adapter entries and exact owned policies, then detaches providers that match recorded metadata before asking OpenShell to delete the sandbox. Before changing each managed adapter, a fresh sandbox process must expose a revision-scoped OpenShell credential placeholder for that adapter. If an observation is absent, unscoped, or unavailable, NemoClaw leaves the affected adapter and every provider unchanged. It attempts to restore adapter entries prepared earlier in the operation and reports rollback failures. Follow the reported [credential-revision recovery](../../reference/troubleshoot-mcp-servers#rebuild-or-destroy-cannot-prove-a-credential-revision), then retry destroy. If deletion is refused, NemoClaw attempts to restore previous MCP state, reports rollback failures, and preserves recovery state. Provider deletion and registry cleanup happen only after OpenShell confirms the sandbox is gone.
-An interrupted destroy can leave a durable transaction marker.
-A prepared-only marker means deletion is not durably confirmed.
-If the sandbox is still live, remove each affected server with force until the managed manifest is empty:
+An interrupted destroy can leave a durable transaction marker. A prepared-only marker means deletion is not durably confirmed. If the sandbox is still live, remove each affected server with force until the managed manifest is empty:
```bash
$$nemoclaw my-sandbox mcp remove --force
```
-A pending marker means the registry records that OpenShell deletion was already confirmed.
-`mcp remove --force` refuses that state because provider or policy cleanup can still be owed.
-Finish the idempotent destroy instead:
+A pending marker means the registry records that OpenShell deletion was already confirmed. `mcp remove --force` refuses that state because provider or policy cleanup can still be owed. Finish the idempotent destroy instead:
```bash
$$nemoclaw my-sandbox destroy
@@ -257,11 +201,9 @@ If a mutating command times out waiting for the per-sandbox lifecycle lock, conf
Every mutating command recovers a lock whose local process is provably dead or whose PID now has a different process-start identity.
-NemoClaw does not expose a force-unlock flag.
-A live owner, different host or PID namespace, or incomplete legacy owner record fails closed because removing it could overlap a provider, policy, or adapter mutation.
+NemoClaw does not expose a force-unlock flag. A live owner, different host or PID namespace, or incomplete legacy owner record fails closed because removing it could overlap a provider, policy, or adapter mutation.
-For state shared across hosts or PID namespaces, resolve the owner on that host or stop sharing the state directory before retrying.
-Do not delete the lock file while ownership is ambiguous.
+For state shared across hosts or PID namespaces, resolve the owner on that host or stop sharing the state directory before retrying. Do not delete the lock file while ownership is ambiguous.
## Related Topics
diff --git a/docs/manage-sandboxes/manage-messaging-channels.mdx b/docs/manage-sandboxes/manage-messaging-channels.mdx
index c5bad7afcdd..98befeb6050 100644
--- a/docs/manage-sandboxes/manage-messaging-channels.mdx
+++ b/docs/manage-sandboxes/manage-messaging-channels.mdx
@@ -5,29 +5,31 @@ title: "Manage Messaging Channels"
sidebar-title: "Manage Messaging Channels"
description: "Rotate, pause, resume, remove, and conflict-check messaging channels on an existing sandbox."
description-agent: "Explains channel credential rotation, destructive removal, pause and resume behavior, duplicate credential and port conflicts, and full messaging stop behavior. Use after a channel is configured."
-keywords: ["nemoclaw channels remove", "nemoclaw channels stop", "messaging credential rotation", "channel conflicts"]
+keywords:
+ [
+ "nemoclaw channels remove",
+ "nemoclaw channels stop",
+ "messaging credential rotation",
+ "channel conflicts",
+ ]
content:
type: "how_to"
agent-variants: ["openclaw", "hermes"]
---
+
Use host-side channel commands to change a configured messaging channel.
## Rotate Credentials
-Running `channels add` for a channel that is already configured overwrites stored tokens and registers the updated bridge provider.
-Rebuild the sandbox after the update so the image reflects the current channel set.
+Running `channels add` for a channel that is already configured overwrites stored tokens and registers the updated bridge provider. Rebuild the sandbox after the update so the image reflects the current channel set.
-For WeChat, the cached-token shortcut applies.
-Remove WeChat first when you intend to acquire a fresh account through a new QR scan.
+For WeChat, the cached-token shortcut applies. Remove WeChat first when you intend to acquire a fresh account through a new QR scan.
-For Google Chat, re-add the channel and paste the replacement service-account JSON.
-NemoClaw updates the gateway-side refresh material.
-The sandbox keeps only the OpenShell credential placeholder.
-OpenShell keeps refreshed access tokens at the gateway and substitutes them at approved egress boundaries.
+For Google Chat, re-add the channel and paste the replacement service-account JSON. NemoClaw updates the gateway-side refresh material. The sandbox keeps only the OpenShell credential placeholder. OpenShell keeps refreshed access tokens at the gateway and substitutes them at approved egress boundaries.
-Re-adding Google Chat prompts again for the project ID, complete Pub/Sub subscription name, and email sender allowlist.
-It does not create a public webhook endpoint.
+ Re-adding Google Chat prompts again for the project ID, complete Pub/Sub subscription name, and
+ email sender allowlist. It does not create a public webhook endpoint.
For detailed token rotation procedures, refer to [Credential Rotation](../../security/credential-rotation).
@@ -42,8 +44,7 @@ $$nemoclaw my-assistant channels remove wechat
$$nemoclaw my-assistant channels remove teams
```
-`channels remove wechat` clears the bot token, deletes the `-wechat-bridge` provider, and removes `wechat` from the enabled-channel set.
-The next rebuild omits WeChat configuration and per-account state files.
+`channels remove wechat` clears the bot token, deletes the `-wechat-bridge` provider, and removes `wechat` from the enabled-channel set. The next rebuild omits WeChat configuration and per-account state files.
`channels remove googlechat` detaches and deletes the `-googlechat-bridge` provider before the rebuild removes Google Chat configuration and the matching policy preset.
@@ -54,8 +55,8 @@ If endpoint teardown fails, the command exits nonzero without changing the chann
-Hermes Google Chat has no dedicated host-side endpoint to stop.
-The next rebuild omits its Pub/Sub project, subscription, sender allowlist, and runtime adapter configuration.
+ Hermes Google Chat has no dedicated host-side endpoint to stop. The next rebuild omits its Pub/Sub
+ project, subscription, sender allowlist, and runtime adapter configuration.
For in-sandbox QR-paired channels such as WhatsApp, `channels remove` destructively clears the session directory before rebuild so stale auth files do not reconnect the channel.
@@ -68,13 +69,11 @@ The cleanup targets `/sandbox/.openclaw//`.
The cleanup targets `/sandbox/.hermes/platforms//`.
-It tries `openshell sandbox exec` and falls back to SSH if the first transport does not produce the success sentinel.
-If neither transport can reach a running sandbox, the command exits nonzero and asks you to start the sandbox and rerun it.
+It tries `openshell sandbox exec` and falls back to SSH if the first transport does not produce the success sentinel. If neither transport can reach a running sandbox, the command exits nonzero and asks you to start the sandbox and rerun it.
-NemoClaw leaves the registry, policy preset, and `session.policyPresets` unchanged on that failure path so a later retry can complete cleanly.
+NemoClaw leaves the registry and current OpenShell policy unchanged on that failure path so a later retry can complete cleanly.
-`channels remove whatsapp` clears the client-side Baileys session but cannot deregister the linked device with WhatsApp's servers after the local connection is gone.
-The phone continues to list the sandbox as a Linked Device until you remove it manually or WhatsApp's 14-day inactivity timeout expires.
+`channels remove whatsapp` clears the client-side Baileys session but cannot deregister the linked device with WhatsApp's servers after the local connection is gone. The phone continues to list the sandbox as a Linked Device until you remove it manually or WhatsApp's 14-day inactivity timeout expires.
Remove the phone entry before pairing the same account with another sandbox.
@@ -90,69 +89,66 @@ $$nemoclaw my-assistant channels start wechat
```
-For WeChat, `channels stop wechat` followed by rebuild keeps the per-account state under `/sandbox/.openclaw/openclaw-weixin/accounts/` even though the bridge is no longer wired into `openclaw.json`.
+ For WeChat, `channels stop wechat` followed by rebuild keeps the per-account state under
+ `/sandbox/.openclaw/openclaw-weixin/accounts/` even though the bridge is no longer wired into
+ `openclaw.json`.
-For WeChat, `channels stop wechat` followed by rebuild keeps the per-account state under `/sandbox/.hermes/` even though the bridge is no longer wired into Hermes config.
+ For WeChat, `channels stop wechat` followed by rebuild keeps the per-account state under
+ `/sandbox/.hermes/` even though the bridge is no longer wired into Hermes config.
-A later `channels start wechat` plus rebuild revives the bridge against the same iLink account without a fresh QR scan.
-The bot token remains in the OpenShell provider across the stop and start cycle.
+A later `channels start wechat` plus rebuild revives the bridge against the same iLink account
+without a fresh QR scan. The bot token remains in the OpenShell provider across the stop and start
+cycle.
Google Chat stop and start cycles also preserve the bridge provider and its gateway-side refresh material.
-They preserve the dedicated public webhook endpoint so the Google Cloud configuration can keep the same URL.
-The next rebuild reuses that provider without requiring the service-account JSON again.
-`$$nemoclaw tunnel stop` does not stop the dedicated Google Chat endpoint.
-It controls the separate full-dashboard tunnel.
+ They preserve the dedicated public webhook endpoint so the Google Cloud configuration can keep the
+ same URL. The next rebuild reuses that provider without requiring the service-account JSON again.
+ `$$nemoclaw tunnel stop` does not stop the dedicated Google Chat endpoint. It controls the
+ separate full-dashboard tunnel.
-They preserve the project ID, Pub/Sub subscription name, and email sender allowlist.
-The next rebuild reuses the bridge provider without requiring the service-account JSON again.
-Hermes Google Chat does not use the dedicated webhook endpoint or `$$nemoclaw tunnel` commands.
+ They preserve the project ID, Pub/Sub subscription name, and email sender allowlist. The next
+ rebuild reuses the bridge provider without requiring the service-account JSON again. Hermes Google
+ Chat does not use the dedicated webhook endpoint or `$$nemoclaw tunnel` commands.
-When `channels start` re-enables a channel, NemoClaw records the channel as enabled in the messaging plan.
-The rebuild attaches the existing bridge provider before applying its matching built-in policy preset to the replacement sandbox.
-While a channel remains stopped, the rebuild omits its runtime configuration, token upsert, and channel startup effects.
-Generic providers and refresh bridges remain detached.
+When `channels start` re-enables a channel, NemoClaw records the channel as enabled in the messaging plan. The rebuild attaches the existing bridge provider before applying its matching built-in policy preset to the replacement sandbox. While a channel remains stopped, the rebuild omits its runtime configuration, token upsert, and channel startup effects. Generic providers and refresh bridges remain detached.
+
-The rebuild also omits the stopped channel's inactive built-in messaging preset.
-Exact custom policies remain preserved for separate replay, including a custom policy whose name matches a built-in messaging preset.
-For stopped Hermes Discord, a preserved custom credential-bound policy requires the exact validated static provider, so the rebuild retains and attaches only that provider without starting Discord or recreating its credentials.
-A missing or incompatible required provider stops the rebuild before the replacement can use the policy.
+ The rebuild also omits the stopped channel's inactive built-in messaging preset from the
+ command-time plan. The messaging plan does not persist policy references; rebuild starts from the
+ current OpenShell policy and derives any requested channel change from current manifests. For
+ stopped Hermes Discord, a preserved custom credential-bound policy requires the exact validated
+ static provider, so the rebuild retains and attaches only that provider without starting Discord
+ or recreating its credentials. A missing or incompatible required provider stops the rebuild
+ before the replacement can use the policy.
-If the command queues the change without rebuilding, the running sandbox keeps its existing bridge and network policy until you rebuild it.
+If the command queues the change without rebuilding, the running sandbox keeps its existing bridge
+and network policy until you rebuild it.
## Avoid Cross-Sandbox Conflicts
-NemoClaw checks only the sandboxes recorded in the selected OpenShell gateway's sandbox registry.
-It cannot detect or prevent Slack credential reuse across independent OpenShell gateways.
+ NemoClaw checks only the sandboxes recorded in the selected OpenShell gateway's sandbox registry.
+ It cannot detect or prevent Slack credential reuse across independent OpenShell gateways.
-Use distinct credentials and resources for each active messaging sandbox.
-Follow these channel-specific rules:
+Use distinct credentials and resources for each active messaging sandbox. Follow these channel-specific rules:
- Use a distinct iLink `accountId` for each WeChat sandbox.
- Run only one active Slack sandbox on each OpenShell gateway.
- Use distinct bot and Socket Mode app tokens across OpenShell gateways.
- Use a different local webhook port for each Microsoft Teams sandbox.
-When you onboard, rebuild, or add a channel, the command aborts on a conflict or an incomplete required check within the selected OpenShell gateway's sandbox registry.
-Legacy entries without credential hashes count as incomplete.
-An unreadable messaging registry also causes onboarding and rebuild to abort.
-Onboarding and rebuild have no conflict override.
+When you onboard, rebuild, or add a channel, the command aborts on a conflict or an incomplete required check within the selected OpenShell gateway's sandbox registry. Legacy entries without credential hashes count as incomplete. An unreadable messaging registry also causes onboarding and rebuild to abort. Onboarding and rebuild have no conflict override.
-For `channels add` only, `--force` overrides conflict and incomplete-check aborts.
-Use it only when you accept the duplicate-consumer or shared-resource risk.
-Rerun `channels add ` with the intended token to refresh stored non-secret identity metadata.
+For `channels add` only, `--force` overrides conflict and incomplete-check aborts. Use it only when you accept the duplicate-consumer or shared-resource risk. Rerun `channels add ` with the intended token to refresh stored non-secret identity metadata.
-Before a rebuild, NemoClaw checks the messaging plan before backup or deletion.
-A conflict leaves the original sandbox intact.
-Resolve any conflict, then rerun the operation.
-`$$nemoclaw status` reports cross-sandbox overlaps within the selected OpenShell gateway's sandbox registry.
+Before a rebuild, NemoClaw checks the messaging plan before backup or deletion. A conflict leaves the original sandbox intact. Resolve any conflict, then rerun the operation. `$$nemoclaw status` reports cross-sandbox overlaps within the selected OpenShell gateway's sandbox registry.
## Stop All Delivery
@@ -163,11 +159,15 @@ Use `channels stop` for an individual bridge or stop the sandbox when you need t
The deprecated full `$$nemoclaw stop` command also attempts to release an unshared OpenShell gateway port whose ownership NemoClaw can verify.
Stopping the in-sandbox gateway stops all channel delivery for that sandbox until you restart the sandbox or gateway.
+
-`$$nemoclaw tunnel stop` stops the dashboard tunnel services that `$$nemoclaw tunnel start` created without stopping the supervisor-owned Hermes gateway, agent-owned host forwards, or managed OpenShell gateway port.
-The deprecated full `$$nemoclaw stop` command attempts to stop host forwards and safely release an unshared OpenShell gateway port while the Hermes gateway remains under sandbox supervision.
+ `$$nemoclaw tunnel stop` stops the dashboard tunnel services that `$$nemoclaw tunnel start`
+ created without stopping the supervisor-owned Hermes gateway, agent-owned host forwards, or
+ managed OpenShell gateway port. The deprecated full `$$nemoclaw stop` command attempts to stop
+ host forwards and safely release an unshared OpenShell gateway port while the Hermes gateway
+ remains under sandbox supervision.
Full stop preserves a shared gateway and fails closed without releasing its port when ownership is ambiguous.
diff --git a/docs/manage-sandboxes/recover-rebuild-sandboxes.mdx b/docs/manage-sandboxes/recover-rebuild-sandboxes.mdx
index 031c9a589b9..ad7c940939d 100644
--- a/docs/manage-sandboxes/recover-rebuild-sandboxes.mdx
+++ b/docs/manage-sandboxes/recover-rebuild-sandboxes.mdx
@@ -11,6 +11,7 @@ content:
skill:
priority: 30
---
+
Use the lightest recovery operation that repairs the sandbox while preserving its supported state.
## Restart a Stopped Sandbox Container
@@ -21,13 +22,13 @@ If NemoClaw reports that a Docker-driver sandbox is stopped, restart the existin
$$nemoclaw start
```
-This path preserves the sandbox workspace and repairs the agent runtime and host-side forwards after the container starts.
-If the container is paused, follow the printed `docker unpause` guidance instead.
-If Docker no longer has the container, follow the printed `rebuild --yes` guidance so NemoClaw can recreate the sandbox from its recorded metadata.
+This path preserves the sandbox workspace and repairs the agent runtime and host-side forwards after the container starts. If the container is paused, follow the printed `docker unpause` guidance instead. If Docker no longer has the container, follow the printed `rebuild --yes` guidance so NemoClaw can recreate the sandbox from its recorded metadata.
-The `start` command returns success only after it authenticates the recovered agent runtime, OpenShell reports the sandbox ready, and host-side port forwards pass their checks.
-If a check fails, the command exits nonzero, identifies the failure, and prints recovery guidance before you retry `start`.
+ The `start` command returns success only after it authenticates the recovered agent runtime,
+ OpenShell reports the sandbox ready, and host-side port forwards pass their checks. If a check
+ fails, the command exits nonzero, identifies the failure, and prints recovery guidance before you
+ retry `start`.
@@ -39,23 +40,17 @@ If the sandbox has shields up and the OpenClaw gateway does not start after the
$$nemoclaw shields down
```
-While holding the config mutation lock, NemoClaw confirms that no startup process runs and no readiness lease exists.
-Only then does it accept `shields down`.
-Other locked-config operations still require the lease.
-This failed-startup recovery path requires a sandbox image that includes the in-container OpenClaw config and state guards.
-If NemoClaw reports that the config guard is absent, upgrade the CLI.
-Then rebuild the sandbox before you retry recovery.
-After shields are down, start the sandbox again.
-When the OpenClaw gateway is healthy, rerun `shields up`.
+While holding the config mutation lock, NemoClaw confirms that no startup process runs and no readiness lease exists. Only then does it accept `shields down`. Other locked-config operations still require the lease. This failed-startup recovery path requires a sandbox image that includes the in-container OpenClaw config and state guards. If NemoClaw reports that the config guard is absent, upgrade the CLI. Then rebuild the sandbox before you retry recovery. After shields are down, start the sandbox again. When the OpenClaw gateway is healthy, rerun `shields up`.
+
## Recover the Agent Runtime
-`recover` can start an existing stopped Docker-driver container before it repairs the agent runtime.
-It starts only a non-paused container that Docker still associates with the registered sandbox.
-It leaves a running or paused container unchanged.
-If Docker cannot start the container, recovery continues to the OpenShell readiness check and reports the resulting failure.
+ `recover` can start an existing stopped Docker-driver container before it repairs the agent
+ runtime. It starts only a non-paused container that Docker still associates with the registered
+ sandbox. It leaves a running or paused container unchanged. If Docker cannot start the container,
+ recovery continues to the OpenShell readiness check and reports the resulting failure.
@@ -65,10 +60,7 @@ If `$$nemoclaw status` reports the sandbox container or gateway is not ru
$$nemoclaw recover
```
-The command repairs a stopped in-sandbox gateway and re-establishes the dashboard port-forward in one step.
-It is idempotent and safe to script.
-If the gateway is already healthy, `recover` exits after the probe and does not restart it.
-If the host forward is already active, recovery accepts it only after OpenShell ownership is reconciled and the local endpoint is reachable.
+The command repairs a stopped in-sandbox gateway and re-establishes the dashboard port-forward in one step. It is idempotent and safe to script. If the gateway is already healthy, `recover` exits after the probe and does not restart it. If the host forward is already active, recovery accepts it only after OpenShell ownership is reconciled and the local endpoint is reachable.
Use `gateway restart` when you intentionally need a supported OpenClaw gateway to reload runtime configuration or plugins.
@@ -76,9 +68,8 @@ Use `gateway restart` when you intentionally need a supported OpenClaw gateway t
$$nemoclaw gateway restart
```
-The restart command asks the topology-specific controller to stop the tracked gateway child, wait for the entrypoint to launch a replacement, and prove listener and HTTP health.
-The host then checks or recovers host-side dashboard, messaging, and agent forwards.
-Refer to [`$$nemoclaw recover`](../../reference/commands#$$nemoclaw-name-recover) and [`$$nemoclaw gateway restart`](../../reference/commands#$$nemoclaw-name-gateway-restart) for details.
+The restart command asks the topology-specific controller to stop the tracked gateway child, wait for the entrypoint to launch a replacement, and prove listener and HTTP health. The host then checks or recovers host-side dashboard, messaging, and agent forwards. Refer to [`$$nemoclaw recover`](../../reference/commands#$$nemoclaw-name-recover) and [`$$nemoclaw gateway restart`](../../reference/commands#$$nemoclaw-name-gateway-restart) for details.
+
@@ -88,20 +79,9 @@ If `$$nemoclaw status` reports the sandbox container or Hermes gateway is
$$nemoclaw recover
```
-The command repairs a stopped in-sandbox gateway and re-establishes the dashboard port-forward in one step.
-It is idempotent and safe to script.
-If the gateway is already healthy, `recover` does not restart it.
-If the host forward is already active, recovery accepts it only after OpenShell ownership is reconciled and the local endpoint is reachable.
-
-Before it repairs the gateway, `recover` checks for a NemoClaw cron restore gate or release recovery record left by an interrupted rebuild.
-The gate continues to block new Hermes turns and cron dispatch across gateway and container restarts in the same sandbox.
-If release rollback could not restore the gate, `recover` uses the root-owned recovery record to reacquire it before gateway repair can start dispatch.
-After gateway repair, `recover` waits for active agent work to finish and validates the restored cron jobs and scripts.
-It clears NemoClaw-owned gate and release recovery state only after validation succeeds.
-If no independent operator drain exists, successful recovery prints `Hermes cron dispatch resumed after restored jobs and scripts were validated.`
-If an operator drain exists, recovery prints `Hermes cron restore gate cleared; the independent operator drain remains active.`
-The command does not own or clear the Hermes operator drain, so new Hermes turns and cron dispatch remain blocked while that drain is active.
-If gate reacquisition or cron validation fails, `recover` exits nonzero and retains the recovery state for another attempt.
+The command repairs a stopped in-sandbox gateway and re-establishes the dashboard port-forward in one step. It is idempotent and safe to script. If the gateway is already healthy, `recover` does not restart it. If the host forward is already active, recovery accepts it only after OpenShell ownership is reconciled and the local endpoint is reachable.
+
+Before it repairs the gateway, `recover` checks for a NemoClaw cron restore gate or release recovery record left by an interrupted rebuild. The gate continues to block new Hermes turns and cron dispatch across gateway and container restarts in the same sandbox. If release rollback could not restore the gate, `recover` uses the root-owned recovery record to reacquire it before gateway repair can start dispatch. After gateway repair, `recover` waits for active agent work to finish and validates the restored cron jobs and scripts. It clears NemoClaw-owned gate and release recovery state only after validation succeeds. If no independent operator drain exists, successful recovery prints `Hermes cron dispatch resumed after restored jobs and scripts were validated.` If an operator drain exists, recovery prints `Hermes cron restore gate cleared; the independent operator drain remains active.` The command does not own or clear the Hermes operator drain, so new Hermes turns and cron dispatch remain blocked while that drain is active. If gate reacquisition or cron validation fails, `recover` exits nonzero and retains the recovery state for another attempt.
Portable Hermes recovery follows the exact receipt-bound start, authenticated-health, and rollback contract in the [`recover` command reference](../../reference/commands#nemoclaw-name-recover).
@@ -111,36 +91,22 @@ Use `gateway restart` when you intentionally need a supported Hermes gateway to
$$nemoclaw gateway restart
```
-The restart command asks the topology-specific controller to stop the tracked gateway child, wait for the entrypoint to launch a replacement, and prove listener and HTTP health.
-The host then checks or recovers host-side dashboard, messaging, and agent forwards.
+The restart command asks the topology-specific controller to stop the tracked gateway child, wait for the entrypoint to launch a replacement, and prove listener and HTTP health. The host then checks or recovers host-side dashboard, messaging, and agent forwards.
+
+For Hermes, the entrypoint supervisor owns the gateway, dashboard process, internal API relay, dashboard relay, and gateway log stream. The nonroot managed supervisor repairs those processes continuously, stops an alive but deaf gateway after four consecutive failed health checks, and quarantines relaunch after five exits within 60 seconds until sandbox recreation.
-For Hermes, the entrypoint supervisor owns the gateway, dashboard process, internal API relay, dashboard relay, and gateway log stream.
-The nonroot managed supervisor repairs those processes continuously, stops an alive but deaf gateway after four consecutive failed health checks, and quarantines relaunch after five exits within 60 seconds until sandbox recreation.
+The host does not start the in-sandbox processes independently. Refer to [`$$nemoclaw recover`](../../reference/commands#$$nemoclaw-name-recover) and [`$$nemoclaw gateway restart`](../../reference/commands#$$nemoclaw-name-gateway-restart) for details.
-The host does not start the in-sandbox processes independently.
-Refer to [`$$nemoclaw recover`](../../reference/commands#$$nemoclaw-name-recover) and [`$$nemoclaw gateway restart`](../../reference/commands#$$nemoclaw-name-gateway-restart) for details.
Recovery uses registry-scoped privileged direct-container control and does not fall back to ordinary `openshell sandbox exec` or a manual in-sandbox relaunch.
For a local Docker-driver sandbox whose container still uses the legacy keepalive startup, `recover` can transactionally recreate the registered container with a credential-free managed startup command.
-NemoClaw keeps the previous container available throughout the replacement health, OpenShell readiness, state restoration, gateway restart, and settle checks.
-Before recreation, NemoClaw backs up the state directories and files declared by the agent manifest.
-NemoClaw waits for OpenShell to re-register the replacement before it restores state.
-After state restoration, it restarts the gateway in that replacement and reruns the managed health and settle checks.
-It commits only after the replacement identity, state restoration, gateway restart, and settle check pass.
-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.
-After a transactional recreation, NemoClaw waits 120 seconds for OpenShell to re-register the sandbox before state restoration and replacement commit.
-Set `NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS` before the recovery command to change this budget.
-A definitive managed-health failure still stops immediately.
-If re-registration, state restoration, or a later gateway check fails, NemoClaw attempts to roll back the replacement and leaves the primary dashboard or API host forward stopped.
-If NemoClaw cannot confirm rollback to the previous container, inspect Docker state before you retry recovery.
-
-For the controller topology, trust boundary, and fail-closed conditions, refer to [Understand Gateway Lifecycle Control](../configure-sandboxes/understand-gateway-lifecycle-control).
-If recovery cannot repair a sandbox that needs credentials or a current controller contract, rebuild it.
+NemoClaw keeps the previous container available throughout the replacement health, OpenShell readiness, state restoration, gateway restart, and settle checks. Before recreation, NemoClaw backs up the state directories and files declared by the agent manifest. NemoClaw waits for OpenShell to re-register the exact replacement before it restores state. After state restoration, it restarts the gateway in that replacement and reruns the managed health and settle checks. It commits only after the replacement identity, state restoration, gateway restart, and settle check pass. 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. After a transactional recreation, NemoClaw waits 120 seconds for OpenShell to re-register the sandbox before state restoration and replacement commit. Set `NEMOCLAW_GATEWAY_RECOVERY_WAIT_SECONDS` before the recovery command to change this budget. A definitive managed-health failure still stops immediately. If re-registration, state restoration, or a later gateway check fails, NemoClaw attempts to roll back the replacement and leaves the primary dashboard or API host forward stopped. If NemoClaw cannot confirm rollback to the previous container, inspect Docker state before you retry recovery.
+
+For the controller topology, trust boundary, and fail-closed conditions, refer to [Understand Gateway Lifecycle Control](../configure-sandboxes/understand-gateway-lifecycle-control). If recovery cannot repair a sandbox that needs credentials or a current controller contract, rebuild it.
+
Deep Agents sandboxes are terminal runtimes and do not expose an OpenClaw or Hermes in-sandbox gateway.
@@ -150,12 +116,10 @@ If the terminal runtime reports degraded health, rebuild the sandbox instead of
### Understand Launch Readiness Leases
-A successful complete preflight for `$$nemoclaw launch ` can publish a credential-free launch-readiness lease on Linux.
-Linux infrastructure can publish the same evidence with `$$nemoclaw connect --probe-only`.
-The lease has a fixed 24-hour lifetime that repeated launches do not extend.
-Leaving the agent with `/exit` does not revoke it, and users do not refresh it manually.
+A successful complete preflight for `$$nemoclaw launch ` can publish a credential-free launch-readiness lease on Linux. Linux infrastructure can publish the same evidence with `$$nemoclaw connect --probe-only`. The lease has a fixed 24-hour lifetime that repeated launches do not extend. Leaving the agent with `/exit` does not revoke it, and users do not refresh it manually.
+
+During the lease, `launch` still verifies the owning OpenShell gateway, exact live sandbox identity, registry and agent configuration, effective policy, inference route, required forwards, and semantic runtime health.
-During the lease, `launch` still verifies the owning OpenShell gateway, live sandbox identity, registry and agent configuration, effective policy, inference route, required forwards, and semantic runtime health.
Configured inference must return HTTP 2xx from the semantic `inference.local` probe, which is stricter than the HTTP 200–499 reachability diagnostic used by ordinary `connect`.
@@ -167,163 +131,116 @@ A failed request rejects launch readiness and identifies the inference request a
-For OpenClaw, `connect --probe-only` settles the existing allowlisted pairing flow before it publishes a credential-free pairing qualification with the lease.
-The readiness evidence binds the OpenClaw version and trusted registry and agent manifest configuration.
-Its pairing qualification binds the canonical CLI client, paired device identity, required operator role and scopes, owning OpenShell gateway, sandbox lifecycle identity, and fixed lease epoch.
-Before lease acceptance, `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 qualification still matches exactly and no relevant allowlisted request is pending.
-Any missing, unreadable, malformed, ambiguous, or changed observation runs the complete pairing approval pass.
-A relevant allowlisted pending request also runs that complete path.
+For OpenClaw, `connect --probe-only` settles the existing allowlisted pairing flow before it publishes a credential-free pairing qualification with the lease. The readiness evidence binds the OpenClaw version and trusted registry and agent manifest configuration. Its 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 lease acceptance, `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 qualification still matches exactly and no relevant allowlisted request is pending. Any missing, unreadable, malformed, ambiguous, or changed observation runs the complete pairing approval pass. A relevant allowlisted pending request also runs that complete path.
-For a current Portable OpenClaw lifecycle receipt, NemoClaw also requires a finalized onboarding policy step and strictly settled local CLI operator pairing.
-If only the paired device exists and no request is pending, recovery runs the canonical OpenClaw request producer once and makes at most one approval attempt.
-An ambiguous approval result receives one final observation and no approval retry.
-NemoClaw publishes no lease when the policy step is incomplete or the receipt, runtime identity, or pairing state is invalid or ambiguous.
-The command exits nonzero with an incomplete-onboarding diagnostic and tells you to resume or rerun onboarding.
+For a current Portable OpenClaw lifecycle receipt, NemoClaw also requires a finalized onboarding policy step and strictly settled local CLI operator pairing. If only the paired device exists and no request is pending, recovery runs the canonical OpenClaw request producer once and makes at most one approval attempt. An ambiguous approval result receives one final observation and no approval retry. NemoClaw publishes no lease when the policy step is incomplete or the receipt, runtime identity, or pairing state is invalid or ambiguous. The command exits nonzero with an incomplete-onboarding diagnostic and tells you to resume or rerun onboarding.
Hermes and LangChain Deep Agents Code retain their existing session setup on the lease-accepted path.
When those checks pass, it can skip duplicate recovery, readiness polling, and inference-route repair.
The lease is not a health guarantee or repair authority.
-For missing, unsafe, malformed, expired, mismatched, changed, 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` and `connect --probe-only` stop before complete preflight or recovery.
-Their redacted guidance asks you to repair the current user's secure OS runtime authority and NemoClaw state permissions, then retry.
-If NemoClaw securely proves that both the authority and receipt are absent but cannot create new authority, ordinary `launch` can run the complete preflight without optimization; on Linux, `connect --probe-only` exits nonzero because it could not publish evidence.
-If that preflight succeeds before the lease expires, replacement evidence keeps the original start and expiry time.
-After expiry, a successful complete preflight starts a new 24-hour lease only when publication succeeds.
-
-Before the first mutation in the complete preflight, the producer revalidates its sandbox-global runtime epoch under 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.
-A stale producer makes no changes and re-inspects the newer lease.
-
-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.
-Publication remains disabled until both wall time and monotonic uptime span the full quarantine.
-Repeated attempts do not extend it.
-After it elapses, the next successful complete preflight can publish a new fixed 24-hour lease.
-
-Lease acceptance and publication are currently Linux-only and require a secure, independently writable OS per-user runtime authority under `/run/user/`.
-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.
-`connect --probe-only` also 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.
-On Linux, the publication-failure diagnostic is redacted and does not print filesystem paths or environment values.
-
-Infrastructure must run `connect --probe-only` as the same final numeric user that later runs `launch`.
-Run it after the final durable home and state volume is mounted and after policy and network provisioning is complete.
-On completion, `connect --probe-only` writes one credential-free `Probe timing:` line with elapsed milliseconds for readiness, authority, lifecycle, gateway, processes, forward, inference, pairing, and publication stages.
-The line also reports the lifecycle and forward actions, the result, and the failed stage when the probe fails.
-Timing output is diagnostic only and does not change probe success or failure.
-NemoClaw rejects evidence after a bound sandbox, configuration, policy, or network identity changes.
-Deployment ordering remains responsible for external changes that OpenShell and NemoClaw cannot observe.
+For missing, unsafe, malformed, expired, mismatched, changed, 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` and `connect --probe-only` stop before complete preflight or recovery. Their redacted guidance asks you to repair the current user's secure OS runtime authority and NemoClaw state permissions, then retry. If NemoClaw securely proves that both the authority and receipt are absent but cannot create new authority, ordinary `launch` can run the complete preflight without optimization; on Linux, `connect --probe-only` exits nonzero because it could not publish evidence. If that preflight succeeds before the lease expires, replacement evidence keeps the original start and expiry time. After expiry, a successful complete preflight starts a new 24-hour lease only when publication succeeds.
+
+Before the first mutation in the complete preflight, the producer revalidates its sandbox-global runtime epoch under 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. A stale producer makes no changes and re-inspects the newer lease.
+
+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. Publication remains disabled until both wall time and monotonic uptime span the full quarantine. Repeated attempts do not extend it. After it elapses, the next successful complete preflight can publish a new fixed 24-hour lease.
+
+Lease acceptance and publication are currently Linux-only and require a secure, independently writable OS per-user runtime authority under `/run/user/`. 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. `connect --probe-only` also 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. On Linux, the publication-failure diagnostic is redacted and does not print filesystem paths or environment values.
+
+Infrastructure must run `connect --probe-only` as the same final numeric user that later runs `launch`. Run it after the final durable home and state volume is mounted and after policy and network provisioning is complete. On completion, `connect --probe-only` writes one credential-free `Probe timing:` line with elapsed milliseconds for readiness, authority, lifecycle, gateway, processes, forward, inference, pairing, and publication stages. The line also reports the lifecycle and forward actions, the result, and the failed stage when the probe fails. Timing output is diagnostic only and does not change probe success or failure. NemoClaw rejects evidence after a bound sandbox, configuration, policy, or network identity changes. Deployment ordering remains responsible for external changes that OpenShell and NemoClaw cannot observe.
### Host OpenShell Gateway Versus In-Sandbox Agent Recovery
-`recover` and `start` repair the in-sandbox agent gateway and the host-side port forwards for one named sandbox.
-`connect --probe-only` waits for that sandbox to become ready, rechecks it on its recorded gateway, and then verifies or repairs the same sandbox-scoped processes and forwards.
-These commands do not restart, replace, or reap the shared host OpenShell gateway process.
-If the host gateway RPC returns an error while these sandbox-scoped commands run, they surface the error with explicit next-step guidance and exit rather than swapping the shared gateway out from under other sandboxes.
-
-The OpenShell CLI has no command that starts a gateway, and `openshell status` only reports the gateway state.
-If NemoClaw starts the gateway on your host, run `$$nemoclaw onboard` again to repair the host gateway itself.
-If a deployment outside NemoClaw owns the gateway process, start the gateway with that deployment, then run `openshell gateway select `.
-NemoClaw prints the applicable recovery guidance when a sandbox-scoped command reports that the host gateway is down.
-Other workflows, including onboarding, rebuild, and `doctor --fix`, can explicitly recover the named host gateway when their operation requires it.
-`$$nemoclaw gateway restart` instead restarts only the supported agent gateway inside the named sandbox.
+`recover` and `start` repair the in-sandbox agent gateway and the host-side port forwards for one named sandbox. `connect --probe-only` waits for that sandbox to become ready, rechecks it on its recorded gateway, and then verifies or repairs the same sandbox-scoped processes and forwards. These commands do not restart, replace, or reap the shared host OpenShell gateway process. If the host gateway RPC returns an error while these sandbox-scoped commands run, they surface the error with explicit next-step guidance and exit rather than swapping the shared gateway out from under other sandboxes.
+
+The OpenShell CLI has no command that starts a gateway, and `openshell status` only reports the gateway state. If NemoClaw starts the gateway on your host, run `$$nemoclaw onboard` again to repair the host gateway itself. If a deployment outside NemoClaw owns the gateway process, start the gateway with that deployment, then run `openshell gateway select `. NemoClaw prints the applicable recovery guidance when a sandbox-scoped command reports that the host gateway is down. Other workflows, including onboarding, rebuild, and `doctor --fix`, can explicitly recover the named host gateway when their operation requires it. `$$nemoclaw gateway restart` instead restarts only the supported agent gateway inside the named sandbox.
+
### Recover Portable Local Ollama
-For a portable experimental-profile sandbox with the recorded `ollama-local` provider, `connect --probe-only` and `recover` also verify the host-side inference chain.
-Before it decides whether to start Ollama, the command probes `http://127.0.0.1:11434/api/tags` and leaves a healthy daemon unchanged.
-When that API is unhealthy, it starts the fixed user-local executable only if NemoClaw has a valid ownership receipt.
-NemoClaw releases that predate this receipt do not claim an existing executable after an upgrade.
-To authorize recovery for a previous NemoClaw user-local install, first verify that `${HOME}/.local/bin/ollama` is the executable you want NemoClaw to manage.
-Then run `NEMOCLAW_PORTABLE_OLLAMA_REENROLL=1 nemoclaw recover` once.
-The command rejects a symbolic link 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, recovery waits up to 30 seconds for `/api/tags` to return valid JSON with a `models` array.
-It does not take over a system service or an unrelated user-managed daemon.
-It refuses a symbolic link, non-regular file, or non-executable file at the receipt-bound executable path.
-
-On every `ollama-local` completion path, the command verifies the authenticated proxy on port `11435`.
-It also requires HTTP 2xx from `https://inference.local/v1/models` before it reports success.
-If Ollama does not become healthy within 30 seconds, the command identifies the receipt-bound executable and its `serve` argument, then tells you to retry recovery.
-An Ollama startup or route failure exits non-zero and prints the available recovery guidance.
+For a portable experimental-profile sandbox with the recorded `ollama-local` provider, `connect --probe-only` and `recover` also verify the host-side inference chain. Before it decides whether to start Ollama, the command probes `http://127.0.0.1:11434/api/tags` and leaves a healthy daemon unchanged. When that API is unhealthy, it starts the fixed user-local executable only if NemoClaw has a valid ownership receipt. NemoClaw releases that predate this receipt do not claim an existing executable after an upgrade. To authorize recovery for a previous NemoClaw user-local install, first verify that `${HOME}/.local/bin/ollama` is the executable you want NemoClaw to manage. Then run `NEMOCLAW_PORTABLE_OLLAMA_REENROLL=1 nemoclaw recover` once. The command rejects a symbolic link 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, recovery waits up to 30 seconds for `/api/tags` to return valid JSON with a `models` array. It does not take over a system service or an unrelated user-managed daemon. It refuses a symbolic link, non-regular file, or non-executable file at the receipt-bound executable path.
+
+On every `ollama-local` completion path, the command verifies the authenticated proxy on port `11435`. It also requires HTTP 2xx from `https://inference.local/v1/models` before it reports success. 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. An Ollama startup or route failure exits non-zero and prints the available recovery guidance.
+
## Rebuild While Preserving State
-If you changed the underlying Dockerfile, upgraded OpenClaw, or want to pick up a new base image without losing your sandbox's workspace files, use `rebuild` instead of destroying and recreating.
+ If you changed the underlying Dockerfile, upgraded OpenClaw, or want to pick up a new base image
+ without losing your sandbox's workspace files, use `rebuild` instead of destroying and recreating.
-If you changed the underlying Dockerfile, upgraded Hermes, or want to pick up a new base image without losing your sandbox's state files, use `rebuild` instead of destroying and recreating.
+ If you changed the underlying Dockerfile, upgraded Hermes, or want to pick up a new base image
+ without losing your sandbox's state files, use `rebuild` instead of destroying and recreating.
-If you changed the underlying Dockerfile, upgraded Deep Agents Code, enabled Tavily Search, or want to pick up a new base image without losing manifest-defined Deep Agents state, use `rebuild` instead of destroying and recreating.
+ If you changed the underlying Dockerfile, upgraded Deep Agents Code, enabled Tavily Search, or
+ want to pick up a new base image without losing manifest-defined Deep Agents state, use `rebuild`
+ instead of destroying and recreating.
-
-When the installer offers prepared backup recovery for a legacy sandbox, the recreate restores only the managed state directory recorded in the validated backup manifest, such as `/sandbox/.openclaw` or `/sandbox/.hermes`.
-It does not preserve files outside that recorded path, including `/sandbox/user-data`.
-Back up those paths outside the sandbox before you approve legacy recovery.
-
+
+ When the installer offers prepared backup recovery for a legacy sandbox, the recreate restores
+ only the managed state directory recorded in the validated backup manifest, such as
+ `/sandbox/.openclaw` or `/sandbox/.hermes`. It does not preserve files outside that recorded
+ path, including `/sandbox/user-data`. Back up those paths outside the sandbox before you approve
+ legacy recovery.
+
```bash
$$nemoclaw rebuild
```
-On WSL with Docker Desktop, a generated replacement image build uses a temporary credential-free Docker configuration when the configured Docker Desktop credential helper is unavailable.
-NemoClaw removes the temporary configuration after the build and does not modify your Docker configuration.
-An explicit custom Dockerfile continues to use your configured Docker credentials because its base image or build steps might require a private registry.
-If that custom rebuild cannot reach the credential helper, restore the Docker Desktop session or credential-helper access before retrying.
+On WSL with Docker Desktop, a generated replacement image build uses a temporary credential-free Docker configuration when the configured Docker Desktop credential helper is unavailable. NemoClaw removes the temporary configuration after the build and does not modify your Docker configuration. An explicit custom Dockerfile continues to use your configured Docker credentials because its base image or build steps might require a private registry. If that custom rebuild cannot reach the credential helper, restore the Docker Desktop session or credential-helper access before retrying.
-After post-restore writes, rebuild verifies that the final `openclaw.json` and `.config-hash` pair match.
-If verification fails, NemoClaw restores Shields, exits nonzero, and does not report a successful rebuild.
+After post-restore writes, rebuild verifies that the final `openclaw.json` and `.config-hash` pair match. If verification fails, NemoClaw restores Shields, exits nonzero, and does not report a successful rebuild.
### Resolve Rebuild Preflight Stops
-Before it backs up or deletes the existing sandbox, `rebuild` validates the recorded sandbox, gateway, inference route, policy, MCP, agent, and operation-lock state.
-When one of these checks fails, NemoClaw prints `Rebuild preflight failed`, explains how to recover, and ends with `Aborting rebuild`.
-At this boundary, the existing sandbox is unchanged and no sandbox data has been removed.
+Before it backs up or deletes the existing sandbox, `rebuild` validates the recorded sandbox, gateway, inference route, policy, MCP, agent, and operation-lock state. When one of these checks fails, NemoClaw prints `Rebuild preflight failed`, explains how to recover, and ends with `Aborting rebuild`. At this boundary, the existing sandbox is unchanged and no sandbox data has been removed.
Use the recovery guidance that matches the reported check:
- Verify the sandbox name when its registry entry is missing.
- Follow the printed OpenShell gateway recovery steps when the gateway schema is incompatible.
-- Repair the named pending baseline policy transition, then rerun `rebuild`.
+- Restore access to the current OpenShell policy when rebuild reports that the live policy cannot be read, then rerun `rebuild`. NemoClaw does not reconstruct policy from registry state.
- Resolve an incomplete MCP destroy transaction before retrying.
- Back up the sandbox state and recreate it with `$$nemoclaw onboard` when the record contains multiple agents. Transactional multi-agent rebuild is not supported.
- Wait for another onboarding or rebuild operation to finish before retrying. If verified stale-lock cleanup is still in progress, wait briefly and rerun the command. Do not delete the lock manually.
- Set the live OpenShell inference route to the sandbox's recorded provider and model when rebuild reports route drift.
-A gateway that reports no live inference route does not stop the rebuild.
-Replacement onboarding configures and verifies the recorded route before it recreates the sandbox.
+A gateway that reports no live inference route does not stop the rebuild. Replacement onboarding configures and verifies the recorded route before it recreates the sandbox.
-The rebuild command preserves the mounted workspace and registered policies while recreating the container.
-When no host web-search key is staged, rebuild preflight reuses an existing Brave or Tavily credential only when the provider name, type, and credential key match the sandbox's binding on its recorded OpenShell gateway.
-A missing or mismatched binding stops before recreation and requires the matching host environment variable before you retry.
-After state restoration, NemoClaw clears a session's stale model and provider pin when it still targets the managed `inference` provider but no longer matches the configured default model.
-The session then follows the current default selected through `inference set`, while sessions pinned to another provider remain unchanged.
+ The rebuild command preserves the mounted workspace and carries the complete current OpenShell
+ policy into sandbox recreation. When no host web-search key is staged, rebuild preflight reuses an
+ existing Brave or Tavily credential only when the provider name, type, and credential key match
+ the sandbox's binding on its recorded OpenShell gateway. A missing or mismatched binding stops
+ before recreation and requires the matching host environment variable before you retry. After
+ state restoration, NemoClaw clears a session's stale model and provider pin when it still targets
+ the managed `inference` provider but no longer matches the configured default model. The session
+ then follows the current default selected through `inference set`, while sessions pinned to
+ another provider remain unchanged.
-The rebuild command preserves Hermes state, registered policies, and managed MCP configuration while recreating the container.
+The rebuild command preserves Hermes state, the complete current OpenShell policy, and managed MCP configuration while recreating the container.
It reuses a messaging provider only when its exact type and credential keys match the recorded channel binding.
A stopped channel remains inactive and contributes no token upsert, rendered runtime configuration, channel startup effect, or inactive built-in messaging preset.
-Exact custom policies remain preserved for separate replay.
+Custom and host-edited policy entries are preserved as part of that one OpenShell policy handoff, not by a separate replay system.
A policy-required provider attachment is the narrow exception: when a preserved custom policy still credential-binds stopped Hermes Discord, rebuild attaches its exact validated static provider without starting Discord.
If that required provider is missing or incompatible, restore or re-add the channel credentials, then rerun the rebuild.
A rebuild creates a new sandbox home and a new Hermes API bearer token.
@@ -333,60 +250,34 @@ After the rebuild succeeds, retrieve the replacement token before reconnecting A
$$nemoclaw gateway-token --quiet
```
-Before post-restore repairs, NemoClaw verifies that the recreated sandbox still identifies as Hermes and exits nonzero if its identity does not match the rebuild target.
-After state restore, NemoClaw restarts the Hermes gateway so it reads the restored durable state, then restores managed MCP configuration through the normal lifecycle.
-MCP restoration performs an acknowledged gateway reload, so NemoClaw finishes by verifying the final running gateway and its managed MCP state without replacing that verified process again.
-The gateway starts during recreation and reads its durable state before the restore replaces it, which is why the first post-restore restart must happen before managed MCP restoration.
-`rebuild` exits nonzero instead of reporting success when it cannot verify final gateway health or managed MCP state.
-Follow the printed recovery guidance, using `$$nemoclaw gateway restart` first for gateway health, `$$nemoclaw recover` when the restart does not restore verified health, and `$$nemoclaw mcp restart` for incomplete managed MCP restoration.
-
-When the rebuild backup contains active Hermes cron jobs that reference scripts, NemoClaw validates those script references before it deletes the existing sandbox.
-The check covers the default profile and named profiles.
-Each referenced script must exist, be readable, be a regular file, and remain inside its profile's `scripts` directory.
-Disabled and paused jobs do not require their referenced scripts.
-If this validation fails, the rebuild keeps the existing sandbox and reports the preserved backup path.
-
-After NemoClaw creates the replacement, it acquires an independent root-owned gate that blocks new Hermes turns and cron dispatch.
-The gate remains active across gateway and container restarts in the replacement sandbox.
-NemoClaw waits for active agent work to finish before restoring state.
-It validates the restored jobs and scripts before the gateway replacement, then keeps dispatch blocked while it restarts and verifies that replacement.
-It records the replacement process identity around managed health verification and clears the gate only if that same live process completes the final cron validation.
-If an operator already drained the gateway, NemoClaw clears its gate and release recovery record while leaving the operator drain active.
-If state restore, managed MCP restoration, gateway replacement, or cron validation fails after gate acquisition, the command exits nonzero and preserves the backup.
-Those failures retain the NemoClaw gate unless the output explicitly reports that release rollback could not restore its marker.
-In that exceptional case, NemoClaw preserves a root-owned release recovery record, but you must not assume dispatch is blocked.
-Run `$$nemoclaw recover` immediately so it can reacquire the gate before validating the restored cron state.
-If gate reacquisition fails, recovery exits nonzero and leaves the recovery record in place for another attempt.
-Failures before gate acquisition do not create a new gate.
-Do not manually remove the root-owned cron restore marker or release recovery record because removal bypasses restored cron validation.
-If managed MCP restoration failed, correct the reported cause and run `$$nemoclaw mcp restart` first.
-Then run `$$nemoclaw recover` to repair and probe the gateway, validate the restored cron tree, and clear NemoClaw-owned cron restore recovery state.
+Before post-restore repairs, NemoClaw verifies that the recreated sandbox still identifies as Hermes and exits nonzero if its identity does not match the rebuild target. After state restore, NemoClaw restarts the Hermes gateway so it reads the restored durable state, then restores managed MCP configuration through the normal lifecycle. MCP restoration performs an acknowledged gateway reload, so NemoClaw finishes by verifying the final running gateway and its managed MCP state without replacing that verified process again. The gateway starts during recreation and reads its durable state before the restore replaces it, which is why the first post-restore restart must happen before managed MCP restoration. `rebuild` exits nonzero instead of reporting success when it cannot verify final gateway health or managed MCP state. Follow the printed recovery guidance, using `$$nemoclaw gateway restart` first for gateway health, `$$nemoclaw recover` when the restart does not restore verified health, and `$$nemoclaw mcp restart` for incomplete managed MCP restoration.
+
+When the rebuild backup contains active Hermes cron jobs that reference scripts, NemoClaw validates those script references before it deletes the existing sandbox. The check covers the default profile and named profiles. Each referenced script must exist, be readable, be a regular file, and remain inside its profile's `scripts` directory. Disabled and paused jobs do not require their referenced scripts. If this validation fails, the rebuild keeps the existing sandbox and reports the preserved backup path.
+
+After NemoClaw creates the replacement, it acquires an independent root-owned gate that blocks new Hermes turns and cron dispatch. The gate remains active across gateway and container restarts in the replacement sandbox. NemoClaw waits for active agent work to finish before restoring state. It validates the restored jobs and scripts before the gateway replacement, then keeps dispatch blocked while it restarts and verifies that replacement. It records the replacement process identity around managed health verification and clears the gate only if that same live process completes the final cron validation. If an operator already drained the gateway, NemoClaw clears its gate and release recovery record while leaving the operator drain active. If state restore, managed MCP restoration, gateway replacement, or cron validation fails after gate acquisition, the command exits nonzero and preserves the backup. Those failures retain the NemoClaw gate unless the output explicitly reports that release rollback could not restore its marker. In that exceptional case, NemoClaw preserves a root-owned release recovery record, but you must not assume dispatch is blocked. Run `$$nemoclaw recover` immediately so it can reacquire the gate before validating the restored cron state. If gate reacquisition fails, recovery exits nonzero and leaves the recovery record in place for another attempt. Failures before gate acquisition do not create a new gate. Do not manually remove the root-owned cron restore marker or release recovery record because removal bypasses restored cron validation. If managed MCP restoration failed, correct the reported cause and run `$$nemoclaw mcp restart` first. Then run `$$nemoclaw recover` to repair and probe the gateway, validate the restored cron tree, and clear NemoClaw-owned cron restore recovery state.
+
-The rebuild command preserves manifest-defined Deep Agents state, regenerates `config.toml`, reconstructs managed MCP projection state, and reapplies registered policies while recreating the container.
+ The rebuild command preserves manifest-defined Deep Agents state, regenerates `config.toml`,
+ reconstructs managed MCP projection state, and passes the complete current OpenShell policy to
+ replacement creation.
### Continue an Interrupted Replacement
-Before `rebuild` deletes the existing sandbox, NemoClaw records a replacement journal in the onboarding session.
-The journal binds the operation to the sandbox name, recorded OpenShell gateway, source identity, and replacement settings.
-It stores fingerprints instead of credential values or raw OpenShell sandbox IDs.
+Before `rebuild` deletes the existing sandbox, NemoClaw records a replacement journal in the onboarding session. The journal binds the operation to the sandbox name, recorded OpenShell gateway, source identity, and replacement settings. It stores fingerprints instead of credential values or raw OpenShell sandbox IDs.
-If `rebuild` stops after recording the journal, rerun the command with the same replacement settings.
-The rerun takes one of these actions:
+If `rebuild` stops after recording the journal, rerun the command with the same replacement settings. The rerun takes one of these actions:
- It continues deletion when the live sandbox still has the journaled source identity.
- It continues creation when the recorded OpenShell gateway explicitly reports the source sandbox as absent.
- It accepts an existing replacement only when its live identity and sandbox registry generation match the journal.
-A mount-free journal written before NemoClaw bound host-mount identity remains resumable.
-An older journal for a rebuild with one or more host mounts stops as incompatible, even when the visible mount settings are unchanged, because it cannot prove the original host source identity.
-Preserve the live sandbox, onboarding session, printed backup, error, and the sandbox name, gateway, and journal phase from the `Journaled replacement` diagnostic.
-Do not change the target settings, edit the session, or delete the same-name sandbox.
-Ask a NemoClaw maintainer to review that retained recovery state before taking another recovery action.
+A mount-free journal written before NemoClaw bound host-mount identity remains resumable. An older journal for a rebuild with one or more host mounts stops as incompatible, even when the visible mount settings are unchanged, because it cannot prove the original host source identity. Preserve the live sandbox, onboarding session, printed backup, exact error, and the sandbox name, gateway, and journal phase from the `Journaled replacement` diagnostic. Do not change the target settings, edit the session, or delete the same-name sandbox. Ask a NemoClaw maintainer to review that retained recovery state before taking another recovery action.
An accepted replacement is not deleted again.
+
A rerun that accepts a journaled Hermes replacement checks for any retained NemoClaw gate before it retires the replacement journal.
When the gate exists, the rerun validates the restored cron tree and releases the gate first.
@@ -398,46 +289,41 @@ After recovery succeeds, rerun `rebuild` with the same replacement settings so N
The command reports `Sandbox '' already holds the replacement from the interrupted rebuild.` and preserves the state backup path when one exists.
Pass `--verbose` to include the replacement identifier, OpenShell gateway, and journal phase in rebuild diagnostics.
-After the sandbox registry proves the journaled replacement identity and generation, NemoClaw removes an obsolete source image that it owns.
-It retains the image when the source is shared or the registered replacement reuses it.
-If image removal fails, NemoClaw keeps the accepted replacement and tells you to run `$$nemoclaw gc` for cleanup.
+After the sandbox registry proves the journaled replacement identity and generation, NemoClaw removes an obsolete source image that it owns. It retains the image when the source is shared or the registered replacement reuses it. If image removal fails, NemoClaw keeps the accepted replacement and tells you to run `$$nemoclaw gc` for cleanup.
-NemoClaw fails closed when the selected gateway, replacement settings, durable source registry fields, or live source or target identity no longer matches the journal.
-The error names the sandbox and the mismatch that stopped recovery.
-Do not delete a same-name sandbox to bypass this check.
-Inspect the named OpenShell gateway and sandbox, correct the reported drift, and rerun the original command.
-Visible settings cannot correct the legacy host-mount journal case described above.
+NemoClaw fails closed when the selected gateway, replacement settings, durable source registry fields, or live source or target identity no longer matches the journal. The error names the sandbox and the mismatch that stopped recovery. Do not delete a same-name sandbox to bypass this check. Inspect the named OpenShell gateway and sandbox, correct the reported drift, and rerun the original command. Visible settings cannot correct the legacy host-mount journal case described above.
-A same-name recreation started by `$$nemoclaw onboard` uses the same replacement journal.
-If that recreation is interrupted after the `Journaled replacement` message, rerun the original onboarding command with the same target settings.
-The active replacement can continue without adding `--resume`.
-Use `--resume` for interrupted onboarding steps that occur before a replacement journal exists.
+A same-name recreation started by `$$nemoclaw onboard` uses the same replacement journal. If that recreation is interrupted after the `Journaled replacement` message, rerun the original onboarding command with the same target settings. The active replacement can continue without adding `--resume`. Use `--resume` for interrupted onboarding steps that occur before a replacement journal exists.
-If an archive command preserves at least one state directory, NemoClaw keeps the usable entries and reports the manifest-defined paths that could not be archived.
-If a manifest-declared state file fails, NemoClaw stops before deleting the original sandbox even when it preserved state directories, unless you explicitly pass `--force`.
-If every state directory fails, NemoClaw stops before deleting the original sandbox even when it captured loose files, unless you explicitly pass `--force`.
+If an archive command preserves at least one state directory, NemoClaw keeps the usable entries and reports the manifest-defined paths that could not be archived. If a manifest-declared state file fails, NemoClaw stops before deleting the original sandbox even when it preserved state directories, unless you explicitly pass `--force`. If every state directory fails, NemoClaw stops before deleting the original sandbox even when it captured loose files, unless you explicitly pass `--force`.
-`rebuild --force` can continue when no state directory was preserved or a manifest-declared state file failed.
-NemoClaw restores any entries captured in the partial backup; if nothing usable was captured, it recreates the sandbox 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.
-When a sandbox with managed MCP servers cannot run a pre-mutation no-op, explicit `--force` uses its complete registry entries plus the live generated policies and provider identities to preserve MCP intent without scrubbing the unreachable in-sandbox adapter.
-Every bridge entry 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.
-NemoClaw rechecks that read-only snapshot immediately before deletion and stops if the target, registry, policy, provider, or recorded gateway changed.
-NemoClaw sends the delete request and every deletion-confirmation lookup to the sandbox's recorded gateway.
-Across every rebuild path, NemoClaw does not attempt to stop the local NIM through the delete attempt, and cleanup is attempted on a best-effort basis only after deletion is positively confirmed.
-After a nonzero delete, an explicit missing result converges as deleted.
-A `Ready` or `Running` result 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.
-Any partial or unreachable result remains ambiguous.
-NemoClaw preserves the MCP ownership and rebuild-recovery records, does not attempt to stop NIM, skips the rebuild process's immediate shields relock, and does not claim that the original sandbox is intact.
-Inspect the live sandbox and gateway state before retrying recovery.
-This recovery also stops for incomplete MCP adds or ambiguous ownership; an error after a successful no-op does not fall back to the host-side path.
+ `rebuild --force` can continue when no state directory was preserved or a manifest-declared state
+ file failed. NemoClaw restores any entries captured in the partial backup; if nothing usable was
+ captured, it recreates the sandbox 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. When a sandbox with managed MCP servers cannot run a pre-mutation no-op, explicit
+ `--force` uses its complete bridge entries plus exact provider and target identities to preserve
+ MCP intent without scrubbing the unreachable in-sandbox adapter. Every bridge entry must record
+ the adapter for the sandbox's recorded agent. NemoClaw rechecks that read-only bridge snapshot
+ immediately before deletion and stops if the target, registry, provider, or recorded gateway
+ changed. Policy is not part of that ownership proof; the independently captured live OpenShell
+ policy is handed to replacement creation unchanged. 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 the local NIM through the delete attempt, and cleanup is
+ attempted on a best-effort basis only after deletion is positively confirmed. After a nonzero
+ delete, an explicit missing result converges as deleted. A `Ready` or `Running` result 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. Any partial or unreachable result remains ambiguous. NemoClaw preserves the
+ MCP ownership and rebuild-recovery records, does not attempt to stop NIM, skips the rebuild
+ process's immediate shields relock, and does not claim that the original sandbox is intact.
+ Inspect the live sandbox and gateway state before retrying recovery. This recovery also stops for
+ incomplete MCP adds or ambiguous ownership; an error after a successful no-op does not fall back
+ to the host-side path.
-When rebuild starts with shields up, NemoClaw opens a 30-minute shields-down window for backup and recreation.
-A detached auto-lock timer remains the recovery authority until NemoClaw commits a successful shields-up state, including when the host rebuild process exits unexpectedly.
+When rebuild starts with shields up, NemoClaw opens a 30-minute shields-down window for backup and recreation. A detached auto-lock timer remains the recovery authority until NemoClaw commits a successful shields-up state, including when the host rebuild process exits unexpectedly.
If a failed shields transition on a sandbox from an older NemoClaw release quarantined the OpenClaw config, the bytes are preserved as `/sandbox/.openclaw/.nemoclaw-rejected-openclaw.json-` rather than deleted.
@@ -449,8 +335,11 @@ Sandboxes with the updated guard report quarantine filenames and synthesize a mi
-For an older Hermes image that predates sealed shields transitions, only the rebuild workflow may use the descriptor-safe compatibility transition needed to archive and replace the sandbox.
-That transition verifies the strict and compatibility hashes and publishes fresh config inodes before changing their lock posture, while ordinary `shields up` and `shields down` commands continue to refuse the older protocol.
+ For an older Hermes image that predates sealed shields transitions, only the rebuild workflow may
+ use the descriptor-safe compatibility transition needed to archive and replace the sandbox. That
+ transition verifies the strict and compatibility hashes and publishes fresh config inodes before
+ changing their lock posture, while ordinary `shields up` and `shields down` commands continue to
+ refuse the older protocol.
Refer to [`$$nemoclaw rebuild`](../../reference/commands#$$nemoclaw-name-rebuild) for flag details.
diff --git a/docs/manage-sandboxes/runtime-controls.mdx b/docs/manage-sandboxes/runtime-controls.mdx
index 4ec202eaf4d..9cd9ed4eb91 100644
--- a/docs/manage-sandboxes/runtime-controls.mdx
+++ b/docs/manage-sandboxes/runtime-controls.mdx
@@ -12,15 +12,15 @@ skill:
priority: 10
agent-variants: ["openclaw", "hermes"]
---
-Use this matrix to choose the operation that makes a sandbox change take effect.
-NemoClaw applies its security posture in three layers: what onboarding writes into the sandbox image, what the running sandbox can hot-reload, and what requires a rebuild or re-onboard.
+
+Use this matrix to choose the operation that makes a sandbox change take effect. NemoClaw applies its security posture in three layers: what onboarding writes into the sandbox image, what the running sandbox can hot-reload, and what requires a rebuild or re-onboard.
## OpenClaw Runtime Changes
| Item | When the change takes effect | How to change it |
-|---|---|---|
+| --- | --- | --- |
| Inference provider | Runtime route and config update while shields are down; rebuild only if you need to recreate the image | Run `$$nemoclaw shields down`, then `$$nemoclaw inference set`, then restore shields |
| Inference model on the current provider | Runtime route and config update while shields are down | Run `$$nemoclaw shields down`, then `$$nemoclaw inference set`, then restore shields |
| Sub-agent | Re-onboard required because the sub-agent and workspace are baked at onboard | `$$nemoclaw onboard --recreate-sandbox` |
@@ -39,25 +39,17 @@ NemoClaw applies its security posture in three layers: what onboarding writes in
| `agents.list` | Runtime; OpenClaw hot-reloads on config change | Prefer agent or NemoClaw commands that keep host and sandbox state aligned |
| `openclaw.json` keys | Mixed; supported config and inference updates run while shields are down, while image, policy, web search, and channel changes can require rebuild | Use `$$nemoclaw inference set` or `$$nemoclaw config set` so the config and integrity hash change together |
-For a new or pristine OpenClaw workspace, `NEMOCLAW_MINIMAL_BOOTSTRAP=1` avoids roughly 3,000 tokens of per-turn project-context overhead by skipping the default template seed.
-It does not delete existing workspace files.
+For a new or pristine OpenClaw workspace, `NEMOCLAW_MINIMAL_BOOTSTRAP=1` avoids roughly 3,000 tokens of per-turn project-context overhead by skipping the default template seed. It does not delete existing workspace files.
-The runtime source of truth is `/sandbox/.openclaw/openclaw.json`.
-The host registry caches metadata, but the image and OpenClaw read from the in-sandbox file.
+The runtime source of truth is `/sandbox/.openclaw/openclaw.json`. The host registry caches metadata, but the image and OpenClaw read from the in-sandbox file.
-OpenClaw config and inference changes are refused while shields are up.
-Run `$$nemoclaw shields down` before the change, then restore lockdown with `$$nemoclaw shields up`.
+OpenClaw config and inference changes are refused while shields are up. Run `$$nemoclaw shields down` before the change, then restore lockdown with `$$nemoclaw shields up`.
-Host-side OpenClaw config writes run under the per-sandbox transition lock and bind the replacement to the SHA-256 digest of the matching read.
-Before `config set` replaces the live file, NemoClaw validates the complete candidate with the installed OpenClaw runtime.
-If candidate validation fails, the command preserves the existing config and does not reach the gateway restart path.
-The root-only config guard validates bounded JSON input, transactionally publishes fresh config and hash inodes, and restores the prior mutable posture without adopting concurrent path changes.
+Host-side OpenClaw config writes run under the per-sandbox transition lock and bind the replacement to the SHA-256 digest of the matching read. Before `config set` replaces the live file, NemoClaw validates the complete candidate with the installed OpenClaw runtime. If candidate validation fails, the command preserves the existing config and does not reach the gateway restart path. The root-only config guard validates bounded JSON input, transactionally publishes fresh config and hash inodes, and restores the prior mutable posture without adopting concurrent path changes.
-In the direct root-entrypoint topology, gateway restart performs a read-only config and hash preflight, temporarily seals fresh inodes while the root PID 1 supervisor replaces the gateway child, and then restores the prior shields posture.
-In the OpenShell-managed topology, the installed root controller performs the config preflight while the nonroot `nemoclaw-start` supervisor replaces the gateway child.
+In the direct root-entrypoint topology, gateway restart performs a read-only config and hash preflight, temporarily seals fresh inodes while the root PID 1 supervisor replaces the gateway child, and then restores the prior shields posture. In the OpenShell-managed topology, the installed root controller performs the config preflight while the nonroot `nemoclaw-start` supervisor replaces the gateway child.
-Mutable config in the managed topology keeps the same trust and time-of-check/time-of-use limits as a managed cold start and does not receive the direct root-entrypoint restart seal.
-If preflight detects an unsafe path, invalid config, invalid ownership posture, or locked hash drift, restart refuses while the old healthy gateway is still serving.
+Mutable config in the managed topology keeps the same trust and time-of-check/time-of-use limits as a managed cold start and does not receive the direct root-entrypoint restart seal. If preflight detects an unsafe path, invalid config, invalid ownership posture, or locked hash drift, restart refuses while the old healthy gateway is still serving.
@@ -65,7 +57,7 @@ If preflight detects an unsafe path, invalid config, invalid ownership posture,
## Hermes Runtime Changes
| Item | When the change takes effect | How to change it |
-|---|---|---|
+| --- | --- | --- |
| Inference provider | Runtime route changes apply immediately; rebuild if you need to rebake model metadata into the image | `$$nemoclaw inference set` for route changes, or `$$nemoclaw rebuild` after changing build-time settings |
| Inference model on the current provider | Hot-reloadable through the Hermes config sync path | `$$nemoclaw inference set` |
| Agent runtime | Re-onboard required because the agent and state layout are baked at onboard | `$$nemoclaw onboard --recreate-sandbox` or `nemoclaw onboard --agent openclaw --recreate-sandbox` |
@@ -81,100 +73,59 @@ If preflight detects an unsafe path, invalid config, invalid ownership posture,
| GPU passthrough or device selector | Locked at creation | Re-onboard with `--gpu` or `--sandbox-gpu-device` |
| Hermes `config.yaml` keys | Mixed; inference and supported config keys can be patched by host commands, while image, policy, and channel changes still require rebuild | Use `$$nemoclaw inference set` or `$$nemoclaw config set` so the config and root-owned trust anchor change together |
-The runtime source of truth is `/sandbox/.hermes/config.yaml` plus `/sandbox/.hermes/.env`.
-The host registry caches metadata, but the image and Hermes runtime read from the in-sandbox files.
+The runtime source of truth is `/sandbox/.hermes/config.yaml` plus `/sandbox/.hermes/.env`. The host registry caches metadata, but the image and Hermes runtime read from the in-sandbox files.
-Do not edit those files or their hash files directly and then expect `gateway restart` to establish the bytes as trusted.
-Use supported host config and inference commands so NemoClaw updates the managed config metadata together.
+Do not edit those files or their hash files directly and then expect `gateway restart` to establish the bytes as trusted. Use supported host config and inference commands so NemoClaw updates the managed config metadata together.
-Hermes host-side config writes run as a sealed transaction.
-NemoClaw binds the write to the SHA-256 digest of the matching read, temporarily seals the mutable config paths, atomically installs fresh config inodes, refreshes the strict and compatibility hashes, and then restores the prior shields posture.
+Hermes host-side config writes run as a sealed transaction. NemoClaw binds the write to the SHA-256 digest of the matching read, temporarily seals the mutable config paths, atomically installs fresh config inodes, refreshes the strict and compatibility hashes, and then restores the prior shields posture.
-`shields up` also publishes fresh config, environment, and compatibility-hash inodes so a descriptor opened before lockdown cannot retain write authority.
-Shields up keeps `/sandbox/.hermes/profiles/dashboard-home/` sandbox-owned at mode `0700` so the dashboard can update its isolated profile.
-Other Hermes profiles remain read-only during lockdown.
-The root-only mutation lock stays held through every Hermes host-side config write.
-On the sealed-plan and compatibility Shields paths, it also stays held through the full `shields up` or `shields down` filesystem transition and verification, and lifecycle recovery that needs to seal those paths.
+`shields up` also publishes fresh config, environment, and compatibility-hash inodes so a descriptor opened before lockdown cannot retain write authority. Shields up keeps `/sandbox/.hermes/profiles/dashboard-home/` sandbox-owned at mode `0700` so the dashboard can update its isolated profile. Other Hermes profiles remain read-only during lockdown. The root-only mutation lock stays held through every Hermes host-side config write. On the sealed-plan and compatibility Shields paths, it also stays held through the full `shields up` or `shields down` filesystem transition and verification, and lifecycle recovery that needs to seal those paths.
-Current NemoClaw-managed Hermes images on the Docker driver use the `provider-state-mutation-v2` runtime provider state mutation contract for Shields filesystem transitions.
-NemoClaw selects this contract only when all these conditions apply:
+Current NemoClaw-managed Hermes images on the Docker driver use the `provider-state-mutation-v2` runtime provider state mutation contract for Shields filesystem transitions. NemoClaw selects this contract only when all these conditions apply:
- The registered sandbox is a managed Hermes image.
- The sandbox registry records its lifecycle generation.
- The image exposes the root-owned capability installed by NemoClaw.
-An older managed image uses the sealed-plan transition only after NemoClaw proves that the capability is absent.
-A custom image, including a legacy Dockerfile workflow, remains on its existing sealed-plan or compatibility contract and cannot opt in by adding a similarly named file.
-An invalid capability that is present fails closed and requires a rebuild with a current managed image.
+An older managed image uses the sealed-plan transition only after NemoClaw proves that the capability is absent. A custom image, including a legacy Dockerfile workflow, remains on its existing sealed-plan or compatibility contract and cannot opt in by adding a similarly named file. An invalid capability that is present fails closed and requires a rebuild with a current managed image.
-The Docker provider binds each transition to the registered lifecycle generation, container, qualified Docker engine authority, mount namespace, `/sandbox/.hermes` inode, AgentDefinition-derived plan and projection, target posture, rollback posture, and fresh nonce.
-Before the provider fence becomes active, NemoClaw drains any earlier privileged sandbox execution lease.
-While the fence is active, new direct-container, SSH, and OpenShell command transports are rejected before a sandbox command starts.
-The installed root-owned controller and Hermes publisher apply and verify the target posture, then the provider starts only the bound Hermes entrypoint and proves the replacement gateway and startup checkpoint before it releases the fence.
+The Docker provider binds each transition to the registered lifecycle generation, exact container, qualified Docker engine authority, mount namespace, `/sandbox/.hermes` inode, AgentDefinition-derived plan and projection, target posture, rollback posture, and fresh nonce. Before the provider fence becomes active, NemoClaw drains any earlier privileged sandbox execution lease. While the fence is active, new direct-container, SSH, and OpenShell command transports are rejected before a sandbox command starts. The installed root-owned controller and Hermes publisher apply and verify the exact target posture, then the provider starts only the bound Hermes entrypoint and proves the replacement gateway and startup checkpoint before it releases the fence.
-The owner-only ledger under `~/.nemoclaw/state/runtime-provider-lifecycle/` survives a host controller restart and remains authoritative for recovery of the target.
-The next Shields command, including `shields status`, must recover a retained fence before it can report or change posture.
-Hermes startup also checks the image-owned startup gate before it reads mutable state and remains held when the runtime provider state mutation is active or cannot be authenticated.
-While recovery is incomplete, do not:
+The owner-only ledger under `~/.nemoclaw/state/runtime-provider-lifecycle/` survives a host controller restart and remains authoritative for recovery of the exact target. The next Shields command, including `shields status`, must recover a retained fence before it can report or change posture. Hermes startup also checks the image-owned startup gate before it reads mutable state and remains held when the runtime provider state mutation is active or cannot be authenticated. While recovery is incomplete, do not:
- Delete the ledger.
- Kill a held entrypoint.
- Use a manual container command to bypass the fence.
-If another host mutation is active, the command reports `Hermes config mutation is already in progress`.
-If another lifecycle request owns the supervisor, it reports `SUPERVISOR_BUSY`.
-Both errors are retryable.
+If another host mutation is active, the command reports `Hermes config mutation is already in progress`. If another lifecycle request owns the supervisor, it reports `SUPERVISOR_BUSY`. Both errors are retryable.
-Let the active command finish, then retry instead of editing lock or seal files manually.
-Hermes config and inference changes are refused while shields are up.
-Run `$$nemoclaw shields down` before the change, then restore lockdown with `$$nemoclaw shields up`.
+Let the active command finish, then retry instead of editing lock or seal files manually. Hermes config and inference changes are refused while shields are up. Run `$$nemoclaw shields down` before the change, then restore lockdown with `$$nemoclaw shields up`.
## Timed Shields Windows
-NemoClaw serializes host-side gateway recovery, config and inference writes, snapshot mutation, sandbox destruction, and shields transitions for each sandbox.
-When `shields down --timeout` is active, each mutation binds to that timer generation so a replaced or expired timer cannot race a later command or a new sandbox that reuses the same name.
+NemoClaw serializes host-side gateway recovery, config and inference writes, snapshot mutation, sandbox destruction, and shields transitions for each sandbox. When `shields down --timeout` is active, each mutation binds to that exact timer generation so a replaced or expired timer cannot race a later command or a new sandbox that reuses the same name.
### Restore Lockdown After Expiration
-If the timeout expires while a mutation is changing sandbox state, auto-restore closes the per-sandbox lifecycle deadline gate.
-The gate blocks new mutations and waits for the recorded live owner to release its lock generation.
-NemoClaw does not signal that process because portable process inspection cannot prove that all descendants stopped.
-After the owner releases the lock, auto-restore restores the restrictive policy and configuration posture.
-The ownership check includes both the process ID and process start identity so PID reuse does not grant control over an unrelated process.
+If the timeout expires while a mutation is changing sandbox state, 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. NemoClaw does not signal that process because portable process inspection cannot prove that all descendants stopped. After the owner releases the lock, auto-restore restores the restrictive policy and configuration posture. The ownership check includes both the process ID and process start identity so PID reuse does not grant control over an unrelated process.
### Complete Generation Recovery
-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.
+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 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 shields status` to resume recovery or receive generation recovery guidance.
-When recovery cannot complete, an interactive command returns an error, or the detached timer exits with a failure status.
+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 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 gates, or the fail-closed state-directory error keeps new mutations blocked until you complete generation operator recovery.
-A `--dry-run` run of a `channels` or `policy` command takes no mutation lock, so you can still preview the change while mutations are blocked.
+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 keeps new mutations blocked until you complete exact-generation operator recovery. A `--dry-run` run of a `channels` or `policy` command takes no mutation lock, so you can still preview the change while mutations are blocked.
-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 stale generations first, and remove the containment generation last.
+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.
-### Preserve Managed MCP Policy
+### Preserve Live MCP Policy
-Before a manual Shields transition replaces a policy, NemoClaw requires the managed Model Context Protocol (MCP) entries to match 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 entries.
-If agreement is absent, a manual Shields transition refuses the replacement policy.
+`shields down` reads MCP policy entries from the current OpenShell policy and carries those exact live values into the temporary relaxed policy. It does not compare them to a NemoClaw ownership record.
-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 it retains policy ownership.
+Restoration reverses only the policy delta introduced by the active Shields transaction. Host-side changes made during the window, including edits to MCP entries, remain intact. The bounded before/forward artifacts are removed when recovery completes.
## Related Topics
diff --git a/docs/network-policy/apply-policy-presets.mdx b/docs/network-policy/apply-policy-presets.mdx
index b136dca0a0f..4ca11fe8939 100644
--- a/docs/network-policy/apply-policy-presets.mdx
+++ b/docs/network-policy/apply-policy-presets.mdx
@@ -4,15 +4,15 @@
title: "Apply Policy Presets"
sidebar-title: "Apply Policy Presets"
description: "Add, reapply, list, or remove policy presets for a running NemoClaw sandbox."
-description-agent: "Applies and manages policy presets for a running sandbox. Use when adding maintained integration access, previewing preset scope, reapplying an edited preset, removing access, or removing a preset the gateway enforces without a local record."
-keywords: ["nemoclaw policy presets", "policy add", "policy remove", "active on gateway missing from local state"]
+description-agent: "Applies and manages policy presets in the current OpenShell policy for a running sandbox."
+keywords: ["nemoclaw policy presets", "policy add", "policy remove", "openshell policy"]
content:
type: "how_to"
skill:
priority: 10
---
-Use policy presets to add reviewed network access to one running sandbox without replacing its current policy.
-NemoClaw records applied presets so rebuild and restore operations can replay them.
+
+Use policy presets to add reviewed network access to one running sandbox without replacing its current policy. NemoClaw provides the convenient merge and removal commands; OpenShell remains the only durable policy state.
Use `$$nemoclaw policy add` to merge a preset into the running policy.
@@ -22,9 +22,7 @@ Follow [Replace the Live Network Policy](replace-live-network-policy) only when
## Choose a Maintained Preset
-During onboarding, the selected [policy tier](../../reference/network-policies#policy-tiers) determines which maintained presets are enabled by default.
-The interactive preset screen lets you add or remove individual presets.
-Messaging channel choices are scoped to the active agent, so unsupported channel presets do not appear.
+During onboarding, the selected [policy tier](../../reference/network-policies#policy-tiers) determines which maintained presets are enabled by default. The interactive preset screen lets you add or remove individual presets. Messaging channel choices are scoped to the active agent, so unsupported channel presets do not appear.
List the presets available to the sandbox:
@@ -33,10 +31,12 @@ $$nemoclaw policy list
```
-For the maintained preset catalog and guided service workflows, refer to [Common Integration Policy Examples](../integration-policy-examples).
+ For the maintained preset catalog and guided service workflows, refer to [Common Integration
+ Policy Examples](../integration-policy-examples).
-For Deep Agents baseline, tier, Tavily, and observability preset behavior, refer to [Network Policies](../../reference/network-policies#policy-tiers).
+ For Deep Agents baseline, tier, Tavily, and observability preset behavior, refer to [Network
+ Policies](../../reference/network-policies#policy-tiers).
## Preview and Apply a Preset
@@ -66,27 +66,19 @@ Omit the preset name to use the interactive picker:
$$nemoclaw my-assistant policy add
```
-The picker requires a terminal on stdin.
-A run without a terminal, such as an SSH command without `-t`, a service unit, or a CI job, exits non-zero and reports that no input is available on stdin.
+The picker requires a terminal on stdin. A run without a terminal, such as an SSH command without `-t`, a service unit, or a CI job, exits non-zero and reports that no input is available on stdin.
-Pass a preset name with `--yes` for scripted workflows.
-Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` to use the same non-interactive flow through an environment variable.
-With that variable set, a missing preset name instead reports that non-interactive mode requires a preset name.
+Pass a preset name with `--yes` for scripted workflows. Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` to use the same non-interactive flow through an environment variable. With that variable set, a missing preset name instead reports that non-interactive mode requires a preset name.
## Reapply an Edited Preset
-Run the same `policy add` command after you edit a maintained or recorded custom preset.
-NemoClaw compares the preset with the live policy.
-If the content differs, it applies the changed content.
-You do not need to remove the preset first.
+Run the same `policy add` command after you edit a maintained preset or a custom source file. NemoClaw compares the preset with the live policy. If the content differs, it applies the changed content. You do not need to remove the preset first.
-The merge starts from the round-trippable base policy returned by `openshell policy get --base`.
-It excludes provider-composed `_provider_*` entries because OpenShell reserves that namespace and rejects it in `policy set`.
-Existing presets and baseline entries remain in place.
+The merge starts from the round-trippable base policy returned by `openshell policy get --base`. It excludes provider-composed `_provider_*` entries because OpenShell reserves that namespace and rejects it in `policy set`. Existing presets and baseline entries remain in place.
## List and Remove Presets
-List every preset recorded for the sandbox:
+List available presets and identify which ones match the current OpenShell policy:
```bash
$$nemoclaw policy list
@@ -111,46 +103,27 @@ $$nemoclaw my-assistant policy remove weather --yes
`policy remove` accepts maintained and custom preset names.
-## Remove a Preset the Gateway Enforces Without a Local Record
+## OpenShell Is the Source of Truth
-`policy list` marks a preset that the OpenShell gateway enforces while no local record explains it:
+`policy list` derives applied state by comparing preset content with the current OpenShell policy:
```bash
$$nemoclaw my-assistant policy list
```
-Expected output:
-
-```text
- ● github [source unverified] — GitHub.com and GitHub API access (git) (active on gateway, missing from local state)
-```
-
-`policy remove` accepts that preset:
+`policy remove` reads the live policy, removes the keys defined by the selected preset, writes the complete result, and verifies it:
```bash
$$nemoclaw my-assistant policy remove github --yes
```
-It narrows the live policy and clears whatever local record remains.
-
-When NemoClaw cannot reach the gateway, `policy remove ` has only the local record to check.
-It refuses an unrecorded preset and reports that it could not query the gateway, rather than treating an unanswered query as absence.
-The interactive picker lists the recorded presets only in that case.
+When NemoClaw cannot read the OpenShell policy, it refuses the mutation rather than falling back to local policy state.
## Understand Persistence
-Dynamic changes apply to the current live policy.
-NemoClaw also records maintained presets and custom presets applied through `--from-file` or `--from-dir`.
-The custom preset record includes the full YAML content.
-Snapshot restore and rebuild replay the recorded presets, even when the original custom file no longer exists.
-
-A sandbox that is absent from the local registry has nothing to record a preset against.
-For a maintained preset, `policy add` still applies it to the gateway and warns that `policy list` reports it as active on gateway, missing from local state.
-For a custom preset applied with `--from-file` or `--from-dir`, `policy add` reaches the gateway but exits non-zero, because a custom preset is discoverable only through the registry and would appear in neither `policy list` nor `status`.
-Recover or re-onboard the sandbox to restore the record, then re-apply any custom preset that failed this way.
+Dynamic changes exist only in the current live OpenShell policy. Maintained preset names are inferred by comparing their current content. Custom presets applied through `--from-file` or `--from-dir` use namespaced keys in that same live document so `policy list` and `policy remove` can discover them without a second registry.
-`$$nemoclaw rebuild` reapplies every recorded policy preset to the recreated sandbox.
-For baseline changes that apply to every future sandbox, follow [Change the Baseline Network Policy](change-baseline-network-policy).
+`$$nemoclaw rebuild` and snapshot clone hand the complete current OpenShell policy to sandbox creation. They do not reconstruct it from preset records, so trusted changes made through the OpenShell TUI or another host process are preserved too. For baseline changes that apply to every future sandbox, follow [Change the Baseline Network Policy](change-baseline-network-policy).
## Approve One Request
@@ -160,8 +133,7 @@ For one-off access, approve a blocked request in the OpenShell TUI:
openshell term
```
-Use the TUI to test a destination before deciding whether it belongs in a maintained or custom preset.
-For the complete approval workflow, refer to [Approve or Deny Network Requests](../approve-network-requests).
+Use the TUI to test a destination before deciding whether it belongs in a maintained or custom preset. For the complete approval workflow, refer to [Approve or Deny Network Requests](../approve-network-requests).
## Related Topics
diff --git a/docs/network-policy/create-custom-policy-presets.mdx b/docs/network-policy/create-custom-policy-presets.mdx
index 96916bb314b..965410bef23 100644
--- a/docs/network-policy/create-custom-policy-presets.mdx
+++ b/docs/network-policy/create-custom-policy-presets.mdx
@@ -11,12 +11,12 @@ content:
skill:
priority: 10
---
-Create a custom preset when a sandbox needs a reviewed endpoint that no maintained NemoClaw preset covers.
-Custom presets add scoped access to one sandbox without changing the baseline policy.
+
+Create a custom preset when a sandbox needs a reviewed endpoint that no maintained NemoClaw preset covers. Custom presets add scoped access to one sandbox without changing the baseline policy.
-Custom preset hosts bypass NemoClaw's review process and can widen sandbox egress.
-Review every host before applying a custom preset, especially when the file originates outside your team.
+ Custom preset hosts bypass NemoClaw's review process and can widen sandbox egress. Review every
+ host before applying a custom preset, especially when the file originates outside your team.
## Author a Preset
@@ -41,44 +41,36 @@ network_policies:
- { path: /path/to/requesting-binary }
```
-Replace `/path/to/requesting-binary` with the executable path reported for the blocked request in `openshell term`.
+Replace `/path/to/requesting-binary` with the exact executable path reported for the blocked request in `openshell term`.
+
-For Deep Agents Code, OpenShell commonly reports `/usr/local/bin/dcode` or `/opt/venv/bin/python3*`.
-Authorize only the process that needs the reviewed endpoint.
+ For Deep Agents Code, OpenShell commonly reports `/usr/local/bin/dcode` or
+ `/opt/venv/bin/python3*`. Authorize only the process that needs the reviewed endpoint.
-The top-level `preset.name` must be a lowercase RFC 1123 label with letters, digits, and hyphens.
-It must not collide with a maintained preset name such as `slack` or `pypi`.
-Rename `preset.name` if NemoClaw reports a collision.
-Custom preset `network_policies` entries must not use `npm_yarn`.
-NemoClaw reserves that key for the maintained `npm` preset and rejects the file before applying it.
+The top-level `preset.name` must be a lowercase RFC 1123 label with letters, digits, and hyphens. It must not collide with a maintained preset name such as `slack` or `pypi`. Rename `preset.name` if NemoClaw reports a collision. Custom preset `network_policies` entries must not use `npm_yarn`. NemoClaw reserves that key for the maintained `npm` preset and rejects the file before applying it.
-Each endpoint must name a specific host or a scoped subdomain wildcard such as `*.example.com`.
-NemoClaw rejects catch-all destinations, including `*`, `0.0.0.0`, `0.0.0.0/0`, `::`, and `::/0`.
-Rule matchers must match the endpoint protocol.
+Each endpoint must name a specific host or a scoped subdomain wildcard such as `*.example.com`. NemoClaw rejects catch-all destinations, including `*`, `0.0.0.0`, `0.0.0.0/0`, `::`, and `::/0`. Rule matchers must match the endpoint protocol.
-| Protocol | Rule fields |
-|----------|-------------|
-| REST | `method` and `path`; `method` accepts standard HTTP methods or `*` |
+| Protocol | Rule fields |
+| --------- | --------------------------------------------------------------------- |
+| REST | `method` and `path`; `method` accepts standard HTTP methods or `*` |
| WebSocket | `method` and `path`; `method` accepts `GET`, `WEBSOCKET_TEXT`, or `*` |
-| JSON-RPC | `method` only |
-| MCP | `method` with optional `tool` or `params.name` |
+| JSON-RPC | `method` only |
+| MCP | `method` with optional `tool` or `params.name` |
The same protocol-specific matcher shape applies to `deny_rules`.
-User-authored presets must not declare `allowed_ips` for ordinary endpoints.
-NemoClaw rejects that field in files passed through `--from-file` or `--from-dir` because it can widen the private ranges that OpenShell checks during SSRF protection.
-Use hostnames, ports, protocols, methods, paths, and binary restrictions instead.
-The only exception is the `host.openshell.internal` bridge endpoint for explicit sandbox-to-host service access.
+User-authored presets must not declare `allowed_ips` for ordinary endpoints. NemoClaw rejects that field in files passed through `--from-file` or `--from-dir` because it can widen the private ranges that OpenShell checks during SSRF protection. Use hostnames, ports, protocols, methods, paths, and binary restrictions instead. The only exception is the `host.openshell.internal` bridge endpoint for explicit sandbox-to-host service access.
## Admit a Private Host
-Use explicit private-host trust when a custom preset targets an operator-controlled endpoint on RFC1918, carrier-grade network address translation (CGNAT), or IPv6 unique local address space.
-This flow applies to REST, WebSocket, JSON-RPC, and MCP endpoint protocols.
+Use explicit private-host trust when a custom preset targets an operator-controlled endpoint on RFC1918, carrier-grade network address translation (CGNAT), or IPv6 unique local address space. This flow applies to REST, WebSocket, JSON-RPC, and MCP endpoint protocols.
-The `--trusted-private-host` option and `NEMOCLAW_TRUSTED_PRIVATE_HOSTS` grant the custom preset access to each exact matching private host.
-Review the preset, resolved addresses, requesting binaries, methods, and paths before you apply it.
+ The `--trusted-private-host` option and `NEMOCLAW_TRUSTED_PRIVATE_HOSTS` grant the custom preset
+ access to each matching exact private host. Review the preset, resolved addresses, requesting
+ binaries, methods, and paths before you apply it.
Pass the endpoint host with `--from-file` or `--from-dir`:
@@ -90,26 +82,13 @@ $$nemoclaw my-assistant policy add \
--dry-run
```
-The option is invalid for a built-in preset because maintained presets own their reviewed destinations.
-NemoClaw rejects unused, unrelated, wildcard, suffix, CIDR, URL-shaped, duplicate, or malformed `--trusted-private-host` declarations.
-It also rejects loopback, link-local, metadata, unspecified, multicast, documentation, translation, benchmarking, and other reserved ranges.
+The option is invalid for a built-in preset because maintained presets own their reviewed destinations. NemoClaw rejects unused, unrelated, wildcard, suffix, CIDR, URL-shaped, duplicate, or malformed `--trusted-private-host` declarations. It also rejects loopback, link-local, metadata, unspecified, multicast, documentation, translation, benchmarking, and other reserved ranges.
-As an alternative, set `NEMOCLAW_TRUSTED_PRIVATE_HOSTS` to a comma-separated list of exact hosts for the current command.
-NemoClaw combines the environment list with any `--trusted-private-host` options.
-It normalizes and deduplicates environment entries and ignores entries unrelated to the custom preset batch.
+As an alternative, set `NEMOCLAW_TRUSTED_PRIVATE_HOSTS` to a comma-separated list of exact hosts for the current command. NemoClaw combines the environment list with any `--trusted-private-host` options. It normalizes and deduplicates environment entries and ignores entries unrelated to the custom preset batch.
-After schema validation, NemoClaw resolves each declared endpoint and inserts every validated address as an `allowed_ips` value in memory.
-A trusted host can return both public and supported private addresses.
-NemoClaw pins every canonical answer.
-If any answer is a disallowed private, reserved, or special-purpose address, validation rejects the preset instead of discarding that answer.
-The dry-run output shows the generated pins for review.
-NemoClaw applies and records the transformed preset instead of the unpinned source file.
-Rebuild replays recorded pins from the sandbox registry without depending on the ambient environment.
-A snapshot does not grant private-host authority to a clean target by itself; reapply the source preset with explicit trust after a cross-sandbox restore.
+After schema validation, NemoClaw resolves each declared endpoint and inserts every validated address as an exact `allowed_ips` value in memory. An exact trusted host can return both public and supported private addresses. NemoClaw pins every canonical answer. If any answer is a disallowed private, reserved, or special-purpose address, validation rejects the preset instead of discarding that answer. The dry-run output shows the generated pins for review. NemoClaw applies the transformed preset directly to the current OpenShell policy instead of the unpinned source file. Rebuild and cross-sandbox snapshot restore carry those live pins forward as part of the complete OpenShell policy without depending on ambient DNS. Reapply the source preset with explicit trust only when you intend to refresh the trusted host's address pins or change its endpoint policy.
-To change a recorded address set, apply the source preset again with explicit trust.
-NemoClaw performs a new preflight and shows the changed pins before it applies them.
-Do not add `allowed_ips` to the source YAML.
+To change the live address set, apply the source preset again with explicit trust. NemoClaw performs a new preflight and shows the changed pins before it applies them. Do not add `allowed_ips` to the source YAML.
## Apply a Single File
@@ -120,8 +99,7 @@ $$nemoclaw my-assistant policy add --from-file ./presets/my-service-api.yaml --d
$$nemoclaw my-assistant policy add --from-file ./presets/my-service-api.yaml --yes
```
-NemoClaw records the complete YAML content with the sandbox.
-You can remove the preset later without keeping the original file.
+NemoClaw namespaces the preset keys in the current OpenShell policy. You can remove the preset later by name without keeping the original file while that live policy remains available.
## Apply Every File in a Directory
@@ -131,16 +109,11 @@ Apply preset files in lexicographic order:
$$nemoclaw my-assistant policy add --from-dir ./presets/ --yes
```
-Processing stops at the first failure.
-NemoClaw does not remove presets that it already applied.
-Fix the failing file and run the command again to continue.
+Processing stops at the first failure. NemoClaw does not remove presets that it already applied. Fix the failing file and run the command again to continue.
## Add a Preset to the Source Catalog
-Save a maintained local preset under `nemoclaw-blueprint/policies/presets/`.
-The filename without `.yaml` must match `preset.name`.
-The preset catalog reads `preset.name`, while `policy add ` loads `presets/.yaml`.
-A mismatch can list a preset that the named command cannot load.
+Save a maintained local preset under `nemoclaw-blueprint/policies/presets/`. The filename without `.yaml` must match `preset.name`. The preset catalog reads `preset.name`, while `policy add ` loads `presets/.yaml`. A mismatch can list a preset that the named command cannot load.
Apply the catalog preset by name:
@@ -148,37 +121,29 @@ Apply the catalog preset by name:
$$nemoclaw my-assistant policy add my-service-api
```
-Run the same command after editing the file.
-NemoClaw compares the preset with the live policy and applies changed content.
+Run the same command after editing the file. NemoClaw compares the preset with the live policy and applies changed content.
## Remove a Custom Preset
-Remove the preset by its recorded name:
+Remove the preset by its name:
```bash
$$nemoclaw my-assistant policy remove my-service-api --yes
```
-Run `$$nemoclaw policy list` to see every maintained and custom preset recorded for the sandbox.
+Run `$$nemoclaw policy list` to see every maintained and custom preset present in the current OpenShell policy.
## Configure a URL-Based MCP Server
-Prefer the managed workflow in [Add an MCP Server](../../manage-sandboxes/mcp-servers/add-an-mcp-server) when the server uses authenticated HTTPS Streamable HTTP.
-Use this custom policy recipe only for an agent-native URL registration that is outside the managed workflow.
-Adding a URL such as `https://mcp.example.com/mcp` can cause a denied CONNECT tunnel.
-The proxy returns `HTTP 403 Forbidden` when the target host is not in the default allowlist.
-The related MCP client output contains this message:
+Prefer the managed workflow in [Add an MCP Server](../../manage-sandboxes/mcp-servers/add-an-mcp-server) when the server uses authenticated HTTPS Streamable HTTP. Use this custom policy recipe only for an agent-native URL registration that is outside the managed workflow. Adding a URL such as `https://mcp.example.com/mcp` can cause a denied CONNECT tunnel. The proxy returns `HTTP 403 Forbidden` when the target host is not in the default allowlist. The related MCP client output contains this message:
```text
CONNECT tunnel failed, response 403
```
-This recipe applies only when URL-based MCP traffic uses the sandbox proxy and fails with this CONNECT response.
-An OAuth MCP login failure such as `getaddrinfo EAI_AGAIN` is a different transport problem.
-A direct-DNS path that bypasses the proxy is also a different problem.
-Widening this allowlist does not fix either case.
+This recipe applies only when URL-based MCP traffic uses the sandbox proxy and fails with this CONNECT response. An OAuth MCP login failure such as `getaddrinfo EAI_AGAIN` is a different transport problem. A direct-DNS path that bypasses the proxy is also a different problem. Widening this allowlist does not fix either case.
Add the MCP host, Streamable HTTP route, required methods, and only the binary that opens the connection:
@@ -202,37 +167,25 @@ network_policies:
- { path: /usr/local/bin/node }
```
-Streamable HTTP clients can use `DELETE` on the same endpoint to terminate a session.
-Keep that method scoped to the MCP route.
-Do not replace the route with `/**` unless the server contract requires every path.
+Streamable HTTP clients can use `DELETE` on the same endpoint to terminate a session. Keep that method scoped to the exact MCP route. Do not replace the route with `/**` unless the server contract requires every path.
-Save the file as `nemoclaw-blueprint/policies/presets/my-mcp.yaml`.
-Apply it by name:
+Save the file as `nemoclaw-blueprint/policies/presets/my-mcp.yaml`. Apply it by name:
```bash
$$nemoclaw my-assistant policy add my-mcp
```
-NemoClaw previews the effective egress scope and prompts for confirmation before applying it.
-For a publicly routed host that passes SSRF checks, invoke the MCP tool again and confirm that the CONNECT tunnel succeeds.
+NemoClaw previews the effective egress scope and prompts for confirmation before applying it. For a publicly routed host that passes SSRF checks, invoke the MCP tool again and confirm that the CONNECT tunnel succeeds.
-The `binaries` list must include only the process that opens the connection.
-The example assumes the Node runtime opens the MCP connection.
-Replace the example path with the requesting binary that OpenShell reports in `openshell term`.
-Shell-invoked clients need their own binary path, such as `/usr/bin/curl`.
-Confirm a candidate path inside the sandbox:
+The `binaries` list must include only the process that opens the connection. The example assumes the Node runtime opens the MCP connection. Replace the example path with the requesting binary that OpenShell reports in `openshell term`. Shell-invoked clients need their own binary path, such as `/usr/bin/curl`. Confirm a candidate path inside the sandbox:
```bash
$$nemoclaw my-assistant exec -- which node
```
-A preset with an endpoint but no matching binary authorizes no process, so requests still fail.
-OpenShell uses `protocol: rest` for this HTTP-based policy even though Streamable HTTP MCP carries JSON-RPC.
+A preset with an endpoint but no matching binary authorizes no process, so requests still fail. OpenShell uses `protocol: rest` for this HTTP-based policy even though Streamable HTTP MCP carries JSON-RPC.
-An allowlist entry does not disable OpenShell SSRF protection or create host routes.
-If the hostname resolves to a private, loopback, or link-local address, establish the required host or VPN route.
-Then follow the approved private-destination configuration.
-Refer to [Agent cannot reach a host-side HTTP service](../../reference/troubleshooting#agent-cannot-reach-a-host-side-http-service) for routing and private-destination diagnostics.
+An allowlist entry does not disable OpenShell SSRF protection or create host routes. If the hostname resolves to a private, loopback, or link-local address, establish the required host or VPN route. Then follow the approved private-destination configuration. Refer to [Agent cannot reach a host-side HTTP service](../../reference/troubleshooting#agent-cannot-reach-a-host-side-http-service) for routing and private-destination diagnostics.
diff --git a/docs/network-policy/customize-network-policy.mdx b/docs/network-policy/customize-network-policy.mdx
index 90fc949b8a4..0b51c24bf54 100644
--- a/docs/network-policy/customize-network-policy.mdx
+++ b/docs/network-policy/customize-network-policy.mdx
@@ -11,22 +11,27 @@ content:
skill:
priority: 10
---
-Choose the policy workflow that matches the scope and persistence of the network access change.
-NemoClaw declares sandbox policy in YAML, and [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) enforces it at runtime.
+
+Choose the policy workflow that matches the scope and persistence of the network access change. NemoClaw declares sandbox policy in YAML, and [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) enforces it at runtime.
| Goal | Use this workflow |
-|---|---|
+| --- | --- |
| Change every future sandbox for an agent | [Change the Baseline Network Policy](configure-policies/change-baseline-network-policy) |
| Add or remove a maintained preset for one sandbox | [Apply Policy Presets](configure-policies/apply-policy-presets) |
| Add a reviewed endpoint that no maintained preset covers | [Create Custom Policy Presets](configure-policies/create-custom-policy-presets) |
+
-| Allow direct TLS negotiation for an endpoint | [Configure Raw TLS Passthrough](configure-policies/configure-raw-tls-passthrough) |
+ | Allow direct TLS negotiation for an exact endpoint | [Configure Raw TLS
+ Passthrough](configure-policies/configure-raw-tls-passthrough) |
-| Replace the complete live policy | [Replace the Live Network Policy](configure-policies/replace-live-network-policy) |
+| Replace the complete live policy | [Replace the Live Network
+Policy](configure-policies/replace-live-network-policy) |
-| Give the sandbox agent a redacted policy summary | [Explain Network Policy to Agents](explain-network-policy-to-agents) |
+ | Give the sandbox agent a redacted policy summary | [Explain Network Policy to
+ Agents](explain-network-policy-to-agents) |
-| Approve or deny one blocked request | [Approve or Deny Network Requests](approve-network-requests) |
+| Approve or deny one blocked request | [Approve or Deny Network Requests](approve-network-requests)
+|
If a sandbox needs an HTTP service on the host, expose the service on a host IP that the OpenShell gateway can reach.
@@ -36,11 +41,12 @@ Refer to [Agent cannot reach a host-side HTTP service](../reference/troubleshoot
-Adding a host to the egress policy permits a connection only when the endpoint, port, method, and binary rules match.
-OpenShell applies SSRF protection separately.
-It can deny a request when the final address resolves to a loopback, private, link-local, or blocked internal range.
-If a package installer or browser download still fails after you allow the public host, install the binary at build time.
-Use [`$$nemoclaw onboard --from`](../reference/commands#--from-dockerfile) instead of runtime egress.
+ Adding a host to the egress policy permits a connection only when the endpoint, port, method, and
+ binary rules match. OpenShell applies SSRF protection separately. It can deny a request when the
+ final address resolves to a loopback, private, link-local, or blocked internal range. If a package
+ installer or browser download still fails after you allow the public host, install the binary at
+ build time. Use [`$$nemoclaw onboard --from`](../reference/commands#--from-dockerfile) instead of
+ runtime egress.
## Static Changes
@@ -50,32 +56,34 @@ Use [`$$nemoclaw onboard --from`](../reference/commands#--from-dockerfile) inste
-
+
-Static changes modify the policy source that NemoClaw reads during sandbox creation.
-Follow [Change the Baseline Network Policy](configure-policies/change-baseline-network-policy) to edit the agent policy file, rerun onboarding, and verify the result.
+Static changes modify the policy source that NemoClaw reads during sandbox creation. Follow [Change the Baseline Network Policy](configure-policies/change-baseline-network-policy) to edit the agent policy file, rerun onboarding, and verify the result.
## Dynamic Changes
-Dynamic changes update a running sandbox.
-Use [Apply Policy Presets](configure-policies/apply-policy-presets) for reviewed additions that NemoClaw records and replays.
+Dynamic changes update the OpenShell policy for a running sandbox. Use [Apply Policy Presets](configure-policies/apply-policy-presets) for convenient reviewed additions. NemoClaw reads, modifies, writes, and verifies the live OpenShell policy without recording a second desired-policy state.
+
-Use [Approve or Deny Network Requests](approve-network-requests) for one-off access.
-Use [Replace the Live Network Policy](configure-policies/replace-live-network-policy) only when a preset cannot express the complete change.
+Use [Approve or Deny Network Requests](approve-network-requests) for one-off access. Use [Replace
+the Live Network Policy](configure-policies/replace-live-network-policy) only when a preset cannot
+express the complete change.
## Policy Presets
-Maintained policy presets cover common integrations and package services.
-Follow [Apply Policy Presets](configure-policies/apply-policy-presets) to preview, apply, reapply, list, or remove them.
+Maintained policy presets cover common integrations and package services. Follow [Apply Policy Presets](configure-policies/apply-policy-presets) to preview, apply, reapply, list, or remove them.
+
-For guided service workflows, refer to [Common Integration Policy Examples](integration-policy-examples).
+ For guided service workflows, refer to [Common Integration Policy
+ Examples](integration-policy-examples).
-Review [Network Policies](../reference/network-policies#policy-tiers) for the maintained presets available to Deep Agents.
+ Review [Network Policies](../reference/network-policies#policy-tiers) for the maintained presets
+ available to Deep Agents.
## Custom Preset Files
@@ -85,13 +93,13 @@ Review [Network Policies](../reference/network-policies#policy-tiers) for the ma
-
+
-Custom preset files add reviewed endpoint access without changing the baseline.
-Follow [Create Custom Policy Presets](configure-policies/create-custom-policy-presets) to author, validate, apply, and remove a custom preset.
+Custom preset files add reviewed endpoint access without changing the baseline. Follow [Create Custom Policy Presets](configure-policies/create-custom-policy-presets) to author, validate, apply, and remove a custom preset.
+
-That page also contains the URL-based MCP server recipe formerly located in this guide.
+ That page also contains the URL-based MCP server recipe formerly located in this guide.
@@ -100,8 +108,7 @@ That page also contains the URL-based MCP server recipe formerly located in this
-Some endpoints require direct TLS negotiation and fail through inspected L7 proxying.
-Follow [Configure Raw TLS Passthrough](configure-policies/configure-raw-tls-passthrough) for the bounded `access: full` and `tls: skip` recipe.
+Some endpoints require direct TLS negotiation and fail through inspected L7 proxying. Follow [Configure Raw TLS Passthrough](configure-policies/configure-raw-tls-passthrough) for the bounded `access: full` and `tls: skip` recipe.
@@ -109,23 +116,24 @@ Follow [Configure Raw TLS Passthrough](configure-policies/configure-raw-tls-pass
-OpenShell `policy set` replaces the complete live policy.
-Follow [Replace the Live Network Policy](configure-policies/replace-live-network-policy) to export the round-trippable base, preserve existing entries, and apply a validated replacement.
+OpenShell `policy set` replaces the complete live policy. Follow [Replace the Live Network Policy](configure-policies/replace-live-network-policy) to export the round-trippable base, preserve existing entries, and apply a validated replacement.
## Agent Policy Context
-Agents need a redacted view of active presets and policy verification state.
-Follow [Explain Network Policy to Agents](explain-network-policy-to-agents) to print or refresh that context and interpret failure classifications.
+Agents need a redacted view of active presets and policy verification state. Follow [Explain Network Policy to Agents](explain-network-policy-to-agents) to print or refresh that context and interpret failure classifications.
## Related Topics
-- [Common Integration Policy Examples](integration-policy-examples) provides maintained service workflows.
+ - [Common Integration Policy Examples](integration-policy-examples) provides maintained service
+ workflows.
-- [Network Policies](../reference/network-policies) is the canonical policy reference.
-- [OpenShell Policy Schema](https://docs.nvidia.com/openshell/latest/reference/policy-schema.html) provides the complete YAML schema.
-- [OpenShell Sandbox Policies](https://docs.nvidia.com/openshell/latest/sandboxes/policies.html) explains OpenShell-layer policy iteration.
+- [Network Policies](../reference/network-policies) is the canonical policy reference. - [OpenShell
+Policy Schema](https://docs.nvidia.com/openshell/latest/reference/policy-schema.html) provides the
+complete YAML schema. - [OpenShell Sandbox
+Policies](https://docs.nvidia.com/openshell/latest/sandboxes/policies.html) explains OpenShell-layer
+policy iteration.
diff --git a/docs/network-policy/explain-network-policy-to-agents.mdx b/docs/network-policy/explain-network-policy-to-agents.mdx
index a225323bae8..7c4020ec832 100644
--- a/docs/network-policy/explain-network-policy-to-agents.mdx
+++ b/docs/network-policy/explain-network-policy-to-agents.mdx
@@ -12,8 +12,8 @@ skill:
priority: 10
agent-variants: ["openclaw", "hermes"]
---
-Use `policy explain` to give a sandbox agent a compact, redacted view of its active network policy.
-The summary helps the agent distinguish policy denials, missing credentials, unsupported capabilities, and upstream failures.
+
+Use `policy explain` to give a sandbox agent a compact, redacted view of its active network policy. The summary helps the agent distinguish policy denials, missing credentials, unsupported capabilities, and upstream failures.
## Print the Policy Context
@@ -37,6 +37,7 @@ Refresh the file without changing policy:
```bash
$$nemoclaw my-assistant policy explain --write
```
+
For Hermes, use the printed Markdown or JSON through an operator-controlled prompt or file workflow.
@@ -45,54 +46,37 @@ The `--write` target is the OpenClaw workspace and is not a Hermes agent-context
## Understand Redaction
-The summary includes the recorded tier, applied presets, allowed host categories, known presets that are not applied, and policy management commands.
-It also explains the support boundaries between NemoClaw, OpenShell, and the agent.
+The summary includes the inferred tier when available, applied presets, allowed host categories, known presets that are not applied, and policy management commands. It also explains the support boundaries between NemoClaw, OpenShell, and the agent.
-The output omits network rule bodies, credential metadata, and binary allowlists.
-It includes only host stems and category-level summaries.
-NemoClaw drops private, loopback, link-local, metadata, unique-local, reserved, CGNAT, benchmarking, and internal-suffix hosts from `allowedHostCategories`.
-It reports their count in `redactedHostCount`.
+The output omits network rule bodies, credential metadata, and binary allowlists. It includes only host stems and category-level summaries. NemoClaw drops private, loopback, link-local, metadata, unique-local, reserved, CGNAT, benchmarking, and internal-suffix hosts from `allowedHostCategories`. It reports their count in `redactedHostCount`.
## Interpret Verification Status
Each active preset includes a `verification` value:
| Status | Meaning |
-|--------|---------|
-| `verified` | The registry lists the preset, and the gateway confirms enforcement. |
-| `registry-only` | The registry lists the preset, but the gateway does not enforce it. Treat the allowed hosts as unverified. |
-| `gateway-only` | The gateway enforces a preset that the registry does not list. |
-| `agent-base` | The gateway enforces this preset because it belongs to the agent's own base policy (`agents//policy-additions.yaml`), not because the operator applied it. It is active, not drift. `policy add` is unnecessary and would record the preset as operator-applied. |
+| --- | --- |
+| `verified` | The current OpenShell policy contains the preset content. |
| `gateway-unavailable` | NemoClaw could not probe the gateway. Treat the report as advisory until the gateway is reachable. |
## Classify a Failed Request
The classifier evaluates conditions in this order:
-1. `unsupported` means the active agent does not offer the asserted capability.
- Surface the limitation without retrying.
-2. `missing-approval` with high confidence means a host on an applied preset returned HTTP 401.
- The network path is open, but credentials are missing or invalid.
-3. `missing-approval` with low confidence means a host on an applied preset returned HTTP 403.
- Confirm credentials, then inspect the effective policy for a method, path, protocol, or binary denial.
-4. `blocked-by-policy` means no applied preset allows the host or the request returned a network-block error.
- Apply an applicable preset or create a custom preset.
-5. `unknown` means no classification matched.
- Surface the underlying error.
+1. `unsupported` means the active agent does not offer the asserted capability. Surface the limitation without retrying.
+2. `missing-approval` with high confidence means a host on an applied preset returned HTTP 401. The network path is open, but credentials are missing or invalid.
+3. `missing-approval` with low confidence means a host on an applied preset returned HTTP 403. Confirm credentials, then inspect the effective policy for a method, path, protocol, or binary denial.
+4. `blocked-by-policy` means no applied preset allows the host or the request returned a network-block error. Apply an applicable preset or create a custom preset.
+5. `unknown` means no classification matched. Surface the underlying error.
-Network-block error codes include `EHOSTUNREACH`, `ENETUNREACH`, `ENOTFOUND`, `ECONNREFUSED`, `ETIMEDOUT`, and `EAI_AGAIN`.
-A block code on a host from a `registry-only` or `gateway-unavailable` preset produces a low-confidence policy verdict.
-A block code on a host from a `verified`, `gateway-only`, or `agent-base` preset stays `unknown` with high confidence because the gateway confirmed enforcement.
+Network-block error codes include `EHOSTUNREACH`, `ENETUNREACH`, `ENOTFOUND`, `ECONNREFUSED`, `ETIMEDOUT`, and `EAI_AGAIN`. A block code while the OpenShell policy is unavailable produces a low-confidence policy verdict. A block code for an entry verified in the current OpenShell policy stays `unknown` with high confidence because policy presence alone does not distinguish credential and application failures.
-Each verdict includes `confidence` set to `high` or `low`.
-Low confidence means the agent must report multiple possibilities instead of treating one next step as authoritative.
+Each verdict includes `confidence` set to `high` or `low`. Low confidence means the agent must report multiple possibilities instead of treating one next step as authoritative.
-For `blocked-by-policy`, run `$$nemoclaw policy add ` or follow [Custom Preset Files](customize-network-policy#custom-preset-files).
-For `missing-approval`, confirm the API token and scopes.
-For `unsupported`, surface the limitation without retrying.
+For `blocked-by-policy`, run `$$nemoclaw policy add ` or follow [Custom Preset Files](customize-network-policy#custom-preset-files). For `missing-approval`, confirm the API token and scopes. For `unsupported`, surface the limitation without retrying.
## Related Topics
-- [Apply Policy Presets](configure-policies/apply-policy-presets) changes the recorded preset set.
+- [Apply Policy Presets](configure-policies/apply-policy-presets) changes the current OpenShell policy.
- [Create Custom Policy Presets](configure-policies/create-custom-policy-presets) adds a reviewed custom destination.
- [Network Policies](../reference/network-policies) explains policy enforcement and tiers.
diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx
index 62928f9e58c..90c20148885 100644
--- a/docs/reference/commands.mdx
+++ b/docs/reference/commands.mdx
@@ -5,33 +5,30 @@ 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"]
+keywords:
+ [
+ "nemoclaw cli commands",
+ "nemoclaw command reference",
+ "nemo-deepagents commands",
+ "dcode commands",
+ ]
content:
type: "reference"
---
+
-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).
+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).
-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).
+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).
-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).
+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).
@@ -39,18 +36,12 @@ For guidance on choosing between the agent CLIs and the underlying `openshell` C
-Use `$$nemoclaw` for the OpenClaw variant.
-OpenClaw is the default agent for `$$nemoclaw onboard` unless you select another installed agent with `--agent ` or set `NEMOCLAW_AGENT=`.
-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`.
+Use `$$nemoclaw` for the OpenClaw variant. OpenClaw is the default agent for `$$nemoclaw onboard` unless you select another installed agent with `--agent ` or set `NEMOCLAW_AGENT=`. 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`.
-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`.
+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
@@ -60,10 +51,7 @@ nemohermes my-sandbox connect # connects to a Hermes sandbox
-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.
+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
@@ -79,7 +67,7 @@ nemo-deepagents my-sandbox connect # connects to a Deep Agents sandbox
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 shields status` on the host |
@@ -91,17 +79,12 @@ Use host-side `$$nemoclaw shields status|up|down` commands to inspect
-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.
+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.
-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.
+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
@@ -111,22 +94,17 @@ dcode status
printf '%s\n' '{"worker":"worker-17"}' | dcode tools call-read-only worker_task_context --json
```
-`dcode tools call-read-only TOOL --json` invokes one coherently read-only managed MCP tool without model participation.
-It requires one JSON object on standard input and writes one bounded JSON result envelope.
-For the JSON schema, status and exit behavior, output limit, and read-only MCP call requirements, refer to [Run Deep Agents Code](/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code).
+`dcode tools call-read-only TOOL --json` invokes one exact, coherently read-only managed MCP tool without model participation. It requires one JSON object on standard input and writes one bounded JSON result envelope. For the JSON schema, status and exit behavior, output limit, and read-only MCP call requirements, refer to [Run Deep Agents Code](/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code).
## Hosted Installer Options
-The hosted installer accepts options after `bash -s --`.
-These options control installation and the onboarding run that follows it.
+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.
+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 | \
@@ -144,15 +122,9 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | \
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` and `NEMOCLAW_MODEL` before onboarding.
-The dedicated vLLM onboarder accepts `NEMOCLAW_VLLM_MODEL` only when the catalog resolves it to the matching fixed recipe.
-It rejects a model that does not resolve to that recipe and all `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` values before it installs vLLM.
-Set `NEMOCLAW_VLLM_PORT` before installation to publish the fixed serving recipe on another host port.
+The profile selects a fixed catalog model and serving command from the managed-inference catalog. The hosted installer rejects `NEMOCLAW_PROVIDER` and `NEMOCLAW_MODEL` before onboarding. The dedicated vLLM onboarder accepts `NEMOCLAW_VLLM_MODEL` only when the catalog resolves it to the matching fixed recipe. It rejects a model that does not resolve to that recipe and all `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` values before it installs vLLM. Set `NEMOCLAW_VLLM_PORT` before installation to publish the fixed serving recipe on another host port.
-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).
+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).
### `--defer-onboarding`
@@ -178,12 +150,7 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | \
## 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.
+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
@@ -191,8 +158,7 @@ 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.
+Show the top-level usage summary and command groups. Running `$$nemoclaw` with no arguments shows the same help output.
```bash
$$nemoclaw help
@@ -208,11 +174,7 @@ $$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 ...` 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.
+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 ...` 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.
@@ -237,8 +199,7 @@ Start a new shell session to refresh the cached sandbox names after creating or
### `$$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.
+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]
@@ -248,9 +209,7 @@ If the gateway is not running, Kubernetes allocatable fields are omitted and hos
### `$$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`.
+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]
@@ -260,9 +219,7 @@ For capability IDs, evidence bounds, and compatibility guidance, refer to [Syste
### `$$nemoclaw agents list`
-List the installed agent runtimes that can be selected with `$$nemoclaw onboard --agent `.
-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.
+List the installed agent runtimes that can be selected with `$$nemoclaw onboard --agent `. 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
@@ -278,9 +235,7 @@ 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.
+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
@@ -292,14 +247,11 @@ Use `--json` for machine-readable output with the same profile fields.
$$nemoclaw profiles list --json
```
-Use the stable `id` value with `$$nemoclaw onboard --profile `.
-Display names are accepted when they identify exactly one profile, but stable IDs are suitable for scripts and automation.
+Use the stable `id` value with `$$nemoclaw onboard --profile `. 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, selects the managed image (or builds an explicit custom Dockerfile), and creates the sandbox.
-Use this command for new installs and for recreating a sandbox after changes to policy or configuration.
+Run the interactive setup wizard (recommended for new installs). The wizard creates an OpenShell gateway, registers inference providers, selects the exact managed image (or builds an explicit custom Dockerfile), 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 ] [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--apf-interceptor] [--gpu | --no-gpu] [--from ] [--name ] [--host-mount ] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device ] [--vllm-gpu-device ] [--agent ] [--agents ] [--tool-disclosure ] [--observability | --no-observability] [--control-ui-port ] [--events=jsonl] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software]
@@ -314,12 +266,7 @@ nemohermes onboard [options]
nemoclaw onboard --agent hermes [options]
```
-The experimental Portable Hermes path records `pending`, `configuring`, and `active` lifecycle phases under the current user's rootless Podman authority.
-If onboarding stops in `pending` or `configuring`, correct the reported condition and run `nemohermes onboard --experimental-profile portable --resume`.
-Mutation, connection, and recovery commands do not act on an incomplete receipt; `status` and `doctor` report its phase.
-After the receipt reaches `active`, the supported runtime actions are `launch`, `connect`, `recover`, `start`, and `stop`; `status` and read-only `doctor` provide diagnostics.
-Other sandbox commands fail before their action runs while the Portable Hermes receipt exists.
-The supported commands revalidate the receipt-owned Podman container and do not fall back to Docker.
+The experimental Portable Hermes path records `pending`, `configuring`, and `active` lifecycle phases under the current user's rootless Podman authority. If onboarding stops in `pending` or `configuring`, correct the reported condition and run `nemohermes onboard --experimental-profile portable --resume`. Mutation, connection, and recovery commands do not act on an incomplete receipt; `status` and `doctor` report its phase. After the receipt reaches `active`, the supported runtime actions are `launch`, `connect`, `recover`, `start`, and `stop`; `status` and read-only `doctor` provide diagnostics. Other sandbox commands fail before their action runs while the Portable Hermes receipt exists. The supported commands revalidate the receipt-owned Podman container and do not fall back to Docker.
@@ -333,124 +280,80 @@ nemoclaw onboard --agent langchain-deepagents-code [options]
-`--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`.
+`--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 `
-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.
+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
```
-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.
+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, declared model, served model alias, runtime image, support state, and download estimates before confirmation.
-When onboarding reuses a running vLLM server, its `/v1/models` response must match the requested profile's served alias or declared model root.
-Otherwise, onboarding stops before it records a route that the profile does not declare.
-After creation, human status shows the profile, recipe, and catalog digest; JSON status includes the complete secret-free `servingProfileProvenance` record for diagnostics and automation.
+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, declared model, served model alias, runtime image, support state, and download estimates before confirmation. When onboarding reuses a running vLLM server, its `/v1/models` response must match the requested profile's served alias or declared model root. Otherwise, onboarding stops before it records a route that the profile does not declare. 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 ` 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.
+On Linux and Windows Subsystem for Linux 2 (WSL2), repeat `--host-mount ` 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:
+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":"","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":{}}}
+{
+ "schemaVersion": 1,
+ "session": "",
+ "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`.
+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.
+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 `.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 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.
+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.
-OpenClaw onboarding does not enter the `complete` state until NemoClaw proves that the local CLI operator pairing is settled.
-Ordinary onboarding first observes the canonical local CLI device.
-If the device is pairing-only, the host runs one bounded request producer on the owning gateway.
-The in-sandbox watcher is the only component that approves the ordinary onboarding upgrade.
-The host observes through any same-device pending state and verifies the final settled state without sending an approval.
-Portable onboarding accepts one exact already-pending canonical write upgrade, avoids a duplicate producer, and still requires strict same-device settlement before completion.
-The paired device must have exactly the `operator.pairing` and `operator.write` scopes.
-Any pairing request considered during bounded repair must request exactly those scopes.
-The active token and client authorization must have exactly the `operator.pairing`, `operator.read`, and `operator.write` scopes.
-NemoClaw rejects every extra, missing, unknown, malformed, or ambiguous scope or identity shape.
-If the policy preset step is incomplete, NemoClaw performs no pairing request or approval writes and publishes no launch-readiness evidence.
-Selected Portable onboarding also stops when its lifecycle receipt is missing, invalid, legacy, or incompatible.
-A failed check leaves onboarding incomplete and tells you to resume or rerun onboarding.
+OpenClaw onboarding does not enter the `complete` state until NemoClaw proves that the local CLI operator pairing is settled. Ordinary onboarding first observes the canonical local CLI device. If the device is pairing-only, the host runs one bounded request producer on the owning gateway. The in-sandbox watcher is the only component that approves the ordinary onboarding upgrade. The host observes through any same-device pending state and verifies the final settled state without sending an approval. Portable onboarding accepts one exact already-pending canonical write upgrade, avoids a duplicate producer, and still requires strict same-device settlement before completion. The paired device must have exactly the `operator.pairing` and `operator.write` scopes. Any pairing request considered during bounded repair must request exactly those scopes. The active token and client authorization must have exactly the `operator.pairing`, `operator.read`, and `operator.write` scopes. NemoClaw rejects every extra, missing, unknown, malformed, or ambiguous scope or identity shape. If the policy preset step is incomplete, NemoClaw performs no pairing request or approval writes and publishes no launch-readiness evidence. Selected Portable onboarding also stops when its lifecycle receipt is missing, invalid, legacy, or incompatible. A failed check leaves onboarding incomplete and tells you to resume or rerun onboarding.
-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.
+ 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.
-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`.
+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`.
If onboarding cannot complete after sandbox creation, NemoClaw preserves the sandbox and records its create-attempt label.
When available, NemoClaw also records a durable identity fingerprint and verified policy evidence for recovery.
@@ -466,44 +369,21 @@ $$nemoclaw onboard --fresh --name
-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 recorded name and type and the same credential-key set.
-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.
+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.
-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.
+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.
+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 --recreate-sandbox` when you intentionally want onboarding to replace that sandbox with a new provider, model, agent, or startup setting.
-Use `$$nemoclaw rebuild` when you want NemoClaw to recreate the sandbox from its recorded registry metadata without changing those selections.
+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 --recreate-sandbox` when you intentionally want onboarding to replace that sandbox with a new provider, model, agent, or startup setting. Use `$$nemoclaw rebuild` when you want NemoClaw to recreate the sandbox from its recorded registry metadata without changing those selections.
#### `--apf-interceptor`
-Use this option to request a policyless sandbox creation for an APF-interceptor flow.
-This option currently supports providerless sandbox creation only.
-APF onboarding with an inference provider and model is not yet supported.
-APF onboarding with an OpenShell provider for a Model Context Protocol (MCP) server is also not yet supported.
-OpenShell cannot bind provider attachment to the new sandbox's verified immutable ID.
-If the prepared plan contains any provider, NemoClaw exits before it:
+Use this option to request a policyless sandbox creation for an APF-interceptor flow. This option currently supports providerless sandbox creation only. APF onboarding with an inference provider and model is not yet supported. APF onboarding with an OpenShell provider for a Model Context Protocol (MCP) server is also not yet supported. OpenShell cannot bind provider attachment to the new sandbox's verified immutable ID. If the prepared plan contains any provider, NemoClaw exits before it:
- Creates the sandbox.
- Registers or changes credentials.
@@ -511,104 +391,72 @@ If the prepared plan contains any provider, NemoClaw exits before it:
The option requires these conditions:
-- Start a new onboarding session.
- Use `--fresh` when a saved onboarding session exists.
+- Start a new onboarding session. Use `--fresh` when a saved onboarding session exists.
- Select a sandbox name that has no registry entry or live OpenShell sandbox.
- Keep the active global policy absent.
- Do not combine the option with `--resume` or `--recreate-sandbox`.
- Do not select the Portable experimental profile.
-NemoClaw omits a caller policy from every sandbox creation attempt.
-After creation, NemoClaw binds the returned durable sandbox identity and verifies its effective policy.
-The policy must be sandbox-scoped and contain every policy entry required by the prepared configuration.
-NemoClaw then records the policy as externally managed and read-only.
-This verification does not establish that APF injected the policy.
+NemoClaw omits a caller policy from every sandbox creation attempt. After creation, NemoClaw binds the returned durable sandbox identity and verifies its effective policy. The policy must be sandbox-scoped and contain every policy entry required by the prepared configuration. NemoClaw stores no policy owner, receipt, or desired state; later policy commands read OpenShell directly. This verification does not establish that APF injected the policy.
```bash
$$nemoclaw onboard --fresh --apf-interceptor --name my-apf-sandbox
```
-If post-create verification or native GPU fallback fails after OpenShell may have created the sandbox, NemoClaw preserves the incomplete sandbox because automatic deletion would use its mutable name.
-Do not destroy that sandbox by name.
-Retain the reported sandbox name, create-attempt label, and durable identity fingerprint for comparison only.
-If OpenShell did not return the fingerprint, recovery remains blocked until an administrator resolves the create-attempt label to one exact sandbox.
-Ask an OpenShell administrator to obtain the exact live durable ID, verify it against the fingerprint, and use an identity-bound removal procedure.
-This onboarding mode does not support `--resume` or `--recreate-sandbox`, regardless of whether sandbox creation began.
-After the administrator confirms identity-bound removal, repeat the original command with `--fresh` and a new name.
+ If post-create verification or native GPU fallback fails after OpenShell may have created the
+ sandbox, NemoClaw preserves the incomplete sandbox because automatic deletion would use its
+ mutable name. Do not destroy that sandbox by name. Retain the reported sandbox name,
+ create-attempt label, and durable identity fingerprint for comparison only. If OpenShell did not
+ return the fingerprint, recovery remains blocked until an administrator resolves the
+ create-attempt label to one exact sandbox. Ask an OpenShell administrator to obtain the exact live
+ durable ID, verify it against the fingerprint, and use an identity-bound removal procedure. This
+ onboarding mode does not support `--resume` or `--recreate-sandbox`, regardless of whether sandbox
+ creation began. After the administrator confirms identity-bound removal, repeat the original
+ command with `--fresh` and a new name.
#### `--tool-disclosure `
-Choose how the selected agent presents its session-authorized tools to the model.
-Outside the Portable experimental profile, `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.
+Choose how the selected agent presents its session-authorized tools to the model. Outside the Portable experimental profile, `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 non-Portable sandbox defaults to `progressive` when neither is set.
-Fresh Portable onboarding defaults to `direct` when the flag is absent, even when `NEMOCLAW_TOOL_DISCLOSURE` is set.
-Pass `--tool-disclosure progressive` explicitly to select progressive disclosure for a fresh Portable sandbox.
-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:
+The flag takes precedence over `NEMOCLAW_TOOL_DISCLOSURE`. A new non-Portable sandbox defaults to `progressive` when neither is set. Fresh Portable onboarding defaults to `direct` when the flag is absent, even when `NEMOCLAW_TOOL_DISCLOSURE` is set. Pass `--tool-disclosure progressive` explicitly to select progressive disclosure for a fresh Portable sandbox. 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
```
-Outside the Portable experimental profile, recreation without an explicit flag or environment value preserves the recorded setting and only falls back to `progressive` for legacy state.
-A Portable resume without the flag preserves the mode recorded by the interrupted session.
-Resuming an interrupted session with a different explicit setting fails with a conflict instead of changing behavior mid-session.
+Outside the Portable experimental profile, recreation without an explicit flag or environment value preserves the recorded setting and only falls back to `progressive` for legacy state. A Portable resume without the flag preserves the mode recorded by the interrupted session. Resuming an interrupted session with a different explicit setting fails with a conflict instead of changing behavior mid-session.
#### `--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.
+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 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.
+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.
+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.
+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.
-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 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:
+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
@@ -621,100 +469,51 @@ Base-image selection follows this precedence:
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 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 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.
-
-For explicit base-image overrides, 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.
+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.
-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 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.
+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.
-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.
+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.
-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`.
+ 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`.
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`:
+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 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.
+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= 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`.
+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`.
-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.
+ 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.
-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.
+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 Arm64 or Linux x86_64 NVIDIA GPU host, 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)`.
-On DGX Spark, the recommended profile appears as **Managed llama.cpp: NVIDIA Nemotron 3 Nano 30B-A3B on one DGX Spark (recommended)**.
-On Linux x86_64, the recommended profile identifies one NVIDIA GPU.
-Meta Muse Glimmer remains available on DGX Spark 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:
+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 \
@@ -725,45 +524,36 @@ NEMOCLAW_SANDBOX_NAME=my-assistant \
Use `llama-cpp.muse-glimmer-30b.spark-single.v1` to select the Meta Muse Glimmer 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 an NVIDIA GPU Host](../inference/local-inference/set-up-llama-cpp#install-managed-llamacpp-on-an-nvidia-gpu-host).
+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:
+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.
+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.
+
-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.
+ 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.
-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.
+ 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.
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 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 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.
+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`):
@@ -771,53 +561,36 @@ In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `bal
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 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.
-It still applies the required preset for each messaging channel enabled during the same onboarding run so the configured channel can reach its service.
-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.
+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 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. It still applies the required preset for each messaging channel enabled during the same onboarding run so the configured channel can reach its service. 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.
+
-For Hermes, this includes replacing stale `nous-web` when Tavily is selected.
+ For Hermes, this includes replacing stale `nous-web` when Tavily is selected.
-An explicit `custom` preset list or interactive manual selection remains operator-controlled for additional presets.
+An explicit `custom` preset list or interactive manual selection remains operator-controlled for
+additional presets.
-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.
+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.
| 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`. |
-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.
+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.
-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.
+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:
@@ -858,20 +631,12 @@ 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`.
+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`.
-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.
+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 \
@@ -879,99 +644,39 @@ 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.
+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.
-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: ` 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 ` 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.
+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: ` 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 ` 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.
-Use `--agents ` to declare secondary OpenClaw agents, `agents.defaults`, and main-agent overrides in a checked-in manifest that NemoClaw includes in the generated sandbox configuration.
-Refer to [Declarative Multi-Agent Manifest](../configure-agents/declarative-agents-manifest) for the schema and OpenClaw-native sub-agent field semantics.
+Use `--agents ` to declare secondary OpenClaw agents, `agents.defaults`, and main-agent overrides in a checked-in manifest that NemoClaw includes in the generated sandbox configuration. Refer to [Declarative Multi-Agent Manifest](../configure-agents/declarative-agents-manifest) for the schema and OpenClaw-native sub-agent field semantics.
-Use `--control-ui-port ` 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 is created.
-
-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 includes those values in the generated Discord guild workspace configuration 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.
-
-
-
-If you cancel a brand-new onboarding run at the policy-tier selector or either policy-preset selector after sandbox creation, NemoClaw preserves the incomplete sandbox, registry entry, and onboarding session for identity-bound recovery.
-NemoClaw reports the durable sandbox identity fingerprint when it is available.
-It does not run OpenShell's mutable-name deletion command because the name may now identify a replacement sandbox.
-Do not delete the sandbox by mutable name.
-Shared inference providers are gateway configuration, not sandbox cleanup targets.
-Sandbox-scoped provider registrations or gateway-bound credentials may remain when the durable recovery record lists them.
-Ask an OpenShell administrator to inspect the exact sandbox identity and remove only sandbox-scoped resources whose ownership is confirmed for the retained sandbox.
-A credential environment name in the recovery record does not prove that its value was exposed.
-Rotate a credential only when identity-bound inspection proves that it was exposed or attached to a retained sandbox-scoped resource.
-NemoClaw stores the recovery record independently from the active onboarding session.
-A fresh run with a different name can proceed without clearing that record, but automatic resume, explicit `--resume`, reuse, recreation, and fresh onboarding with the retained name remain blocked.
-NemoClaw has no supported operation in this release to clear the recovery record, so the retained name remains unavailable even after external recovery or removal.
-Preserve the record as evidence.
-Start fresh onboarding with `$$nemoclaw onboard --fresh --name `.
-Select the required provider, model, agent, policy, and environment inputs again because `--fresh` does not retain them.
-
-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 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.
-If restoration into the replacement does not complete, NemoClaw reports the failed directories, files, and restore reason that are available, preserves the snapshot, leaves the replacement unregistered, and exits nonzero.
-Run the owner-scoped `openshell sandbox delete -g '' ''` command that onboarding prints, then rerun the original onboarding command.
-If NemoClaw cannot identify the owning gateway, do not delete a same-name sandbox.
-Preserve the snapshot for manual recovery.
-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.
+Use `--control-ui-port ` 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 is created.
+
+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 includes those values in the generated Discord guild workspace configuration 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.
+
+
+
+If you cancel a brand-new onboarding run at the policy-tier selector or either policy-preset selector after sandbox creation, NemoClaw preserves the incomplete sandbox, registry entry, and onboarding session for identity-bound recovery. NemoClaw reports the durable sandbox identity fingerprint when it is available. It does not run OpenShell's mutable-name deletion command because the name may now identify a replacement sandbox. Do not delete the sandbox by mutable name. Shared inference providers are gateway configuration, not sandbox cleanup targets. Sandbox-scoped provider registrations or gateway-bound credentials may remain when the durable recovery record lists them. Ask an OpenShell administrator to inspect the exact sandbox identity and remove only sandbox-scoped resources whose ownership is confirmed for the retained sandbox. A credential environment name in the recovery record does not prove that its value was exposed. Rotate a credential only when identity-bound inspection proves that it was exposed or attached to a retained sandbox-scoped resource. NemoClaw stores the recovery record independently from the active onboarding session. A fresh run with a different name can proceed without clearing that record, but automatic resume, explicit `--resume`, reuse, recreation, and fresh onboarding with the retained name remain blocked. NemoClaw has no supported operation in this release to clear the recovery record, so the retained name remains unavailable even after external recovery or removal. Preserve the record as evidence. Start fresh onboarding with `--fresh` and another available sandbox name. Select the required provider, model, agent, policy, and environment inputs again because `--fresh` does not retain them.
+
+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 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. If restoration into the replacement does not complete, NemoClaw reports the failed directories, files, and restore reason that are available, preserves the snapshot, leaves the replacement unregistered, and exits nonzero. Run the owner-scoped `openshell sandbox delete -g '' ''` command that onboarding prints, then rerun the original onboarding command. If NemoClaw cannot identify the owning gateway, do not delete a same-name sandbox. Preserve the snapshot for manual recovery. 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.
@@ -980,107 +685,46 @@ For OpenClaw, the backed-up paths include agents, extensions, workspace, skills,
-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.
-
-
-
-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:`.
-If a host firewall blocks that sandbox path, onboarding exits with a `sudo ufw allow from to 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).
-
-The Docker-driver gateway and the portable experimental profile's Podman-driver gateway resolve to the same default state directory when they use the same gateway port, because NemoClaw scopes that directory by port, not by driver.
-Selecting the portable experimental profile on a host that already has a Docker-driver gateway therefore refuses to rewrite that gateway's config rather than silently repurposing it for Podman.
-The error names the driver the existing config already uses and the driver this run selected.
-Docker and Podman gateways cannot reuse one state directory. For NemoClaw-managed state, switch drivers with the applicable `$$nemoclaw uninstall` path, then retry onboarding. Uninstall preserves externally managed or supervised state; resolve that state through its lifecycle authority instead. To run both drivers concurrently, select an unused gateway port with `NEMOCLAW_GATEWAY_PORT=` and a separate state directory with `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR=`.
+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.
+
+
+
+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:`. If a host firewall blocks that sandbox path, onboarding exits with a `sudo ufw allow from to 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).
+
+The Docker-driver gateway and the portable experimental profile's Podman-driver gateway resolve to the same default state directory when they use the same gateway port, because NemoClaw scopes that directory by port, not by driver. Selecting the portable experimental profile on a host that already has a Docker-driver gateway therefore refuses to rewrite that gateway's config rather than silently repurposing it for Podman. The error names the driver the existing config already uses and the driver this run selected. Docker and Podman gateways cannot reuse one state directory. For NemoClaw-managed state, switch drivers with the applicable `$$nemoclaw uninstall` path, then retry onboarding. Uninstall preserves externally managed or supervised state; resolve that state through its lifecycle authority instead. To run both drivers concurrently, select an unused gateway port with `NEMOCLAW_GATEWAY_PORT=` and a separate state directory with `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR=`.
#### `--from `
-Without `--from`, onboarding through the OpenShell Docker driver for OpenClaw, Hermes, and LangChain Deep Agents Code selects an immutable managed image for the installed release and host architecture.
-NemoClaw validates the complete three-agent publication cohort before selecting any member.
-If registry or catalog availability prevents resolution, stock onboarding stops before sandbox creation and does not build a shipped Dockerfile.
-Catalog evidence that is incomplete, mixed, mutable, wrong-platform, or identity-inconsistent also fails closed before sandbox creation.
-The portable experimental profile and native Podman are not part of this activation.
-
-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.
+Without `--from`, onboarding through the OpenShell Docker driver for OpenClaw, Hermes, and LangChain Deep Agents Code selects an immutable managed image for the installed release and host architecture. NemoClaw validates the complete three-agent publication cohort before selecting any member. If registry or catalog availability prevents resolution, stock onboarding stops before sandbox creation and does not build a shipped Dockerfile. Catalog evidence that is incomplete, mixed, mutable, wrong-platform, or identity-inconsistent also fails closed before sandbox creation. The portable experimental profile and native Podman are not part of this activation.
+
+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.
-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.
+ 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.
```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.
+The Dockerfile path must exist. Missing paths fail during command parsing before preflight, gateway setup, inference setup, or sandbox creation starts.
-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).
+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).
-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:
+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/
@@ -1090,27 +734,18 @@ build-dir/
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.
+- 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.
+- 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 build timings.
+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.
+`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:
+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
@@ -1119,8 +754,7 @@ 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 ` or `NEMOCLAW_SANDBOX_NAME` so a `--from` build cannot silently clobber the default `my-assistant` 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 ` 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
@@ -1130,27 +764,17 @@ If a `--resume` is attempted with a different `--from` path than the original se
#### `--name `
-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.
+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 ` 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.
+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 ` 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 ` 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.
+Use a custom Dockerfile for the sandbox image. This variant of `$$nemoclaw onboard` accepts a `--from ` 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
@@ -1158,51 +782,11 @@ $$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 ` to select an NVIDIA GPU by index (`0`), GPU UUID (`GPU-...`), or full CDI device name (`nvidia.com/gpu=0`).
-NemoClaw preserves the selection on resume.
-Use `--vllm-gpu-device ` to select the host GPU for the vLLM container that NemoClaw installs and manages.
-This selection is separate from sandbox GPU access, and NemoClaw also preserves it on resume.
-The selected GPU must satisfy the model's memory and compute-capability requirements.
-For native Docker and Podman creation, NemoClaw passes the normalized CDI name through OpenShell driver config; compatibility routes use the equivalent container-runtime selector.
-Device selection requires explicit sandbox GPU enablement.
-On ordinary native Linux Docker-driver hosts, NemoClaw uses native OpenShell GPU injection by default and never broadens confinement automatically.
-
-Portable onboarding requires native OpenShell GPU injection for every agent.
-It does not use `NEMOCLAW_DOCKER_GPU_PATCH` compatibility routing, so do not set `fallback`, `1`, or another legacy nonzero value for that profile.
-
-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 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 first asks OpenShell to stop the sandbox so its durable lifecycle row reaches `Stopped` before any irreversible Docker mutation.
-It then stops the exact transaction-owned replacement, removes the rollback backup, and asks OpenShell to start the sandbox so OpenShell owns the `Starting` lifecycle fence.
-NemoClaw verifies a `Ready` row, a working sandbox exec, and that the exact replacement is the sole running labeled container within the final handoff deadline.
-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.
+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 ` to select an NVIDIA GPU by index (`0`), GPU UUID (`GPU-...`), or full CDI device name (`nvidia.com/gpu=0`). NemoClaw preserves the selection on resume. Use `--vllm-gpu-device ` to select the host GPU for the vLLM container that NemoClaw installs and manages. This selection is separate from sandbox GPU access, and NemoClaw also preserves it on resume. The selected GPU must satisfy the model's memory and compute-capability requirements. For native Docker and Podman creation, NemoClaw passes the normalized CDI name through OpenShell driver config; compatibility routes use the equivalent container-runtime selector. Device selection requires explicit sandbox GPU enablement. On ordinary native Linux Docker-driver hosts, NemoClaw uses native OpenShell GPU injection by default and never broadens confinement automatically.
+
+Portable onboarding requires native OpenShell GPU injection for every agent. It does not use `NEMOCLAW_DOCKER_GPU_PATCH` compatibility routing, so do not set `fallback`, `1`, or another legacy nonzero value for that profile.
+
+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 first asks OpenShell to stop the sandbox so its durable lifecycle row reaches `Stopped` before any irreversible Docker mutation. It then stops the exact transaction-owned replacement, removes the rollback backup, and asks OpenShell to start the sandbox so OpenShell owns the `Starting` lifecycle fence. NemoClaw verifies a `Ready` row, a working sandbox exec, and that the exact replacement is the sole running labeled container within the final handoff deadline. 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:
@@ -1211,38 +795,18 @@ Prerequisites:
- 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.
+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.
-When the latest resumable onboarding session owns the matching inference-route reservation but has not created a sandbox, text output shows it under `Incomplete onboarding` with the recorded step and resume command.
-JSON output reports the same state in `incompleteOnboarding`; it remains separate from `sandboxes` and never affects the default sandbox.
-When present, `incompleteOnboarding` contains `name`, `status` (`failed` or `in_progress`), `step` (a string or `null`), `interrupted` (a boolean), and `resumable: true`; otherwise it is `null`.
-NemoClaw does not expose stale reservations that belong to another onboarding session.
-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.
+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. When the latest resumable onboarding session owns the matching inference-route reservation but has not created a sandbox, text output shows it under `Incomplete onboarding` with the recorded step and resume command. JSON output reports the same state in `incompleteOnboarding`; it remains separate from `sandboxes` and never affects the default sandbox. When present, `incompleteOnboarding` contains `name`, `status` (`failed` or `in_progress`), `step` (a string or `null`), `interrupted` (a boolean), and `resumable: true`; otherwise it is `null`. NemoClaw does not expose stale reservations that belong to another onboarding session. 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.
+
-When a sandbox has a recorded dashboard port, the output includes its local dashboard URL.
+ When a sandbox has a recorded dashboard port, the output includes its local dashboard URL.
-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.
+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]
@@ -1251,13 +815,9 @@ $$nemoclaw list --json
### `$$nemoclaw use `
-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.
+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.
+`$$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
@@ -1266,96 +826,60 @@ $$nemoclaw use --json
### `$$nemoclaw launch `
-Connect to a sandbox and start its agent in one host-side command.
-Use it instead of running `$$nemoclaw connect` and then typing the agent command inside the sandbox.
+Connect to a sandbox and start its agent in one host-side command. Use it instead of running `$$nemoclaw connect` and then typing the agent command inside the sandbox.
-`launch` runs the complete preflight from [`$$nemoclaw 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/`.
-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.
+`launch` runs the complete preflight from [`$$nemoclaw 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/`. 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 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 owning OpenShell gateway reports the exact sandbox identity in the `Ready` or `Running` state.
+- The sandbox registry, agent manifest, and interactive command match the recorded identity, and the current OpenShell policy is readable and valid. The lease stores no policy hash, so trusted host-side policy changes do not invalidate launch readiness.
+
-- 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 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 recorded inference selection matches the live route, and `inference.local` returns HTTP 2xx from its semantic probe for every configured provider except `openrouter-api`.
- OpenRouter's HTTP 404 response for `GET /v1/models` passes only after a bounded inference request for the recorded model succeeds.
- This is stricter than the HTTP 200–499 reachability diagnostic used by ordinary `connect`.
+- The recorded inference selection matches the live route, and `inference.local` returns HTTP 2xx from its semantic probe for every configured provider except `openrouter-api`. OpenRouter's HTTP 404 response for `GET /v1/models` passes only after a bounded inference request for the recorded model succeeds. 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.
-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, 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.
+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.
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` |
+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
```
-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.
+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.
-`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`.
+`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`.
@@ -1369,14 +893,11 @@ When you want a shell inside the sandbox rather than an agent session, use `$$ne
### `$$nemoclaw deploy`
-The `$$nemoclaw deploy` command is deprecated.
-Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `$$nemoclaw onboard` on that host.
+ The `$$nemoclaw deploy` command is deprecated. Prefer provisioning the remote host separately,
+ then running the standard NemoClaw installer and `$$nemoclaw onboard` on that host.
-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.
+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
@@ -1384,30 +905,13 @@ $$nemoclaw deploy
### `$$nemoclaw 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 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 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.
-
-While a session opened by `connect` remains active, NemoClaw watches for a Shields auto-relock that occurs after the connection begins.
-When one occurs, the host terminal prints one warning for that event on stderr, explains that restricted operations can now fail, and shows the `$$nemoclaw shields down --timeout ...` command to run on the host.
-The connected session remains open.
-If the Shields audit cannot be read, NemoClaw keeps the session open and might not print the advisory warning.
-
-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.
+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 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 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.
+
+While a session opened by `connect` remains active, NemoClaw watches for a Shields auto-relock that occurs after the connection begins. When one occurs, the host terminal prints one warning for that event on stderr, explains that restricted operations can now fail, and shows the exact `$$nemoclaw shields down --timeout ...` command to run on the host. The connected session remains open. If the Shields audit cannot be read, NemoClaw keeps the session open and might not print the advisory warning.
+
+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.
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.
@@ -1422,46 +926,20 @@ If Ollama does not become healthy within 30 seconds, the command identifies the
The command does not take over a system service or an unrelated user-managed Ollama daemon.
-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 --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 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.
+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 --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 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.
+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.
+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/`.
-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.
+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/`. 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.
-Every `connect --probe-only` completion prints at most one credential-free `Probe timing:` line.
-The line always reports these stages in this order, with cumulative whole-millisecond durations:
+Every `connect --probe-only` completion prints at most one credential-free `Probe timing:` line. The line always reports these stages in this order, with cumulative whole-millisecond durations:
- `readiness` waits for the sandbox state.
- `authority` validates launch-readiness authority and evidence.
@@ -1473,28 +951,20 @@ The line always reports these stages in this order, with cumulative whole-millis
- `pairing` settles OpenClaw operator pairing when applicable.
- `publication` publishes launch-readiness evidence on Linux.
-The line also reports `total`, `lifecycleAction=skipped|reused|recovered|failed`, `forwardAction=skipped|verified|restored|failed`, and `result=ready|failed`.
-A failed probe adds `failedStage=` or `failedStage=unknown`.
-Stages that do not apply or do not run report `0ms`.
-Timing collection and output are fail-open: clock or writer failures do not change the readiness work, command diagnostics, or exit status.
-Use the command exit status, not a duration or action field, as the readiness decision.
+The line also reports `total`, `lifecycleAction=skipped|reused|recovered|failed`, `forwardAction=skipped|verified|restored|failed`, and `result=ready|failed`. A failed probe adds `failedStage=` or `failedStage=unknown`. Stages that do not apply or do not run report `0ms`. Timing collection and output are fail-open: clock or writer failures do not change the readiness work, command diagnostics, or exit status. Use the command exit status, not a duration or action field, as the readiness decision.
-Portable lifecycle recovery also emits one credential-free `Portable lifecycle timing:` line.
-It reports fixed authority, container, exec-readiness, Ollama, startup, and gateway stages with their durations, selected actions, attempt counts, result, and failed stage when available.
-This diagnostic does not change recovery behavior or the command exit status.
+ Portable lifecycle recovery also emits one credential-free `Portable lifecycle timing:` line. It
+ reports fixed authority, container, exec-readiness, Ollama, startup, and gateway stages with their
+ durations, selected actions, attempt counts, result, and failed stage when available. This
+ diagnostic does not change recovery behavior or the command exit status.
Run it for health checks and scripted readiness probes; users continue to run only `$$nemoclaw launch `.
-For a current Portable OpenClaw sandbox, `connect`, `connect --probe-only`, `recover`, and `launch` require the same strict local CLI operator pairing as onboarding.
-If NemoClaw finds only the paired device and no pending request, it runs the canonical OpenClaw request producer once.
-It then runs at most one canonical approval and observes the final pairing state.
-An ambiguous approval result receives one final observation and no approval retry.
-Pairing with missing, extra, unknown, malformed, or ambiguous scope or identity data exits nonzero with an incomplete-onboarding diagnostic instead of opening a session or publishing launch-readiness evidence.
-Follow the diagnostic to resume or rerun onboarding.
+For a current Portable OpenClaw sandbox, `connect`, `connect --probe-only`, `recover`, and `launch` require the same strict local CLI operator pairing as onboarding. If NemoClaw finds only the paired device and no pending request, it runs the canonical OpenClaw request producer once. It then runs at most one canonical approval and observes the final pairing state. An ambiguous approval result receives one final observation and no approval retry. Pairing with missing, extra, unknown, malformed, or ambiguous scope or identity data exits nonzero with an incomplete-onboarding diagnostic instead of opening a session or publishing launch-readiness evidence. Follow the diagnostic to resume or rerun onboarding.
@@ -1502,18 +972,13 @@ Use [`$$nemoclaw launch `](#$$nemoclaw-launch-name) when you want launch-r
### `$$nemoclaw 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.
+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.
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`.
+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`.
@@ -1531,15 +996,9 @@ Everything after `--` is forwarded verbatim to the sandbox command, including fl
-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.
+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 ` 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 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.
+For a registered OpenClaw sandbox with a selected owning managed gateway, a successful direct `openclaw pairing approve googlechat ` 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 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.
@@ -1548,28 +1007,24 @@ The exit code is the remote command's exit code.
-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.
+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:
+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 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.
+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 ` | Working directory inside the sandbox. The directory is checked before the command runs; if it does not exist, NemoClaw reports `error: --workdir: 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 ` | Timeout in seconds (`0` means no timeout) |
@@ -1579,16 +1034,11 @@ Line breaks are accepted only in command argv: `--workdir` remains single-line,
-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.
+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.
+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"
@@ -1600,17 +1050,7 @@ $$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 `, 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.
+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 `, 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:
@@ -1620,33 +1060,9 @@ These leave the OpenShell wait unbounded:
- 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 `, `--session-id `, `--agent `, `--model `, `--thinking `, `--json`, `--deliver`, `--reply-channel `, and `--timeout `.
-For OpenClaw sandboxes and registry fallbacks, `$$nemoclaw agent --help` prints the wrapper-level summary locally.
-Invoke `$$nemoclaw 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 agent` and `dcode --help` for `$$nemoclaw agent --help`.
+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 `, `--session-id `, `--agent `, `--model `, `--thinking `, `--json`, `--deliver`, `--reply-channel `, and `--timeout `. For OpenClaw sandboxes and registry fallbacks, `$$nemoclaw agent --help` prints the wrapper-level summary locally. Invoke `$$nemoclaw 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 agent` and `dcode --help` for `$$nemoclaw agent --help`.
Host-side validation runs before the sandbox dispatch:
@@ -1657,11 +1073,7 @@ Host-side validation runs before the sandbox dispatch:
-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.
+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:
@@ -1675,15 +1087,7 @@ curl -sN http://127.0.0.1:8642/v1/chat/completions \
-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 agent -n ""` 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 agent` launches the same terminal TUI as `dcode`.
-Headless `$$nemoclaw agent -n ""` uses the managed headless boundary, where non-shell tools can auto-run without the interactive approval UI.
+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 agent -n ""` 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 agent` launches the same terminal TUI as `dcode`. Headless `$$nemoclaw agent -n ""` uses the managed headless boundary, where non-shell tools can auto-run without the interactive approval UI.
@@ -1693,9 +1097,7 @@ The following commands are available for targeted host-side maintenance, but the
#### `$$nemoclaw 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.
+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.
@@ -1722,19 +1124,16 @@ $$nemoclaw my-assistant config get --key models.default --format yaml
-| Flag | Description |
-|------|-------------|
-| `--key ` | Print one value from the sanitized config |
-| `--format json\|yaml` | Output format. Defaults to JSON |
+| Flag | Description |
+| --------------------- | ----------------------------------------- |
+| `--key ` | Print one value from the sanitized config |
+| `--format json\|yaml` | Output format. Defaults to JSON |
#### `$$nemoclaw config set`
-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 shields down` first.
+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 shields down` first.
```bash
$$nemoclaw my-assistant config set --key agents.defaults.model.primary --value nvidia/nemotron
@@ -1742,43 +1141,31 @@ $$nemoclaw my-assistant config set --key agents.defaults.timeoutSeconds --value
```
| Flag | Description |
-|------|-------------|
+| --- | --- |
| `--key ` | Dotpath to update in the config. Required |
| `--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 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.
-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.
+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.
-For Deep Agents sandboxes, `config set` is unavailable because managed startup (or an explicit custom image build) materializes the `dcode` configuration as image-owned state.
-Run `$$nemoclaw onboard --agent dcode --name --fresh` when you need to change it.
-Use `$$nemoclaw config get` to read the current values.
+For Deep Agents sandboxes, `config set` is unavailable because managed startup (or an explicit custom image build) materializes the `dcode` configuration as image-owned state. Run `$$nemoclaw onboard --agent dcode --name --fresh` when you need to change it. Use `$$nemoclaw config get` to read the current values.
#### `$$nemoclaw 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.
+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.
@@ -1793,30 +1180,20 @@ $$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 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 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 shields up`.
-If the retry still fails, rebuild a known-good baseline with `$$nemoclaw rebuild --yes`.
+If `shields up` reports that the config remains unlocked or drifted, confirm that the sandbox is running and ready, then retry `$$nemoclaw shields up`. If the retry still fails, rebuild a known-good baseline with `$$nemoclaw rebuild --yes`.
-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.
+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.
@@ -1830,116 +1207,41 @@ Host-side gateway recovery uses the same per-sandbox serialization.
-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 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.
+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 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 recursive posture.
+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 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 a 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 ''; retry after the provider fence is released.`
-Recover and retry as follows:
+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 ''; retry after the provider fence is released.` Recover and retry as follows:
1. Let the active Shields or recovery command finish.
2. Run `$$nemoclaw 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`.
-
-
-
-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 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 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 shields status` to resume recovery or receive 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 gates, or the fail-closed state-directory error blocks new mutations until you complete 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 stale generations first, and remove the containment generation last.
-
-Before a manual Shields transition replaces a policy, NemoClaw requires 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 entries.
-If 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 it retains policy ownership.
+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`.
+
+
+
+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 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.
+
+Shields treats OpenShell's current policy as authoritative. `shields down` captures that document as bounded transaction state and preserves its live MCP entries in the temporary relaxed policy without consulting a policy ownership manifest. Restoration performs a three-way reversal of only the changes made by that Shields transaction: a host-side edit made while Shields is down is preserved, while an unchanged temporary value is restored to its pre-transition value. The snapshot and forward document are deleted when the transaction completes; neither becomes durable desired policy state.
### `$$nemoclaw 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 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 replacement to pass managed gateway health and OpenShell re-registration before it restores state.
-After state restoration, it restarts the gateway in the 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.
-At the final commit handoff, NemoClaw asks OpenShell to stop the sandbox before it mutates either exact container.
-After OpenShell acknowledges that stop, NemoClaw stops the exact replacement, removes the rollback container, and asks OpenShell to start the sandbox through its authoritative lifecycle path.
-This preserves OpenShell's stopped/starting event fence while stale Docker removal snapshots settle; raw Docker stop/start events cannot strand the lifecycle row in `Error` or `Deleting`.
-If the authoritative stop fails, NemoClaw leaves both containers intact. If the start or final `Ready`/exec/exact-container proof fails after rollback-container removal, NemoClaw reports that automatic rollback is unavailable.
-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 transient results:
+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 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. At the final commit handoff, NemoClaw asks OpenShell to stop the sandbox before it mutates either exact container. After OpenShell acknowledges that stop, NemoClaw stops the exact replacement, removes the rollback container, and asks OpenShell to start the sandbox through its authoritative lifecycle path. This preserves OpenShell's stopped/starting event fence while stale Docker removal snapshots settle; raw Docker stop/start events cannot strand the lifecycle row in `Error` or `Deleting`. If the authoritative stop fails, NemoClaw leaves both containers intact. If the start or final `Ready`/exec/exact-container proof fails after rollback-container removal, NemoClaw reports that automatic rollback is unavailable. 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_NOT_RUNNING`, `SUPERVISOR_DISCOVERY_PENDING`, `PRIVILEGED_CONTROL_UNAVAILABLE`, `GATEWAY_HEALTH_TIMEOUT`, or `SUPERVISOR_BUSY`.
- Status `137` with blank stdout and stderr.
- Status `1` with blank stdout and exactly one stderr line, `Error response from daemon: Container is restarting, wait until the container is running`.
-For the Docker result, `` 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`.
-The managed controller emits `SUPERVISOR_DISCOVERY_PENDING` only when an incomplete process-table scan during startup cannot yet prove either one exact supervisor or clean supervisor absence.
-That result delays recovery but cannot authorize container recreation or accept a supervisor identity; a later request must perform the complete identity proof again.
-Managed settle confirmation treats exact `SUPERVISOR_BUSY` and `SUPERVISOR_DISCOVERY_PENDING` results 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 four exact startup results, `SUPERVISOR_BUSY`, and 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.
-Only an exact `SUPERVISOR_NOT_RUNNING` result that remains after the bounded startup retries can enter transactional legacy keepalive recreation.
-The pinned controller probe must then confirm the missing supervisor before recreation proceeds.
-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 gateway restart`](#$$nemoclaw-name-gateway-restart) when you deliberately need a running gateway to reload runtime configuration or plugins.
+For the Docker result, `` 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`. The managed controller emits `SUPERVISOR_DISCOVERY_PENDING` only when an incomplete process-table scan during startup cannot yet prove either one exact supervisor or clean supervisor absence. That result delays recovery but cannot authorize container recreation or accept a supervisor identity; a later request must perform the complete identity proof again. Managed settle confirmation treats exact `SUPERVISOR_BUSY` and `SUPERVISOR_DISCOVERY_PENDING` results 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 four exact startup results, `SUPERVISOR_BUSY`, and 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. Only an exact `SUPERVISOR_NOT_RUNNING` result that remains after the bounded startup retries can enter transactional legacy keepalive recreation. The pinned controller probe must then confirm the missing supervisor before recreation proceeds. 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 gateway restart`](#$$nemoclaw-name-gateway-restart) when you deliberately need a running gateway to reload runtime configuration or plugins.
```bash
$$nemoclaw my-assistant recover
@@ -1949,100 +1251,53 @@ $$nemoclaw my-assistant recover
-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`.
+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`.
-For an active Portable Hermes receipt, `recover` starts only the exact receipt-owned Podman container when it is stopped.
-If authenticated health is not ready after that start, recovery launches the receipt-owned `nemoclaw-start` command once and waits for authenticated Hermes health.
-For an already-running container, recovery does not launch the startup command, does not stop the container, and only waits for authenticated health.
-If a container or OpenShell identity check, reconnect check, or health check later fails after recovery started the container, NemoClaw stops that exact container.
-It then requires Podman to report the container as `exited` and OpenShell to report `Error` or `Stopped`.
-If NemoClaw cannot prove that rollback, the command reports both the recovery failure and the rollback failure.
+For an active Portable Hermes receipt, `recover` starts only the exact receipt-owned Podman container when it is stopped. It waits for the existing in-container `nemoclaw-start` supervisor to establish authenticated Hermes health and never launches another detached `nemoclaw-start` process. If a container or OpenShell identity check, reconnect check, or health check later fails after recovery started the container, NemoClaw stops that exact container. It then requires Podman to report the container as `exited` and OpenShell to report `Error` or `Stopped`. If NemoClaw cannot prove that rollback, the command reports both the recovery failure and the rollback failure.
-`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:` 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:` 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 rebuild --yes` before retrying.
+`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:` 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:` 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 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.
+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.
+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.
-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.
+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 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.
+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 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 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.
+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.
-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 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 shields down` before a Hermes config or inference change; these commands refuse to mutate a shields-up sandbox.
+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 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 shields down` before a Hermes config or inference change; these commands refuse to mutate a shields-up sandbox.
-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 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 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.
+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 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 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.
### `$$nemoclaw stop`
-Stop the sandbox's local runtime 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 destroy`](#$$nemoclaw-name-destroy) when you want to delete it instead.
+Stop the sandbox's local runtime 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 destroy`](#$$nemoclaw-name-destroy) when you want to delete it instead.
```bash
$$nemoclaw my-assistant stop
@@ -2050,29 +1305,30 @@ $$nemoclaw my-assistant stop
-For an active Portable Hermes receipt, `stop` targets only the receipt-owned Podman container and waits for its terminal stopped state without using Docker as a fallback.
-A `pending` or `configuring` receipt instead directs you to resume Portable onboarding.
-Portable Hermes does not run the Docker provider's channel hook or the generic post-stop dashboard-forward cleanup.
+For an active Portable Hermes receipt, `stop` targets only the exact receipt-owned Podman container and waits for its terminal stopped state without using Docker as a fallback. A `pending` or `configuring` receipt instead directs you to resume Portable onboarding. Portable Hermes does not run the Docker provider's channel hook or the generic post-stop dashboard-forward cleanup.
-For OpenClaw-managed gateways, the command first asks the in-sandbox gateway to shut down its channels gracefully; non-Portable 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.
+For OpenClaw-managed gateways, the command first asks the in-sandbox gateway to shut down its channels gracefully; non-Portable 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.
+
-Except for Portable 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.
+ Except for Portable 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.
-The shared host gateway, tunnel services, and any local NIM inference container serve other sandboxes and keep running.
+The shared host gateway, tunnel services, and any local NIM inference container serve other
+sandboxes and keep running.
-Stopping an already-stopped sandbox succeeds.
-Except for Portable Hermes, NemoClaw also attempts to remove any leftover dashboard forward for that sandbox.
+ Stopping an already-stopped sandbox succeeds. Except for Portable Hermes, NemoClaw also attempts
+ to remove any leftover dashboard forward for that sandbox.
-Stopping an already-stopped sandbox succeeds without changes.
+ Stopping an already-stopped sandbox succeeds without changes.
-The command is available only when NemoClaw holds local-container authority.
-Portable profiles use receipt-owned Podman authority; non-Portable local-container paths use the default Docker driver or the vm driver.
-Remote drivers such as kubernetes are unavailable, and an unreachable selected runtime produces an outage report instead of a guessed container state.
+The command is available only when NemoClaw holds local-container authority. Portable profiles use
+receipt-owned Podman authority; non-Portable local-container paths use the default Docker driver or
+the vm driver. Remote drivers such as kubernetes are unavailable, and an unreachable selected
+runtime produces an outage report instead of a guessed container state.
### `$$nemoclaw start`
@@ -2084,119 +1340,63 @@ $$nemoclaw my-assistant start
-For an active Portable Hermes receipt, `start` follows the Podman container, supervisor, authenticated health, and rollback contract documented for [`recover`](#$$nemoclaw-name-recover). It does not use Docker as a fallback.
-A `pending` or `configuring` receipt instead directs you to resume Portable onboarding.
+For an active Portable Hermes receipt, `start` follows the exact Podman container, supervisor, authenticated health, and rollback contract documented for [`recover`](#$$nemoclaw-name-recover); it does not fall back to Docker. A `pending` or `configuring` receipt instead directs you to resume Portable onboarding.
-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 rebuild`.
+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 rebuild`.
-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`.
+ 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`.
-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`.
+ 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`.
-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.
+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.
+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 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.
+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 Portable Hermes, `status` reports `Portable lifecycle phase: pending`, `configuring`, or `active` from the receipt authority without running Docker or OpenClaw status work.
-An active receipt must match its sandbox registry lifecycle identity; a mismatch fails instead of reporting status from another runtime.
-
-
-
-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 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 matches the recorded provider, the request uses the sandbox's recorded API family, even when only the model differs.
-This includes `openai-responses`.
-When the live provider differs, NemoClaw does not carry the recorded API family to the live provider.
-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:
+For Portable Hermes, `status` reports `Portable lifecycle phase: pending`, `configuring`, or `active` from the receipt authority without running Docker or OpenClaw status work. An active receipt must match its sandbox registry lifecycle identity; a mismatch fails instead of reporting status from another runtime.
+
+
+
+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`, `policiesAvailable`, `failureLayer`, `terminalRuntimeHealth`, `servingProcessHealth`, and `dockerPaused`. `policies` is derived from the current OpenShell policy; NemoClaw does not persist a second preset list or baseline-exclusion ledger. `policiesAvailable` is `false` when that live policy cannot be read or parsed, distinguishing an unavailable result from a verified empty `policies` array; text status prints `Policies: unavailable` for the same state. 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 matches the recorded provider, the request uses the sandbox's recorded API family, even when only the model differs. This includes `openai-responses`. When the live provider differs, NemoClaw does not carry the recorded API family to the live provider. 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 ` 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 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 ( 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.
-When the canonical text command targets an unregistered name, it reports that the sandbox is not registered and tells you to run `$$nemoclaw list`.
-The alias form `$$nemoclaw status --json` requires the sandbox to be registered locally; the canonical form `$$nemoclaw sandbox status --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:
+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 ` 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 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 ( 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. When the canonical text command targets an unregistered name, it reports that the sandbox is not registered and tells you to run `$$nemoclaw list`. The alias form `$$nemoclaw status --json` requires the sandbox to be registered locally; the canonical form `$$nemoclaw sandbox status --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.
-| State | Meaning |
-|---|---|
-| `preparing` | The gateway-scoped owner exists, but `receipt.json` is absent. |
-| `running` | The receipt-owned container is running under the recorded Docker authority. |
-| `stopped` | The receipt-owned container exists but is stopped. |
-| `absent` | The finalized receipt exists, but its 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.
+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.
-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.
+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.
@@ -2206,12 +1406,10 @@ $$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:
+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. |
@@ -2220,35 +1418,18 @@ The main `Inference` line reports one of these states:
| `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 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.
-
-The `Inference (upstream)` check authenticates with the host credential that NemoClaw resolves for the provider, such as `NVIDIA_INFERENCE_API_KEY`.
-The gateway stores the provider credential that the sandbox route uses.
-The CLI cannot read the stored value back, so the two credentials can hold different secrets.
-When the `inference.local` route has already served the inference request, an `unauthorized` result on `Inference (upstream)` describes the host credential.
-NemoClaw then reports that check as `not probed` and names both credential sources.
-An `Inference (upstream)` check that fails for another reason, such as `unreachable`, still reports its own state.
-Local backend and auth proxy checks, such as `Inference (auth proxy)`, always report their own state and their own repair step.
-`$$nemoclaw doctor` sends no inference request, so it always reports the `Inference (upstream)` state that it measured.
-
-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.
+An authentication response on the route probe alone confirms that the route is reachable, not that provider credentials are valid. `$$nemoclaw 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.
+
+The `Inference (upstream)` check authenticates with the host credential that NemoClaw resolves for the provider, such as `NVIDIA_INFERENCE_API_KEY`. The gateway stores the provider credential that the sandbox route uses. The CLI cannot read the stored value back, so the two credentials can hold different secrets. When the `inference.local` route has already served the inference request, an `unauthorized` result on `Inference (upstream)` describes the host credential. NemoClaw then reports that check as `not probed` and names both credential sources. An `Inference (upstream)` check that fails for another reason, such as `unreachable`, still reports its own state. Local backend and auth proxy checks, such as `Inference (auth proxy)`, always report their own state and their own repair step. `$$nemoclaw doctor` sends no inference request, so it always reports the `Inference (upstream)` state that it measured.
+
+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.
+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.
+
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.
@@ -2259,29 +1440,30 @@ Address the reported recovery layer, then run the displayed `$$nemoclaw
-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.
+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 for inspection and directs the operator to remove that stale entry with `$$nemoclaw destroy --yes` before clean onboarding. Rebuild cannot recreate a missing sandbox because no authoritative OpenShell policy remains.
+
-Gateway and dashboard health checks treat HTTP `401` from device auth as a live service, not as an offline gateway.
+ Gateway and dashboard health checks treat HTTP `401` from device auth as a live service, not as an
+ offline gateway.
-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:
@@ -2332,8 +1513,7 @@ Expected output:
...
```
-If the sandbox is running an older Hermes version than this NemoClaw release expects, `status` and `connect` add an `Update` line pointing at `nemohermes 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.
+If the sandbox is running an older Hermes version than this NemoClaw release expects, `status` and `connect` add an `Update` line pointing at `nemohermes 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.
@@ -2356,71 +1536,43 @@ Expected output:
...
```
-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 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.
+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 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.
### `$$nemoclaw 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.
+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.
+
-For gateway-based agents, it also reports messaging channel conflicts within the selected OpenShell gateway's sandbox registry.
+ For gateway-based agents, it also reports messaging channel conflicts within the selected
+ OpenShell gateway's sandbox registry.
-`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.
+`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 Portable Hermes, `doctor` reports a `Portable lifecycle` check with the receipt phase.
-The `pending` and `configuring` phases produce a warning, while `active` passes when the receipt and registry authority agree.
-This read-only path does not run Docker or OpenClaw checks, and `doctor --fix` is not supported while the Portable Hermes receipt exists.
+For Portable Hermes, `doctor` reports a `Portable lifecycle` check with the receipt phase. The `pending` and `configuring` phases produce a warning, while `active` passes when the receipt and registry authority agree. This read-only path does not run Docker or OpenClaw checks, and `doctor --fix` is not supported while the Portable Hermes receipt exists.
-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.
-The `Inference` `Route` check warns when either the provider or model is unknown.
-After the gateway is healthy, run `$$nemoclaw status` to refresh the route information.
-
-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.
+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. The `Inference` `Route` check warns when either the provider or model is unknown. After the gateway is healthy, run `$$nemoclaw status` to refresh the route information.
-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.
+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 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.
+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.
-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.
+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` |
@@ -2431,28 +1583,21 @@ $$nemoclaw my-assistant doctor [--json | --fix]
$$nemoclaw my-assistant doctor [--json]
```
-| Flag | Description |
-|------|-------------|
+| Flag | Description |
+| -------- | ----------------------- |
| `--json` | Emit the report as JSON |
### `$$nemoclaw 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.
+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.
-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`.
+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 ` 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 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.
+A successful direct `openclaw pairing approve googlechat ` 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 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.
@@ -2465,23 +1610,19 @@ The command exits with the remote command's exit code.
$$nemoclaw my-assistant exec [--workdir ] [--tty|--no-tty] [--timeout ] [--stdin|--no-stdin] -- [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.
+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:
+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 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.
+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 ` | Set the working directory inside the sandbox. The directory is checked before the command runs; if it does not exist, NemoClaw reports `error: --workdir: 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 ` | Timeout in seconds. Use `0` for no timeout |
@@ -2489,13 +1630,7 @@ Line breaks are accepted only in command argv: `--workdir` remains single-line,
### `$$nemoclaw logs`
-View sandbox logs.
-Use `--follow` to stream output in real time.
-Use `--tail ` or `-n ` to limit the number of returned lines.
-Use `--since ` 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 ` flag is a line-count flag; the lower-level `openshell logs --tail` flag means follow live output, so use `openshell logs -n ` when running OpenShell directly for a fixed line count.
+View sandbox logs. Use `--follow` to stream output in real time. Use `--tail ` or `-n ` to limit the number of returned lines. Use `--since ` 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 ` flag is a line-count flag; the lower-level `openshell logs --tail` flag means follow live output, so use `openshell logs -n ` when running OpenShell directly for a fixed line count.
```bash
$$nemoclaw my-assistant logs [--follow] [--tail |-n ] [--since ]
@@ -2505,50 +1640,40 @@ $$nemoclaw my-assistant logs [--follow] [--tail |-n ] [--since
-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.
+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:
+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)
```
-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.
+ 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.
-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.
+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.
+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.
-`dashboard-url` is not applicable to Deep Agents sandboxes because the managed harness is a terminal runtime without a dashboard port.
-Use `$$nemoclaw launch ` to start `dcode`.
-Use `$$nemoclaw connect` instead when you want a sandbox shell.
+`dashboard-url` is not applicable to Deep Agents sandboxes because the managed harness is a terminal runtime without a dashboard port. Use `$$nemoclaw launch ` to start `dcode`. Use `$$nemoclaw connect` instead when you want a sandbox shell.
@@ -2556,22 +1681,16 @@ Use `$$nemoclaw connect` instead when you want a sandbox shell.
-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:
+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 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):
+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)
@@ -2580,22 +1699,13 @@ curl -fsS -H "Authorization: Bearer $TOKEN" \
```
-Treat the gateway token like a password.
-Do not log it, share it, or commit it to version control.
+ Treat the gateway token like a password. Do not log it, share it, or commit it to version control.
-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:
+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)
@@ -2604,31 +1714,21 @@ curl -fsS -H "Authorization: Bearer $TOKEN" \
```
-Treat the token like a password.
-Do not log it, share it, or commit it to version control.
+ Treat the token like a password. Do not log it, share it, or commit it to version control.
-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`.
+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`.
-`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.
+`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.
### `$$nemoclaw 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).
+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:
@@ -2646,120 +1746,50 @@ Back up your workspace first with `$$nemoclaw snapshot create` or refer t
If you want to upgrade the sandbox while preserving state, use `$$nemoclaw rebuild` instead.
-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.
-These controls do not suppress the active-session warning.
-The warning lists the detected process IDs, and destroy still terminates those sessions with a `Broken pipe` error.
+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. These controls do not suppress the active-session warning. The warning lists the detected process IDs, and destroy still terminates those sessions with a `Broken pipe` error.
-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:
+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 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 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 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
+```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.
+The labels show what each container claims. They do not prove container ownership.
-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.
+ 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.
-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.
+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.
-If the Hermes sandbox has managed MCP entries, shields must be down before destroy can scrub their adapter configuration.
-Use `$$nemoclaw 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.
+If the Hermes sandbox has managed MCP entries, shields must be down before destroy can scrub their adapter configuration. Use `$$nemoclaw 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.
-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.
-Detached auto-restore uses one 7-attempt recovery budget to restore lockdown.
-Waiting for a verified live sandbox mutation owner does not consume an attempt.
-The deadline gate remains closed during that wait.
-If the recovery budget is exhausted, durable containment blocks new sandbox mutations.
-Run `$$nemoclaw shields status` and follow its generation recovery guidance.
-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 completes with a nonzero status, `destroy` continues, but the retained volume may still contain old files.
-Use a different sandbox name to avoid reusing that retained volume.
-If workspace cleanup reaches its 60-second timeout, NemoClaw cannot confirm the remote result.
-NemoClaw stops before provider cleanup and sandbox deletion, attempts to restore any prepared MCP state, and preserves the local registry entry.
-Run `$$nemoclaw status` to check or start the recorded OpenShell gateway.
-If a shields auto-restore timer remains active, run `$$nemoclaw shields status` to verify bounded recovery or follow its durable-containment guidance, then retry `destroy` only after shields recovery permits it.
-If no timer remains active, retry after the recorded gateway is available.
-Cleaning up the gateway after the last sandbox also purges the shared cluster volume that retains the per-name persistent volume.
-If NemoClaw detects active SSH sessions before destroy, it warns that destroy terminates them with a Broken pipe error and lists their process IDs.
-This warning prints before the confirmation prompt and when `--yes` or `--force` skips that prompt.
-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 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 command completes with a gateway transport error 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 status` and retry destroy when you need a confirmed deletion.
-If the OpenShell sandbox deletion command reaches its 60-second timeout, NemoClaw cannot confirm whether OpenShell deleted the sandbox.
-NemoClaw preserves the local registry entry under both `--yes` and `--force`.
-Run `$$nemoclaw status` to check or start the recorded OpenShell gateway.
-If the preceding output also reports a failed pre-delete re-lock, run `$$nemoclaw shields status` to verify recovery or follow its durable-containment guidance, then retry `destroy` only after shields recovery permits it.
-Otherwise, retry after the recorded gateway is available.
-Managed MCP ownership disables the local-only fallback because 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.
+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. Detached auto-restore uses one 7-attempt recovery budget to restore lockdown. Waiting for a verified live sandbox mutation owner does not consume an attempt. The deadline gate remains closed during that wait. If the recovery budget is exhausted, durable containment blocks new sandbox mutations. Run `$$nemoclaw shields status` and follow its exact-generation recovery guidance. 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 completes with a nonzero status, `destroy` continues, but the retained volume may still contain old files. Use a different sandbox name to avoid reusing that retained volume. If workspace cleanup reaches its 60-second timeout, NemoClaw cannot confirm the remote result. NemoClaw stops before provider cleanup and sandbox deletion, attempts to restore any prepared MCP state, and preserves the local registry entry. Run `$$nemoclaw status` to check or start the recorded OpenShell gateway. If a shields auto-restore timer remains active, run `$$nemoclaw shields status` to verify bounded recovery or follow its durable-containment guidance, then retry `destroy` only after shields recovery permits it. If no timer remains active, retry after the recorded gateway is available. Cleaning up the gateway after the last sandbox also purges the shared cluster volume that retains the per-name persistent volume. If NemoClaw detects active SSH sessions before destroy, it warns that destroy terminates them with a Broken pipe error and lists their process IDs. This warning prints before the confirmation prompt and when `--yes` or `--force` skips that prompt. 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 command completes with a gateway transport error 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 status` and retry destroy when you need a confirmed deletion. If the OpenShell sandbox deletion command reaches its 60-second timeout, NemoClaw cannot confirm whether OpenShell deleted the sandbox. NemoClaw preserves the local registry entry under both `--yes` and `--force`. Run `$$nemoclaw status` to check or start the recorded OpenShell gateway. If the preceding output also reports a failed pre-delete re-lock, run `$$nemoclaw shields status` to verify recovery or follow its durable-containment guidance, then retry `destroy` only after shields recovery permits it. Otherwise, retry after the recorded gateway is available. 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 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 cleanup fails, `destroy` preserves the sandbox registry entry and ownership state so you can correct the reported conflict and retry.
+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 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.
+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
@@ -2774,16 +1804,12 @@ $$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 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 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.
+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
@@ -2795,45 +1821,14 @@ To apply a specific preset without the interactive picker, pass its name as a po
$$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 the interactive picker receives a nonnumeric or out-of-range selection, the command prints the validation error, exits non-zero, and applies no preset.
-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.
-For built-in presets in that same case, the command applies the preset and returns success, because a built-in preset stays discoverable from the gateway.
-It warns that `policy list` will report the preset as active on gateway, missing from local state.
-
-With `--from-file` or `--from-dir`, pass a repeatable `--trusted-private-host ` 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 exact matching 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.
+The positional form is required in scripted workflows. Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` for the same non-interactive behavior. If the preset is already present with identical content, the command reports no changes. If its content differs, NemoClaw previews the change and asks for confirmation before applying it again.
+
+Every mutation starts from the round-trippable base document returned by OpenShell, merges the requested built-in or custom content, submits the complete document, and verifies the live result. NemoClaw stores no applied-preset list or custom-policy copy in its registry. Custom preset names are encoded in namespaced keys in the live policy so later `policy list` and `policy remove` commands can derive them from OpenShell. If the live policy cannot be read or parsed, the command exits without writing a replacement.
+
+With `--from-file` or `--from-dir`, pass a repeatable `--trusted-private-host ` 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. Applying the preset places those pins in the current OpenShell policy, which rebuild carries forward without re-resolving ambient DNS.
| Flag | Description |
-|------|-------------|
+| --- | --- |
| `--from-file ` | Apply a custom preset YAML file instead of a built-in preset |
| `--from-dir ` | Apply every custom preset YAML file in a directory in lexicographic order |
| `--trusted-private-host ` | Admit one private endpoint host from a custom preset and generate address pins; repeat for additional hosts |
@@ -2867,34 +1862,20 @@ For batch workflows, apply all preset files from a directory:
$$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.
+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 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 policy command to reconcile it before sandbox creation or recreation, rebuild, or cross-sandbox snapshot cloning.
+List available policy presets and show which ones match the current OpenShell policy. Built-in rows are scoped to the active agent. Custom preset rows are decoded from namespaced keys in that live document. NemoClaw does not cross-reference a local preset registry or display baseline-exclusion records.
-Each active preset is annotated with its provenance so you can tell why it is applied:
+Each active preset is annotated with display-time provenance:
-- `[from tier]` — the preset name matches an entry in the sandbox's current tier definition (see [Policy Tiers](../reference/network-policies#policy-tiers)).
-- `[from 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.
+- `[from tier]` means the name appears in the current tier definition.
+- `[from agent]` means the name is an agent-specific preset for the active agent.
+- `[user-added]` covers other live presets.
+- `[source unverified (gateway unreachable)]` appears only when OpenShell cannot be read; no local policy fallback is shown.
-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]` even when an operator added it manually with `policy add` after onboarding.
-Agent-specific preset names are only labelled `[from agent]` when the active agent matches that label.
+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]` even when an operator added it manually with `policy add` after onboarding. Agent-specific preset names are only labelled `[from agent]` when the active agent matches that label.
```bash
$$nemoclaw my-assistant policy list
@@ -2902,8 +1883,7 @@ $$nemoclaw my-assistant policy list
### `$$nemoclaw policy remove`
-Remove a previously applied policy preset from a sandbox.
-The command lists the presets the local registry records together with the presets the live gateway enforces, prompts you to select one, shows the endpoints that would be removed, and asks for confirmation before narrowing egress.
+Remove a previously applied policy preset from a sandbox. The command derives applied presets from the current OpenShell policy, 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
@@ -2915,53 +1895,29 @@ To remove a specific preset non-interactively, pass its name as a positional arg
$$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 neither the local registry nor the live gateway holds it, the command exits non-zero with a clear error.
-A preset the gateway enforces without a local registry record is removable, which is the state `policy list` reports as active on gateway, missing from local state.
-When NemoClaw cannot query the gateway, the command checks the local registry alone; with a preset name it also reports that the gateway could not be queried.
+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 absent from the live OpenShell policy, the command exits non-zero with a clear error. When NemoClaw cannot query OpenShell, it refuses the mutation instead of consulting a local policy record.
-| Flag | Description |
-|------|-------------|
-| `--yes`, `--force` | Skip the confirmation prompt (requires a preset name) |
-| `--dry-run` | Preview which endpoints would be removed without applying changes |
+| 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 policy exclude `
-Persistently exclude one 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.
+Remove one exact entry from the current OpenShell 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. No exclusion record or replay journal is written: OpenShell's resulting policy is the complete state, and rebuild carries that live document forward. The command refuses to exclude a key that an applied preset also requires, because removing that live key would 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 policy restore --dry-run` to preview the current baseline egress that restoration would allow again.
-After you review the output, run `$$nemoclaw policy restore --force` to allow that egress again and clear the stale exclusion record.
-Then preview the current exclusion scope with `$$nemoclaw policy exclude --dry-run` and reapply it with `$$nemoclaw policy exclude --force` only if you still accept the support impact.
-When a release removes the entry, first run `$$nemoclaw policy restore --dry-run` to confirm that restoration will clear only the stale exclusion record.
-After you review the output, run `$$nemoclaw policy restore --force`; there is no replacement scope to review or approve.
+To restore an entry, run `$$nemoclaw policy restore --dry-run` to preview the current baseline egress, then run it with `--force` after review. If the current baseline no longer defines the key, the command reports that there is nothing to restore and leaves the live OpenShell policy unchanged.
### `$$nemoclaw policy restore `
-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.
+Restore one entry from the current agent baseline into the current OpenShell policy. `--dry-run` lists the egress that restoration would allow again; after review, `--force` applies it. 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. The command writes no exclusion record or journal and verifies the resulting live OpenShell policy before returning.
```bash
$$nemoclaw my-assistant policy restore nous_research --dry-run
@@ -2971,15 +1927,13 @@ $$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 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.
+Print a redacted summary of the current OpenShell 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 inferred tier and preset context, allowed host categories, known unapplied presets, 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
@@ -2998,25 +1952,23 @@ Pass `--write` to refresh that file on demand without changing the policy:
```bash
$$nemoclaw my-assistant policy explain --write
```
+
-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.
+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 |
-|------|-------------|
+| Flag | Description |
+| -------- | ------------------------------------------------------------------------- |
| `--json` | Emit the policy context as a structured JSON object for agent consumption |
+
-| `--write` | Refresh `/sandbox/.openclaw/workspace/POLICY.md` inside the sandbox in addition to printing |
+ | `--write` | Refresh `/sandbox/.openclaw/workspace/POLICY.md` inside the sandbox in addition to
+ printing |
### `$$nemoclaw 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.
+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
@@ -3024,8 +1976,8 @@ $$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 |
-|------|-------------|
+| Flag | Description |
+| ----------- | ----------------------------------------------------------------------------- |
| `--dry-run` | Print the JSON patch for the resulting `hostAliases` list without applying it |
### `$$nemoclaw hosts-list`
@@ -3044,21 +1996,17 @@ Remove a hostname from the sandbox `hostAliases` list.
$$nemoclaw my-assistant hosts-remove searxng.local
```
-| Flag | Description |
-|------|-------------|
+| Flag | Description |
+| ----------- | ----------------------------------------------------------------------------- |
| `--dry-run` | Print the JSON patch for the resulting `hostAliases` list without applying it |
### `$$nemoclaw 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 and Hermes also support experimental Google Chat.
+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 and Hermes also support 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.
+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
@@ -3066,78 +2014,35 @@ $$nemoclaw my-assistant channels list
### `$$nemoclaw channels add `
-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.
-
-Google Chat uses an experimental token-paste flow for the service-account JSON on both agents.
-OpenClaw also requires interactive public-webhook confirmation and prompts for optional app-principal configuration during enrollment.
-Hermes instead prompts for the Google Cloud project ID, complete Pub/Sub subscription name, and email sender allowlist.
-It pulls inbound events from Pub/Sub over REST and does not create a public webhook endpoint.
-
-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.
-Static channel credentials use a validated endpointless OpenShell provider profile so the gateway can replace their sandbox placeholders.
-NemoClaw validates the existing profile, provider type, and credential keys before it reuses a provider.
-A missing, malformed, conflicting, or incompatible provider state stops the operation before reuse.
-Hermes Discord uses its dedicated static provider type because its policy binds the Discord API and Gateway endpoints.
-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 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 ` 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 channels add `.
-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.
+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.
+
+Google Chat uses an experimental token-paste flow for the service-account JSON on both agents. OpenClaw also requires interactive public-webhook confirmation and prompts for optional app-principal configuration during enrollment. Hermes instead prompts for the Google Cloud project ID, complete Pub/Sub subscription name, and email sender allowlist. It pulls inbound events from Pub/Sub over REST and does not create a public webhook endpoint.
+
+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. Static channel credentials use a validated endpointless OpenShell provider profile so the gateway can replace their sandbox placeholders. NemoClaw validates the existing profile, provider type, and credential keys before it reuses a provider. A missing, malformed, conflicting, or incompatible provider state stops the operation before reuse. Hermes Discord uses its dedicated static provider type because its policy binds the Discord API and Gateway endpoints. 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 ` 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 channels add `. 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 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 `` argument, the CLI prints the `channels add ` usage with the supported channel list instead of falling back to top-level help.
+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 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 `` argument, the CLI prints the `channels add ` usage with the supported channel list instead of falling back to top-level help.
### `$$nemoclaw channels remove `
-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.
+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 from the current OpenShell policy so the upstream API is no longer allow-listed after the channel is gone. No session preset list exists to synchronize.
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//` (for example `/sandbox/.openclaw/whatsapp/`).
-- Hermes: `/sandbox/.hermes/platforms//` (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/`.
+- Hermes: `/sandbox/.hermes/platforms//` (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.
@@ -3146,22 +2051,17 @@ $$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 rebuild`.
-`channels start` and `channels stop` follow the same rule.
-If you omit the required `` argument, the CLI prints the `channels remove ` usage with the supported channel list.
+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 rebuild`. `channels start` and `channels stop` follow the same rule. If you omit the required `` argument, the CLI prints the `channels remove ` usage with the supported channel list.
Host-side removal is the supported path because managed startup (or an explicit custom image build) materializes agent channel config as image-owned state (`/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 channels stop `
-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 rebuild omits its runtime configuration, token upsert, and startup effects.
-Generic channel providers and refresh bridges remain detached while the channel is stopped.
+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 rebuild omits its runtime configuration, token upsert, and startup effects. Generic channel providers and refresh bridges remain detached while the channel is stopped.
+
When a stopped Hermes Discord channel keeps a credential-bound policy, the rebuild retains and attaches only the validated static provider that the policy requires.
@@ -3175,44 +2075,31 @@ $$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 channels start `
-Re-enable a channel previously paused with `channels stop`.
-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.
-NemoClaw removes the channel from the disabled list and records it as enabled in the messaging plan.
-The rebuild uses that plan to attach the existing bridge provider before applying its matching built-in network policy preset to the replacement sandbox.
-Before updating the disabled list, NemoClaw prints the 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 the command queues the change without rebuilding, the running sandbox keeps its existing bridge and network policy until you run `$$nemoclaw rebuild`.
+Re-enable a channel previously paused with `channels stop`. 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. NemoClaw removes the channel from the disabled list and records it as enabled in the messaging plan. The rebuild uses that plan to attach the existing bridge provider before applying its matching built-in network policy preset to the replacement sandbox. Before updating the disabled list, 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 the command queues the change without rebuilding, the running sandbox keeps its existing bridge and network policy until you run `$$nemoclaw rebuild`.
```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 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.
+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:
+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. |
@@ -3220,35 +2107,13 @@ The status compatibility probe has this contract:
| 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 channels remove whatsapp` and then `$$nemoclaw 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 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.
-Detailed non-wait JSON keeps the schema-version-1 `{schemaVersion,sandbox,channel,report}` envelope.
-When a probe-capable channel is paused, the command skips the live probe, returns `report.verdict` as `info` with paused registration and runtime-health signals, and exits 0.
-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 ` 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.
+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 channels remove whatsapp` and then `$$nemoclaw 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 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. Detailed non-wait JSON keeps the schema-version-1 `{schemaVersion,sandbox,channel,report}` envelope. When a probe-capable channel is paused, the command skips the live probe, returns `report.verdict` as `info` with paused registration and runtime-health signals, and exits 0. 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 ` 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
@@ -3258,81 +2123,40 @@ $$nemoclaw my-assistant channels status --channel slack --wait --timeout 180 --j
```
| Flag | Description |
-|------|-------------|
+| --- | --- |
| `--channel ` | Channel to inspect in detail |
| `--wait` | Wait for the selected channel's manifest-defined readiness check (requires `--channel`) |
| `--timeout ` | 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 |
-Without `--wait`, a detailed channel status request with `--json` returns the `schemaVersion`, `sandbox`, `channel`, and `report` envelope.
-A paused channel retains that envelope when NemoClaw skips its live probe.
-With `--wait`, the result contains top-level `status` and `readiness` fields, and the detailed channel status envelope is under `status`.
-
-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.
+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.
### `$$nemoclaw 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.
+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 |
-|------|-------------|
+| Flag | Description |
+| -------- | ----------------------------------------------------------------------------- |
| `--json` | Emit sandbox, support, and MCP server state as JSON without credential values |
### `$$nemoclaw 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 ` option to admit an 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 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 resolver placeholder for the recorded key into the agent configuration.
-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.106` evaluates that policy before replacing the attached provider placeholder in the allowed request header.
-NemoClaw imports the endpointless `nemoclaw-mcp-v1` profile and binds the dedicated provider to that endpoint with `credential_binding.provider`.
-OpenShell withholds the credential before the binding is active and outside the bound host, port, and path.
-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 generated policy, expected provider attachment, recorded provider ID, `nemoclaw-mcp-v1` 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).
+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 ` 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 resolver placeholder for the recorded key into the agent configuration. 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.106` evaluates that policy before replacing the attached provider placeholder in the allowed request header. NemoClaw imports the endpointless `nemoclaw-mcp-v1` profile and binds the dedicated provider to that endpoint with `credential_binding.provider`. OpenShell withholds the credential before the binding is active and outside the bound host, port, and path. 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, `nemoclaw-mcp-v1` 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).
-Hermes MCP add, restart, and remove mutate managed config and are refused while shields are up.
-Hermes includes the credential revision from the readiness check in the resolver placeholder and preserves it through inspection, rollback, and lifecycle reconciliation while OpenShell still reports it.
-Run `$$nemoclaw shields down --timeout 15m --reason "MCP maintenance"` before the mutation, then run `$$nemoclaw 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.
+Hermes MCP add, restart, and remove mutate managed config and are refused while shields are up. Hermes includes the credential revision from the readiness check in the resolver placeholder and preserves it through inspection, rollback, and lifecycle reconciliation while OpenShell still reports it. Run `$$nemoclaw shields down --timeout 15m --reason "MCP maintenance"` before the mutation, then run `$$nemoclaw 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.
-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 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.
+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 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.
@@ -3355,45 +2179,22 @@ unset LOCAL_MCP_TOKEN
### `$$nemoclaw 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.
-When a single server is named, status requests a differential wire-level credential-resolution probe.
-It sends no probe traffic unless the generated policy equals the effective gateway policy, the expected provider attachment is confirmed, and the live provider has the recorded ID, `nemoclaw-mcp-v1` 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 recorded resolver 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 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.
+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. 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, `nemoclaw-mcp-v1` 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 recorded resolver 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 |
@@ -3401,29 +2202,16 @@ $$nemoclaw my-assistant mcp status [server] [--json] [--probe|--no-probe] [--too
### `$$nemoclaw 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.
-An existing provider with the profile-less legacy `generic` type must be removed and added again with its credential exported.
-OpenShell 0.0.106 cannot bind that provider to an MCP endpoint, so restart and rebuild fail closed instead of activating it.
-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.
+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. An existing provider with the profile-less legacy `generic` type must be removed and added again with its credential exported. OpenShell 0.0.106 cannot bind that provider to an MCP endpoint, so restart and rebuild fail closed instead of activating it. 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.
-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.
+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.
-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.
+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.
@@ -3437,106 +2225,59 @@ Remove an MCP server from a sandbox.
-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.
+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.
-For an ordinary managed entry, NemoClaw unregisters the sandbox agent adapter, removes the owned generated policy, detaches and deletes the recorded OpenShell provider, and clears the sandbox registry entry.
-For a stored legacy entry whose credential name is no longer accepted, it first detaches the provider so adapter cleanup cannot start with that credential attached.
-Deep Agents teardown does not require managed MCP capability v2 from the old image.
-For a v1 image, NemoClaw removes the 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 recorded ID and credential key plus an accepted managed provider type, and policy deletion still requires live policy content to equal the recorded owned content.
-A legacy `generic` provider is accepted only for cleanup.
-Residuals preserve registry state.
-OpenShell `0.0.106` mutates providers by name, so do not concurrently replace a managed provider through another OpenShell client during this command.
+For an ordinary managed entry, NemoClaw unregisters the sandbox agent adapter, removes the exact owned generated policy, detaches and deletes the recorded OpenShell provider, and clears the sandbox registry entry. For a stored legacy entry whose credential name is no longer accepted, it first detaches the exact provider so adapter cleanup cannot start with that credential attached. 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 recorded ID and credential key plus an accepted managed provider type, and policy deletion still requires exact owned content. An exact legacy `generic` provider is accepted only for cleanup. Residuals preserve registry state. OpenShell `0.0.106` 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 mcp remove --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.
+When an interrupted destroy leaves a prepared-only transaction, deletion is not durably confirmed. If the sandbox is still live, run `$$nemoclaw mcp remove --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 destroy` to finish the idempotent provider and policy cleanup.
+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 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 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. |
+| --- | --- |
+| `--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 skill install `
-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.
+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.
+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.
-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/` 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.
+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/` 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.
-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.
+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.
-For Deep Agents, the command installs a fresh skill directly into `/sandbox/.deepagents/agent/skills/`, 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 connect` to inspect the existing directory.
-Update it manually only after confirming ownership.
-The legacy `/sandbox/.deepagents/skills/` 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.
+For Deep Agents, the command installs a fresh skill directly into `/sandbox/.deepagents/agent/skills/`, 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 connect` to inspect the existing directory. Update it manually only after confirming ownership. The legacy `/sandbox/.deepagents/skills/` 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.
-Run `$$nemoclaw 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.
+Run `$$nemoclaw 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.
+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.
+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 skill remove `
-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.
+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.
@@ -3545,16 +2286,12 @@ For OpenClaw, the command also removes the OpenClaw home-directory mirror when p
-Start a new Hermes chat session for the removal to take effect.
-A gateway restart is not required.
+Start a new Hermes chat session for the removal to take effect. A gateway restart is not required.
-For Deep Agents, automatic removal is refused before any sandbox files change.
-The active `/sandbox/.deepagents/agent/skills/` directory is shared with agent-authored content, so its presence alone cannot prove NemoClaw owns it.
-Use `$$nemoclaw connect` to inspect the existing directory.
-Remove it manually only after confirming ownership.
+For Deep Agents, automatic removal is refused before any sandbox files change. The active `/sandbox/.deepagents/agent/skills/` directory is shared with agent-authored content, so its presence alone cannot prove NemoClaw owns it. Use `$$nemoclaw connect` to inspect the existing directory. Remove it manually only after confirming ownership.
@@ -3562,16 +2299,13 @@ Remove it manually only after confirming ownership.
$$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 `..`.
+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 `..`.
### `$$nemoclaw 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.
+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
@@ -3581,8 +2315,7 @@ $$nemoclaw my-assistant agents list --bindings
### `$$nemoclaw 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.
+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
@@ -3591,9 +2324,7 @@ $$nemoclaw my-assistant agents add work --model gpt-4o
### `$$nemoclaw agents delete `
-Remove an OpenClaw agent from the sandbox.
-This is a thin pass-through to `openclaw agents delete ` 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.
+Remove an OpenClaw agent from the sandbox. This is a thin pass-through to `openclaw agents delete ` 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
@@ -3602,11 +2333,7 @@ $$nemoclaw my-assistant agents delete work --force --json
### `$$nemoclaw 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 --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.
+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 --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
@@ -3622,9 +2349,7 @@ Pass `-f` / `--file ` to point at the manifest; `--yes` confirms th
### `$$nemoclaw 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.
+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
@@ -3636,8 +2361,7 @@ $$nemoclaw my-assistant sessions --all-agents --json
### `$$nemoclaw 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.
+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
@@ -3650,8 +2374,7 @@ $$nemoclaw my-assistant sessions --source cli --limit 20
### `$$nemoclaw 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.
+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
@@ -3663,8 +2386,7 @@ $$nemoclaw my-assistant sessions list --agent main --json
### `$$nemoclaw sessions list`
-Invoke `hermes sessions list` inside the sandbox.
-NemoClaw forwards native Hermes flags such as `--source` and `--limit` and streams the output unchanged.
+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
@@ -3673,9 +2395,7 @@ $$nemoclaw my-assistant sessions list --source cli --limit 20
### `$$nemoclaw sessions delete `
-Invoke `hermes sessions delete --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.
+Invoke `hermes sessions delete --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
@@ -3687,8 +2407,7 @@ $$nemoclaw my-assistant sessions delete 20260727_130357_cb2b61
### `$$nemoclaw sessions reset `
-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.
+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
@@ -3698,20 +2417,17 @@ $$nemoclaw my-assistant sessions reset agent:main:main --json
```
| Flag | Description |
-|------|-------------|
+| --- | --- |
| `--agent ` | Agent id when `` is an alias rather than the canonical `agent::` 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 `` argument accepts an alias (e.g. `main`, `telegram:t-1`) or the canonical `agent::` form.
-Mismatched `--agent` plus canonical-key combinations are refused before the gateway is invoked.
+The `` argument accepts an alias (e.g. `main`, `telegram:t-1`) or the canonical `agent::` form. Mismatched `--agent` plus canonical-key combinations are refused before the gateway is invoked.
### `$$nemoclaw sessions delete `
-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.
+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
@@ -3721,7 +2437,7 @@ $$nemoclaw my-assistant sessions delete agent:main:slack:c-9 --json
```
| Flag | Description |
-|------|-------------|
+| --- | --- |
| `--agent ` | Agent id when `` is an alias rather than the canonical `agent::` form. |
| `--keep-transcript` | Retain the session transcript on disk after the entry is removed. |
| `--json` | Print the delete result as JSON. |
@@ -3733,13 +2449,7 @@ $$nemoclaw my-assistant sessions delete agent:main:slack:c-9 --json
### `$$nemoclaw 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 --json` and copies only the matching `.jsonl` files, plus optional `.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::` keys, to filter.
+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 --json` and copies only the matching `.jsonl` files, plus optional `.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::` keys, to filter.
```bash
$$nemoclaw my-assistant sessions export
@@ -3749,20 +2459,14 @@ $$nemoclaw my-assistant sessions export --format tar --out ./bundles/alpha.tgz -
```
| Flag | Description |
-|------|-------------|
+| --- | --- |
| `--agent ` | Agent id when `` are aliases rather than the canonical `agent::` form. |
| `--format ` | `dir` (default) writes a directory of session files; `tar` writes a single `.tgz` bundle for sharing/upload. |
| `--out ` | Host destination. Defaults to `./sessions-/` for `dir` or `./sessions--.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.
-If the staging cleanup fails, the command warns with the retained path and a manual removal command.
-The retained artifact can contain session JSONL with pasted secrets.
-Run the removal command from the warning, then inspect that same retained path to confirm it no longer exists.
+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. If the staging cleanup fails, the command warns with the retained path and a manual removal command. The retained artifact can contain session JSONL with pasted secrets. Run the exact removal command from the warning, then inspect that same retained path to confirm it no longer exists.
The export keeps its original success or failure result, so a cleanup warning after a successful download does not make the export fail.
@@ -3771,11 +2475,7 @@ The export keeps its original success or failure result, so a cleanup warning af
### `$$nemoclaw 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-.jsonl`; `--out` picks a different path.
+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-.jsonl`; `--out` picks a different path.
```bash
$$nemoclaw my-assistant sessions export
@@ -3784,16 +2484,12 @@ $$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 ` | Host destination. Defaults to `./sessions-.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.
-If the staging cleanup fails, the command warns with the retained path and a manual removal command.
-The retained artifact can contain session JSONL with pasted secrets.
-Run the removal command from the warning, then inspect that same retained path to confirm it no longer exists.
+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. If the staging cleanup fails, the command warns with the retained path and a manual removal command. The retained artifact can contain session JSONL with pasted secrets. Run the exact removal command from the warning, then inspect that same retained path to confirm it no longer exists.
The export keeps its original success or failure result, so a cleanup warning after a successful download does not make the export fail.
@@ -3801,17 +2497,7 @@ The export keeps its original success or failure result, so a cleanup warning af
### `$$nemoclaw download [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.
+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.
@@ -3840,8 +2526,7 @@ $$nemoclaw my-assistant download /sandbox/.deepagents/.state/ ./deepagents-state
### `$$nemoclaw upload [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.
+Host-side wrapper around `openshell sandbox upload`, symmetric to the download wrapper. With no `sandbox-dest` the destination defaults to `/sandbox/` inside the sandbox.
@@ -3870,31 +2555,14 @@ $$nemoclaw my-assistant upload ./agent-skills/ /sandbox/.deepagents/agent/skills
### `$$nemoclaw 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.
+Upgrade a sandbox to the current agent version while preserving workspace state. The command backs up workspace state, captures the current OpenShell policy into a private temporary handoff, destroys the old sandbox, recreates it with the current image, and restores workspace state. Credentials are stripped from backups before storage. The replacement receives the captured OpenShell document directly; NemoClaw does not reconstruct policy from preset records. 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 ] [--dcode-auto-approval ] [--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 registered MCP intent through host-side recovery. |
| `--verbose`, `-v` | Log SSH commands, exit codes, and session state (also enabled by `NEMOCLAW_REBUILD_VERBOSE=1`) |
@@ -3902,50 +2570,9 @@ $$nemoclaw my-assistant rebuild [--yes|-y|--force] [--verbose|-v] [--tool-disclo
| `--dcode-auto-approval ` | 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 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 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, a 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 `policy exclude` or `policy restore` command to rerun.
-For a prepared-only transaction, the redacted diagnostic points to `$$nemoclaw mcp remove --force` when the sandbox is still live.
-For a pending or both-marker transaction, it points to `$$nemoclaw 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.
-A mount-free journal written before host-mount identity binding remains resumable.
-An older journal that used host mounts fails closed because it cannot prove the original host source identity, even when the visible mount settings are unchanged.
-Preserve the sandbox, onboarding session, printed backup, error, and `Journaled replacement` diagnostic, then follow the legacy journal guidance in [Continue an Interrupted Replacement](../manage-sandboxes/operate-sandboxes/recover-and-rebuild-sandboxes#continue-an-interrupted-replacement).
-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.
+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 plus exact provider and target identities, without trying an in-sandbox adapter scrub or changing MCP lifecycle state. Each bridge must record the adapter for the sandbox.s recorded agent. It rechecks the registry, recorded gateway, resolved targets, and provider identities immediately before deletion; incomplete adds, drift, or ambiguous bridge state stop before deletion. Policy is not part of that ownership proof; rebuild independently captures the complete current OpenShell policy and hands it to replacement creation. 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. For a prepared-only transaction, the redacted diagnostic points to `$$nemoclaw mcp remove --force` when the sandbox is still live. For a pending or both-marker transaction, it points to `$$nemoclaw 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. A mount-free journal written before host-mount identity binding remains resumable. An older journal that used host mounts fails closed because it cannot prove the original host source identity, even when the visible mount settings are unchanged. Preserve the sandbox, onboarding session, printed backup, exact error, and `Journaled replacement` diagnostic, then follow the legacy journal guidance in [Continue an Interrupted Replacement](../manage-sandboxes/operate-sandboxes/recover-and-rebuild-sandboxes#continue-an-interrupted-replacement). 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.
@@ -3954,28 +2581,18 @@ After restore, the command runs `openclaw doctor --fix` for cross-version struct
-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.
+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.
-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.
+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 current live OpenShell policy can be captured. 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.
### `$$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.
-The update request and every redirect require HTTPS:
+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. The update request and every redirect require HTTPS:
```bash
curl -fsSL --proto '=https' --proto-redir '=https' https://www.nvidia.com/nemoclaw.sh | bash
@@ -3986,112 +2603,62 @@ $$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:
+`$$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 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).
+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` | Inspect sandbox state without rebuilding. Exits nonzero when it reports stale state, an unknown version, a backup recovery condition, or a sandbox missing from its recorded gateway. Inspect each diagnostic before you select a remediation. |
| `--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 rebuild`, so workspace files survive the upgrade.
-If the registry or required managed-image catalog evidence is unavailable, NemoClaw fails closed instead of selecting an unpinned image.
-Restore registry access, then rerun the command so NemoClaw can validate the image digest.
-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.
+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 rebuild`, so workspace files survive the upgrade. If the registry or required managed-image catalog evidence is unavailable, NemoClaw fails closed instead of selecting an unpinned image. Restore registry access, then rerun the command so NemoClaw can validate the exact image digest. 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.
+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 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.
+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`.
+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.
+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 snapshot create`
-Create a timestamped snapshot of sandbox state.
-Snapshots are stored in `~/.nemoclaw/rebuild-backups//`.
-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 backup owner to finish.
-Auto-restore does not signal the backup process.
-If ownership becomes ambiguous, NemoClaw attempts to record durable containment and reports generation recovery guidance.
-If the containment commit fails, NemoClaw retains any 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 shields status` to resume recovery or receive 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.
+Create a timestamped snapshot of sandbox state. Snapshots are stored in `~/.nemoclaw/rebuild-backups//`. 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 shields status` to resume recovery or receive exact-generation recovery guidance. Snapshot metadata does not contain policy presets or exclusions.
```bash
$$nemoclaw my-assistant snapshot create
```
| Flag | Description |
-|------|-------------|
+| --- | --- |
| `--name