> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemoclaw/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemoclaw/_mcp/server.

# NemoDeepAgents CLI Commands Reference

> Full CLI reference for standalone NemoDeepAgents commands and Deep Agents-specific in-sandbox commands.

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).

## Agent Selection

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

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

## In-Sandbox Commands

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.

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

## Standalone Host Commands

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

### `nemo-deepagents help`, `nemo-deepagents --help`, `nemo-deepagents -h`

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

```bash
nemo-deepagents help
```

### `nemo-deepagents --version`, `nemo-deepagents -v`

Print the installed NemoClaw CLI version.

```bash
nemo-deepagents --version
```

### `nemo-deepagents resources`

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

```bash
nemo-deepagents resources [--json]
```

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

### `nemo-deepagents agents list`

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

```bash
nemo-deepagents agents list
```

Expected output:

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

### `nemo-deepagents onboard`

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

```bash
nemo-deepagents onboard [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from <Dockerfile>] [--name <sandbox>] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device <device>] [--agent <name>] [--agents <agents.yaml>] [--tool-disclosure <progressive|direct>] [--observability | --no-observability] [--control-ui-port <N>] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software]
```

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

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

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

#### `--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, and custom Dockerfile path recorded by the original run.
Completed onboarding sessions are not resumable.
Use `--resume` only for interrupted `in_progress` 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.

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 `nemo-deepagents onboard`, which skips automatic resume detection.
`--resume` and `--fresh` are mutually exclusive.
For an existing completed sandbox, use `--fresh --name <sandbox-name> --recreate-sandbox` when you intentionally want onboarding to replace that sandbox with a new provider, model, agent, or build-time setting.
Use `nemo-deepagents <sandbox-name> rebuild` when you want NemoClaw to recreate the sandbox from its recorded registry metadata without changing those selections.

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

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

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

```bash
nemo-deepagents onboard --name my-assistant --recreate-sandbox --tool-disclosure direct
```

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

#### `--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 `nemo-deepagents` 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
nemo-deepagents onboard --observability
nemoclaw onboard --agent langchain-deepagents-code --observability
```

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

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

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

```bash
nemo-deepagents my-dcode rebuild --observability --yes
nemo-deepagents 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 the complete collector setup, privacy boundary, policy recovery, verification, and a host-side LangSmith exporter example, refer to [Quickstart with LangChain Deep Agents Code](/user-guide/deepagents/get-started/quickstart#export-traces-through-a-local-collector).

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 nemo-deepagents onboard --recreate-sandbox
NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1 nemo-deepagents <sandbox-name> rebuild
```

Base-image selection follows this precedence:

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

After a cache miss, source checkouts require a fresh local build before candidate selection when base-image inputs have dirty or staged changes, or Git cannot inspect the worktree safely.
For a clean checkout, NemoClaw first accepts an exact release-version or source-commit image; only when neither exists does a difference from `main` or a missing comparison ref require a fresh local build before `: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.

Otherwise, normal resolution checks compatible images in Docker's local image store before attempting to pull a missing published candidate.
When the OpenShell sandbox ABI is required, NemoClaw can reuse or build an ABI-compatible local fallback when published candidates are unavailable or incompatible.
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.

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 `nemo-deepagents onboard` when you need to create or recreate the OpenShell gateway or sandbox.
Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemo-deepagents onboard`.

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

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

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

When existing sandboxes were created with OpenShell earlier than `0.0.37`, the installer prompts before running the new automatic gateway upgrade path.
For scripted installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1` to allow the installer to prepare the current CLI without replacing OpenShell, back up every registered sandbox with the current state manifest, retire the old gateway, install the supported OpenShell release, and recover the existing sandboxes.
If any registered sandbox cannot be backed up, the installer aborts before it changes the gateway.
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 a manually prepared upgrade, set `NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1` only after preserving every registered sandbox and retiring the old gateway.

The wizard prompts for a provider first, then collects the provider credential if needed.
Supported non-experimental choices include NVIDIA Endpoints, 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 `nemo-deepagents setup` command is deprecated; use `nemo-deepagents onboard` instead.

After provider selection, the wizard reviews the provider, model, credential state, and sandbox name before registering inference.

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.
Three 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.                  |

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.
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.
Later re-onboard runs seed from that finalized selection, so presets you intentionally removed stay removed unless you select them again or override the policy mode.

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

```bash
NEMOCLAW_POLICY_TIER=restricted nemo-deepagents 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`, or `open`; 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 [`nemo-deepagents <name> policy-add`](#nemo-deepagents-name-policy-add) across re-onboards.
Use `custom` with `NEMOCLAW_POLICY_PRESETS` when you want the explicit list to be authoritative.
Onboarding removes any preset that is not in the list.
`skip` leaves the applied set untouched and does not apply tier defaults.
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.
An explicit `custom` preset list or interactive manual selection remains operator-controlled.

| Value                 | Behaviour                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`.                 |
| `custom`              | Apply exactly `NEMOCLAW_POLICY_PRESETS`. Previously-applied presets not in the list are removed. Alias: `list`. |
| `skip`                | Skip the policy step entirely. Aliases: `none`, `no`.                                                           |

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

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

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

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

```bash
nemo-deepagents onboard --non-interactive --yes-i-accept-third-party-software
```

or:

```bash
NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 nemo-deepagents onboard --non-interactive
```

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

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

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

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

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

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

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

Before creating the gateway, the wizard runs preflight checks.
It verifies that Docker is reachable, warns on untested runtimes such as Podman, and prints host remediation guidance when prerequisites are missing.
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 `nemo-deepagents onboard` is safe to run just to check preflight output.
For Linux Docker-driver gateways, onboarding also checks that a helper container on the OpenShell Docker network can reach `host.openshell.internal:<gateway-port>`.
If a host firewall blocks that sandbox path, onboarding exits with a `sudo ufw allow from <subnet> to <gateway-ip> port <gateway-port> proto tcp` command before it reports the gateway healthy.
Set `NEMOCLAW_AUTO_FIX_FIREWALL=1` to opt in to automatic UFW remediation for this specific failure: NemoClaw uses `sudo -n` only, validates the Docker bridge subnet/gateway/port, applies the narrow UFW rule only after a proven TCP reachability failure, and re-probes before continuing.
If passwordless sudo, UFW, or active UFW is unavailable, NemoClaw falls back to the manual guidance path without prompting for a password.
Tune the wait via `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 probe always runs at least once, and the interval is clamped to a minimum of `0` (no sleep between attempts).

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

Build the sandbox image from a custom Dockerfile instead of the stock NemoClaw image.
The 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.
If that directory contains a `.dockerignore`, onboarding applies those rules 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.

```bash
nemo-deepagents 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 file can have any name; if it is not already named `Dockerfile`, onboard copies it to `Dockerfile` inside the staged build context automatically.
To create an isolated build context, create a dedicated directory that contains only the Dockerfile and the files it needs:

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

For faster custom builds, plan for Docker cache behavior:

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

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

All NemoClaw build arguments (`NEMOCLAW_MODEL`, `NEMOCLAW_PROVIDER_KEY`, `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.

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

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

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

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

```bash
NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_FROM_DOCKERFILE=path/to/Dockerfile NEMOCLAW_SANDBOX_NAME=my-build nemo-deepagents onboard
```

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

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

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

```bash
nemo-deepagents onboard --non-interactive --name my-build --from path/to/Dockerfile
```

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

### `nemo-deepagents onboard --from`

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

```bash
nemo-deepagents onboard --from ./Dockerfile.custom
```

### GPU passthrough

When `nemo-deepagents onboard` detects an NVIDIA GPU on the host, it enables OpenShell GPU passthrough at both the gateway and sandbox level by default.
Detection proceeds along two paths. The `nvidia-smi`-based paths (the primary `--query-gpu=name,memory.total,memory.free` probe and the unified-memory `--query-gpu=name` fallback) require `nvidia-smi` to succeed and, on hosts whose firmware does not classify as a known NVIDIA platform (DGX Spark, DGX Station, Jetson, or Tegra), additionally require that the GPU name does not match the placeholder family observed on the Windows-on-ARM WSL2 nvidia-smi shim (`JMJWOA-Generic-*`) and that either the host is not ARM64 Linux (the observed shim is Windows-on-ARM only) or the NVIDIA kernel driver is bound (`/proc/driver/nvidia/` present), so that placeholder shims on non-NVIDIA hardware are not mistaken for real GPUs.
Jetson/Tegra hosts that ship without `nvidia-smi` continue to be detected via the devicetree firmware fallback (`/sys/firmware/devicetree/base/model`) or the Tegra device-node fallback (`/dev/nvhost-gpu`, `/dev/nvhost-ctrl-gpu`, `/dev/nvhost-ctrl`, or `/dev/nvmap`); both bypass the trust-tier gate above.
Use `--no-gpu` to opt out when you want host-side inference providers only and do not need direct GPU access inside the sandbox.
Use `--gpu` to require GPU passthrough and fail fast if an NVIDIA GPU is not detected.
Use `--sandbox-gpu` or `--no-sandbox-gpu` to control only direct NVIDIA GPU access inside the sandbox.
Use `--sandbox-gpu --sandbox-gpu-device <device>` to pass a specific OpenShell GPU device selector to `openshell sandbox create`; device selectors require explicit sandbox GPU enablement.
On ordinary native Linux Docker-driver hosts with usable CDI, NemoClaw uses OpenShell native GPU injection by default.
On Docker Desktop WSL and Jetson/Tegra, NemoClaw creates the sandbox first and then recreates the OpenShell-managed Docker container with NVIDIA GPU access by default.
When you force this compatibility path on ordinary native Linux, NemoClaw 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 the host group IDs that own `/dev/nvmap` and `/dev/nvhost-*` so the sandbox user can initialize CUDA.
If the patch fails, onboarding keeps diagnostics and prints a manual cleanup command rather than deleting the failed sandbox automatically.

Prerequisites:

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

When GPU passthrough is enabled and a gateway already exists without it, onboarding first checks whether replacing the CPU-only gateway is safe.
If no other registered sandbox depends on that gateway, or if `--recreate-sandbox` is recreating the only registered sandbox with the same name, onboarding cleans up the stale gateway and continues.
If other sandboxes depend on the gateway or Docker state is unclear, onboarding exits without cleanup and prints targeted destroy or gateway-removal guidance.
To add GPU to an existing sandbox, rerun with `--recreate-sandbox`.
Leave `NEMOCLAW_DOCKER_GPU_PATCH` unset or set it to `auto` to use the platform default.
Set `NEMOCLAW_DOCKER_GPU_PATCH=1` to force the legacy Docker container-swap path on ordinary native Linux.
Set `NEMOCLAW_DOCKER_GPU_PATCH=0` to select native OpenShell GPU injection on ordinary native Linux or Jetson/Tegra.
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.

### `nemo-deepagents 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.
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.
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
nemo-deepagents list [--json]
nemo-deepagents list --json
```

### `nemo-deepagents use <name>`

Promote a registered sandbox to the default.
This is the first-class replacement for hand-editing `~/.nemoclaw/sandboxes.json`; it updates the registry through the same atomic, lock-guarded path that `nemo-deepagents 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.

`nemo-deepagents 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
nemo-deepagents use <name>
nemo-deepagents use <name> --json
```

### `nemo-deepagents deploy`

The `nemo-deepagents deploy` command is deprecated.
Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `nemo-deepagents 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.

```bash
nemo-deepagents deploy <instance-name>
```

### `nemo-deepagents <name> connect`

Connect to a sandbox by name.
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` (integer seconds, default `120`). 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 `nemo-deepagents <name> rebuild` hint.
If another terminal is already connected to the sandbox, `connect` prints a note with the number of existing sessions before proceeding. Multiple concurrent sessions are allowed.

`connect` does not pull or serve 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.

When the live OpenShell gateway inference route differs from the route recorded in the NemoClaw registry, `connect` checks every registered sandbox on that gateway before attempting a repair.
It realigns the route only when those registry entries are compatible with the requested provider and model.
If another sandbox records a conflicting route, `connect` exits non-zero without changing the gateway and names the affected sandboxes.
Use `nemo-deepagents inference set --provider <provider> --model <model>` to make an intentional compatible route change.
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 `nemo-deepagents onboard` after a reboot in this case.

```bash
nemo-deepagents my-assistant connect [--probe-only]
```

The `--probe-only` flag verifies the sandbox is reachable over SSH and exits without opening a shell.
Use it for health checks and scripted readiness probes.

### `nemo-deepagents <name> exec`

Run a single command non-interactively in a running sandbox via the OpenShell exec endpoint.
The command runs as the sandbox user with `HOME=/sandbox`, so in-sandbox tooling resolves NemoClaw-provisioned config the same way it does for `connect` and `openshell sandbox connect`.
This is the supported substitute for `docker exec` on the sandbox container; raw `docker exec` runs as root and lands on `HOME=/root`, where the selected agent config is not present.

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

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' | nemo-deepagents my-assistant exec --stdin -- cat
ssh dgx-spark 'nemo-deepagents my-assistant exec --no-stdin -- pwd'
```

The OpenShell exec endpoint rejects any command argument (the values after `--`) that contains a newline or carriage return, so multi-line commands such as a `bash` heredoc cannot be passed through `exec`.
NemoClaw detects this before dispatch, names the offending argument position, and exits with status `2` instead of surfacing the lower-level OpenShell `InvalidArgument` error.
Join the statements with semicolons (`nemo-deepagents <name> exec -- bash -lc "cmd1; cmd2"`).
Pipe the script into the sandbox shell over stdin (`printf 'cmd1\ncmd2\n' | nemo-deepagents <name> exec --stdin -- bash`).
Or write the script to a file in the sandbox and run it (`nemo-deepagents <name> exec -- bash <script-path>`).

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

### `nemo-deepagents <name> agent`

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 `nemo-deepagents <name> agent -n "<task>"` from the host.
The host wrapper keeps `HOME=/sandbox`, the managed proxy environment, and the manifest-declared Deep Agents config path aligned with `connect`.
Interactive `nemo-deepagents <name> agent` launches the same terminal TUI as `dcode`.
Headless `nemo-deepagents <name> agent -n "<task>"` uses the managed headless boundary, where non-shell tools can auto-run without the interactive approval UI.

### Advanced Sandbox Maintenance Commands

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

#### `nemo-deepagents <name> config get`

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

```bash
nemo-deepagents my-assistant config get
nemo-deepagents my-assistant config get --key model --format yaml
```

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

#### `nemo-deepagents <name> shields`

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

```bash
nemo-deepagents my-assistant shields status
nemo-deepagents my-assistant shields up
nemo-deepagents 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 `shields up` reports that the config remains unlocked or drifted, confirm that the sandbox is running and ready, then retry `nemo-deepagents <name> shields up`.
If the retry still fails, rebuild a known-good baseline with `nemo-deepagents <name> rebuild --yes`.

Host-side config and inference writes, snapshot mutation, sandbox destruction, and shields transitions serialize per sandbox.
When a timed shields-down window reaches its deadline, auto-restore can interrupt the exact process tree holding that transition and restore lockdown.
Retry an interrupted command in a new shields-down window.

### `nemo-deepagents <name> status`

Show sandbox-scoped status, health, and inference configuration for one registered sandbox.
Use this form when you care about a specific sandbox's live OpenShell state, agent runtime, inference health, GPU proof, permissions, and recovery hints.
Do not pass a sandbox name to `nemo-deepagents status`; that command is the global all-sandbox/service overview.

Pass `--json` to emit a structured per-sandbox report instead of the text renderer.
The JSON output includes at least `schemaVersion`, `name`, `found`, `model`, `provider`, `phase`, `gatewayState`, `inferenceHealth`, `rpcIssue`, `hostGpuDetected`, `sandboxGpuEnabled`, `sandboxGpuMode`, `sandboxGpuDevice`, `openshellDriver`, `openshellVersion`, `policies`, `failureLayer`, `terminalRuntimeHealth`, and `dockerPaused`.
`openshellDriver` and `openshellVersion` are always strings (falling back to `"unknown"` when the registry has no value), so consumers can rely on `typeof` checks.
`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.
`dockerPaused` is `true` when NemoClaw detects that the Docker-driver sandbox container is paused.
In that case, text output keeps OpenShell's authoritative phase but prints a `docker unpause <container>` recovery hint instead of sending you directly to rebuild.
For terminal runtime sandboxes, the command also checks cgroup OOM kill counters.
If the counter records an OOM kill, text output prints `Runtime health: degraded (... OOM kill recorded)` and points you to `nemo-deepagents <name> rebuild`; JSON output reports `terminalRuntimeHealth.kind: "degraded"` with the OOM kill count and source counter path.
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, or a terminal runtime sandbox reports a recorded OOM kill.
The alias form `nemo-deepagents <name> status --json` requires the sandbox to be registered locally; the canonical form `nemo-deepagents sandbox status <name> --json` is the one to use from automation that may run against an unknown sandbox name, since it still emits a JSON document with `found: false` instead of a text error.

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

The command probes every inference provider and reports one of three states on the `Inference` line:

| State          | Meaning                                                                                |
| -------------- | -------------------------------------------------------------------------------------- |
| `healthy`      | The provider endpoint returned a reachable response.                                   |
| `unreachable`  | The probe failed. The output includes the endpoint URL and a remediation hint.         |
| `not probed`   | The endpoint URL is not known (for example, `compatible-*` providers).                 |
| `not verified` | NemoClaw could not verify the sandbox or gateway state, so it skips inference probing. |

Local providers (Ollama, vLLM) probe the host-side health endpoint.
Remote providers (NVIDIA Endpoints, OpenAI, Anthropic, Gemini) use a lightweight reachability check; any HTTP response, including `401` or `403`, counts as reachable.
No API keys are sent.

For Local Ollama, the command also probes the authenticated proxy and prints an `Inference (auth proxy)` line when a proxy token is available.
Use that line to distinguish a healthy backend from a broken proxy path that the sandbox uses for inference.

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 command prints the `sandbox_container_stopped` failure layer with the message `sandbox container exists but is not running.` as the first line of stdout, suppresses the host-side `Inference` probe, and exits with a non-zero status.

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.

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

A `Connected` line reports whether the sandbox has any active SSH sessions and, if so, how many.

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

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

#### Checking the Deep Agents version

NemoClaw pins the Deep Agents Code version inside the sandbox image at build time, not at runtime.
The `langchain-deepagents-code` agent manifest declares the expected version and the `dcode --version` probe command.
Existing sandboxes do not auto-upgrade when a newer NemoClaw release ships a newer Deep Agents Code pin; you upgrade by rebuilding the sandbox.

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

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

Expected output:

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

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

### `nemo-deepagents <name> doctor`

Run a focused health check for one sandbox and the host services it depends on.
The command checks the local CLI build, Docker daemon, OpenShell CLI, NemoClaw gateway container, gateway port mapping, live sandbox state, inference route, provider reachability, Ollama reachability, and the cloudflared tunnel state.

Warnings do not make the command fail.
Failed checks exit non-zero so scripts can use `doctor` as a readiness gate.
Use `--json` for machine-readable output.

### `nemo-deepagents <name> exec`

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

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

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

The OpenShell exec endpoint rejects any command argument (the values after `--`) that contains a newline or carriage return, so multi-line commands such as a `bash` heredoc cannot be passed through `exec`.
NemoClaw detects this before dispatch, names the offending argument position, and exits with status `2` instead of surfacing the lower-level OpenShell `InvalidArgument` error.
Join the statements with semicolons (`nemo-deepagents <name> exec -- bash -lc "cmd1; cmd2"`).
Pipe the script into the sandbox shell over stdin (`printf 'cmd1\ncmd2\n' | nemo-deepagents <name> exec --stdin -- bash`).
Or write the script to a file in the sandbox and run it (`nemo-deepagents <name> exec -- bash <script-path>`).

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

### `nemo-deepagents <name> logs`

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

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

### `nemo-deepagents <name> dashboard-url`

`dashboard-url` is not applicable to Deep Agents sandboxes because the managed harness is a terminal runtime without a dashboard port.
Use `nemo-deepagents <name> connect` and run `dcode` inside the sandbox.

### `nemo-deepagents <name> gateway-token`

`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.

### `nemo-deepagents <name> destroy`

Stop the NIM container, 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.

This command attempts to wipe the manifest-defined agent state while its persistent volume is mounted, then removes the sandbox.
OpenShell can retain the per-name persistent volume after sandbox deletion.
If the wipe cannot complete, onboarding with the same name can resurface old files.
Do not rely on a retained volume as a backup.
Back up your workspace first with `nemo-deepagents <name> snapshot create` or refer to [Backup and Restore](../manage-sandboxes/backup-restore).
If you want to upgrade the sandbox while preserving state, use `nemo-deepagents <name> 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` to skip the prompt in scripted workflows.

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 hardening fails, the command refuses deletion and leaves the timer authority available to retry lockdown.
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, `destroy` preserves the shared NemoClaw gateway.
Pass `--cleanup-gateway` to remove the shared gateway when destroying the last sandbox, or `--no-cleanup-gateway` to force preservation when environment defaults request cleanup.
If the pre-delete workspace wipe cannot run, use a different sandbox name for a clean start.
When this is the last sandbox, pass `--cleanup-gateway` to purge the shared cluster volume that retains the per-name persistent volume.
If the OpenShell gateway is unreachable and the sandbox has no managed MCP ownership state, `--force` removes only NemoClaw's local registry entry and local artifacts.
Gateway-side deletion remains unconfirmed, shared host-service and gateway teardown are skipped, and the sandbox and retained volume may still exist if the gateway returns.
Start the gateway with `nemo-deepagents <name> status` and retry destroy when you need a confirmed deletion.
Managed MCP ownership disables the local-only fallback because exact provider cleanup requires the retained ownership state, and other delete failures remain fatal.

```bash
nemo-deepagents my-assistant destroy [--yes|-y|--force] [--cleanup-gateway|--no-cleanup-gateway]
```

### `nemo-deepagents <name> policy-add`

Add a policy preset to a sandbox.
Presets extend the baseline network policy with additional endpoints.
Before applying, the command shows which endpoints the preset would open and prompts for confirmation.

```bash
nemo-deepagents my-assistant policy-add
```

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

```bash
nemo-deepagents 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.
If the preset name is unknown or already applied, the command exits non-zero with a clear error.
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.
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 current live policy from OpenShell.
If the live 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.

| Flag                 | Description                                                                           |
| -------------------- | ------------------------------------------------------------------------------------- |
| `--from-file <path>` | Apply a custom preset YAML file instead of a built-in preset                          |
| `--from-dir <path>`  | Apply every custom preset YAML file in a directory in lexicographic order             |
| `--yes`, `--force`   | Skip the confirmation prompt (requires a preset name, `--from-file`, or `--from-dir`) |
| `--dry-run`          | Preview the endpoints a preset would open without applying changes                    |

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

```bash
nemo-deepagents my-assistant policy-add --dry-run
```

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

```bash
nemo-deepagents my-assistant policy-add --from-file ./presets/my-internal-api.yaml
```

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

```bash
nemo-deepagents 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.

### `nemo-deepagents <name> policy-list`

List available policy presets and show which ones are applied to the sandbox.
The available built-in rows are scoped to the sandbox's active agent, so unsupported messaging channel policies are not listed for agents without matching channel policy files.
The command cross-references the local registry against the live gateway state (via `openshell policy get`), so it flags presets that are applied in one place but not the other.
This catches desync caused by external edits to the gateway policy or stale registry entries after a manual rollback.
Preset summaries come only from the YAML `preset.description` field.
NemoClaw does not render network-policy rule bodies as prose in `policy-list` output.

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

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

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

```bash
nemo-deepagents my-assistant policy-list
```

### `nemo-deepagents <name> policy-remove`

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

```bash
nemo-deepagents my-assistant policy-remove
```

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

```bash
nemo-deepagents my-assistant policy-remove pypi --yes
```

Set `NEMOCLAW_NON_INTERACTIVE=1` as an alternative to `--yes`.
If the preset is unknown or not currently applied, the command exits non-zero with a clear error.

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

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

### `nemo-deepagents <name> policy-explain`

Print a redacted summary of the active policy context for a sandbox so an agent or operator can reason about what is allowed, what is blocked, and how to request a change.
The output covers the recorded tier, the applied presets (built-in and custom) with their allowed host categories, the known presets that are not applied, the inspect/add/remove commands that change policy, and the support boundaries between NemoClaw, OpenShell, and the agent.
Raw policy YAML, rule bodies, and credential metadata are deliberately not included.

```bash
nemo-deepagents my-assistant policy-explain
```

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

```bash
nemo-deepagents my-assistant policy-explain --json
```

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

| Flag     | Description                                                               |
| -------- | ------------------------------------------------------------------------- |
| `--json` | Emit the policy context as a structured JSON object for agent consumption |

### `nemo-deepagents <name> hosts-add`

Add a host alias to the sandbox pod template.
Use this when a sandbox needs a stable LAN-only name, such as a local SearXNG or internal model endpoint, without dropping to `docker exec` and `kubectl patch`.
Host alias commands use the legacy Kubernetes gateway `Sandbox` resource path.
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
nemo-deepagents my-assistant hosts-add searxng.local 192.168.1.105
```

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

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

### `nemo-deepagents <name> hosts-list`

List host aliases configured on the sandbox resource.

```bash
nemo-deepagents my-assistant hosts-list
```

### `nemo-deepagents <name> hosts-remove`

Remove a hostname from the sandbox `hostAliases` list.

```bash
nemo-deepagents my-assistant hosts-remove searxng.local
```

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

### `nemo-deepagents <name> mcp list`

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

```bash
nemo-deepagents my-assistant mcp list [--json]
```

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

### `nemo-deepagents <name> mcp add`

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

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

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

### `nemo-deepagents <name> mcp status`

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

```bash
nemo-deepagents my-assistant mcp status [server] [--json] [--probe|--no-probe]
```

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

### `nemo-deepagents <name> mcp restart`

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

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.

```bash
nemo-deepagents my-assistant mcp restart [server]
```

### `nemo-deepagents <name> mcp remove`

Remove an MCP server from a sandbox.

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

```bash
nemo-deepagents my-assistant mcp remove github [--force]
```

| Flag      | Description                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--force` | Remove same-name adapter config and continue exact-ownership provider/policy cleanup; preserve registry state when residuals remain |

### `nemo-deepagents <name> skill install <path>`

Deploy a skill directory to a running sandbox.
The command validates the `SKILL.md` frontmatter (a `name` field is required), uploads all non-dot files preserving subdirectory structure, and performs agent-specific post-install steps.

```bash
nemo-deepagents 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.

For Deep Agents, the command uploads skills under `/sandbox/.deepagents/skills/<name>` and mirrors agent-facing skills under `/sandbox/.deepagents/agent/skills/<name>` when the manifest requires that view.
The managed `dcode` launchers discover those skills on the next session without accepting executable hook configuration.

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

Files with names starting with `.` (dotfiles) are skipped and listed in the output.
Files with unsafe path characters are rejected to prevent shell injection.

If the skill already exists on the sandbox, the command updates it in place and preserves chat history.
For new installs, the agent session index is refreshed so the agent discovers the skill on the next session.

### `nemo-deepagents <name> skill remove <skill>`

Remove an installed skill from a running sandbox by skill name.
The command validates the skill name, removes the sandbox upload directory, and refreshes the agent session index so the remaining skills are rediscovered on the next session.

For Deep Agents, the command removes the uploaded skill from the managed `/sandbox/.deepagents` skill paths and refreshes the session index for future `dcode` sessions.
It does not enable project hooks or unmanaged MCP files.

```bash
nemo-deepagents 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 `..`.

### `nemo-deepagents <name> download <sandbox-path> [host-dest]`

Host-side wrapper around `openshell sandbox download` that adds a live-sandbox readiness check.
The sandbox source path is forwarded to OpenShell verbatim; a relative host destination is resolved against the caller's working directory before it reaches OpenShell, so the downloaded file lands where the user invoked the CLI from rather than inside the install directory.
Absolute host destinations pass through unchanged, and the OpenShell transport keeps its file-system semantics (single-file vs directory copy, trailing-slash handling, overwrite behaviour).
With no `host-dest` the destination defaults to the current directory.

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

### `nemo-deepagents <name> upload <host-path> [sandbox-dest]`

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

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

### `nemo-deepagents <name> rebuild`

Upgrade a sandbox to the current agent version while preserving workspace state.
The command backs up workspace state, destroys the old sandbox (including its host-side Docker image), recreates it with the current image via `onboard --resume`, and restores workspace state into the new sandbox.
Credentials are stripped from backups before storage.
Policy presets applied to the old sandbox are reapplied to the new one so your egress rules survive the rebuild.
The replacement uses the recorded compatible-endpoint reasoning mode and web search selection instead of ambient shell values.
The recorded sandbox GPU mode is preserved across rebuild.
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 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
nemo-deepagents my-assistant rebuild [--yes|-y|--force] [--verbose|-v] [--tool-disclosure <progressive|direct>] [--observability|--no-observability]
```

| Flag                                      | Description                                                                                                                                                                       |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--yes`, `-y`, `--force`                  | Skip the confirmation prompt                                                                                                                                                      |
| `--verbose`, `-v`                         | Log SSH commands, exit codes, and session state (also enabled by `NEMOCLAW_REBUILD_VERBOSE=1`)                                                                                    |
| `--tool-disclosure <progressive\|direct>` | Change the model-visible tool catalog during this transactional rebuild. Use this path for sandboxes with managed MCP servers so their providers and adapter state are preserved. |
| `--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 must be running for the backup step to succeed.
If an archive command reports partial output while still producing usable data, `rebuild` keeps the captured backup entries and reports only the manifest-defined paths that could not be archived.
If any required state path still cannot be backed up, `rebuild` exits before destroying the original sandbox.
Before backup or deletion, rebuild checks the staged messaging configuration for credentials or channel resources already used by another registered sandbox.
A conflict aborts with the original sandbox registered and intact so you can resolve the conflict before retrying.
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.

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.

### `nemo-deepagents update`

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

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

```bash
nemo-deepagents update [--check] [--fresh] [--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 even when already up to date (clean re-clone of `~/.nemoclaw/source`); useful to repair a broken-but-current install. Does not reset onboarding state. |
| `--yes`, `-y` | Skip the confirmation prompt and run the maintained installer flow.                                                                                                                   |

`nemo-deepagents 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.
It does not replace `nemo-deepagents 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.

### `nemo-deepagents 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.
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.

```bash
nemo-deepagents upgrade-sandboxes [--check] [--auto] [--yes|-y]
```

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

Each rebuild reuses the same workspace backup-and-restore flow as `nemo-deepagents <name> rebuild`, so workspace files survive the upgrade.
If the registry is unreachable (offline or firewalled hosts), NemoClaw falls back to the unpinned `:latest` tag and reports that the digest could not be resolved instead of failing.
During installer recovery, a registered sandbox that is not Ready can also be rebuilt from its validated latest backup.
That recovery requires a NemoClaw-managed image fingerprint or the installer's explicit confirmation for a listed pre-fingerprint OpenClaw or Hermes entry.
Recorded custom-image evidence remains blocked from automatic recreation.

### `nemo-deepagents backup-all`

Back up all registered running sandboxes to `~/.nemoclaw/rebuild-backups/`.
Sandboxes that are not running are skipped.

```bash
nemo-deepagents 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.

A running sandbox whose in-sandbox SSH endpoint does not answer fails its backup and aborts the run.
For a standalone `nemo-deepagents 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.

### `nemo-deepagents <name> snapshot create`

Create a timestamped snapshot of sandbox state.
Snapshots are stored in `~/.nemoclaw/rebuild-backups/<name>/`.
The command requires shields to be down and keeps the shields check and backup under one per-sandbox transition.
An expired auto-restore timer can interrupt a long-running backup and restore lockdown.

```bash
nemo-deepagents my-assistant snapshot create
```

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

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

```bash
nemo-deepagents my-assistant snapshot create --name before-upgrade
```

### `nemo-deepagents <name> snapshot list`

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

```bash
nemo-deepagents my-assistant snapshot list
```

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

Restore sandbox state from a snapshot.
The sandbox must be running before you restore.
If no selector is provided, the latest snapshot is used.
Restore performs a clean replacement of each state directory, removing files that were added after the snapshot was taken.
The state replacement, mutable-config permission repair, and policy reconciliation run under the same per-sandbox transition.
An expired auto-restore timer can interrupt that work and restore lockdown.

The selector accepts any of:

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

Pass `--to <dst>` to restore the snapshot into a different sandbox instead of the source.
When `dst` does not exist, it is auto-created by reusing the source sandbox's container image.
No re-onboarding is needed.
When `dst` already exists, `snapshot restore --to <dst>` refuses by default to avoid silently mutating the destination's filesystem.
To overwrite an existing destination, pass `--force`: the command deletes `dst`, then recreates it from the source's image and restores the snapshot into the fresh copy.
If the existing destination has an active shields timer, the force path restores and verifies lockdown, revokes the timer, and then deletes the destination.
It clears the remaining local shields state only after deletion succeeds.
The `--force` path prompts interactively to confirm the destination name before deleting.
Pass `--yes` (or set `NEMOCLAW_NON_INTERACTIVE=1`) to skip the prompt.
The snapshot selector and source pod image are both validated before any deletion, so a bad selector or unresolvable image cannot destroy `dst` and only fail afterwards.

```bash
# restore latest snapshot in-place
nemo-deepagents my-assistant snapshot restore

# restore by version
nemo-deepagents my-assistant snapshot restore v3

# restore by user-assigned name
nemo-deepagents my-assistant snapshot restore before-upgrade

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

# clone v3 into a new sandbox
nemo-deepagents my-assistant snapshot restore v3 --to my-assistant-clone

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

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

### `nemo-deepagents <name> share mount`

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

```bash
nemo-deepagents my-assistant share mount
```

Expected output:

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

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

Prerequisites:

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

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

### `nemo-deepagents <name> share unmount`

Unmount a previously mounted sandbox filesystem.

```bash
nemo-deepagents my-assistant share unmount
```

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

### `nemo-deepagents <name> share status`

Check whether the sandbox filesystem is currently mounted.

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

Expected output:

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

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

## `openshell term`

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

```bash
openshell term
```

For a remote Brev instance, SSH to the instance and run `openshell term` there, or use a port-forward to the gateway.

### `nemo-deepagents status`

Show the global sandbox list and the status of host auxiliary services (for example cloudflared).
This command is host-wide. It summarizes registered sandboxes, the default sandbox's live inference route, gateway health, and host services.
Use `nemo-deepagents <name> status` when you need one sandbox's live health and recovery guidance.
Pass `--json` for machine-readable output with registered sandboxes, service state, inference routes, and health details.
For each listed sandbox, the text output includes the configured inference provider and model plus whether an active SSH session is connected.
Host-service PID lookup honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default.

```bash
nemo-deepagents status
nemo-deepagents status --json
```

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

### `nemo-deepagents inference get`

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

```bash
nemo-deepagents inference get
nemo-deepagents inference get --json
```

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

```bash
nemo-deepagents my-assistant inference get
```

### `nemo-deepagents inference set`

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

### `nemo-deepagents setup`

The `nemo-deepagents setup` command is deprecated.
Use `nemo-deepagents onboard` instead.

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

```bash
nemo-deepagents setup
```

### `nemo-deepagents setup-spark`

The `nemo-deepagents setup-spark` command is deprecated.
Use the standard installer and run `nemo-deepagents onboard` instead, because current OpenShell releases handle the older DGX Spark cgroup behavior.

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

```bash
nemo-deepagents setup-spark
```

### `nemo-deepagents debug`

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

```bash
nemo-deepagents debug [--quick|-q] [--sandbox NAME] [--output PATH|-o PATH]
```

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

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

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

### `nemo-deepagents credentials list`

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

```bash
nemo-deepagents credentials list
```

### `nemo-deepagents credentials add <PROVIDER>`

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

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

```bash
nemo-deepagents credentials add tavily-search --type tavily --credential TAVILY_API_KEY
```

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

### `nemo-deepagents credentials reset <PROVIDER>`

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

```bash
nemo-deepagents credentials reset nvidia-prod
```

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

### `nemo-deepagents gc`

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

```bash
nemo-deepagents gc [--dry-run] [--yes|-y|--force]
```

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

### `nemo-deepagents uninstall`

Run `uninstall.sh` to remove NemoClaw sandboxes, gateway resources, related images and containers, and local state.
The CLI runs the local `uninstall.sh` shipped with the installed npm package.
If that local script is missing, the CLI does not auto-fetch a remote copy.
It prints the versioned URL of the matching `uninstall.sh` so you can download, review, and run it manually.

Uninstall also stops any orphaned `openshell` host processes left behind by previous onboard or destroy cycles, including `openshell sandbox create`, `openshell ssh-proxy`, and SSH sessions spawned by OpenShell.
Earlier releases only stopped `openshell forward` processes, so those orphans accumulated across runs.

For Local Ollama setups, uninstall also stops matching Ollama auth proxy processes before deleting `~/.nemoclaw` state so stale proxy listeners do not block a later reinstall.

On Linux, uninstall removes `~/.local/state/nemoclaw`, which contains Docker-driver gateway SQLite data, audit logs, VM-driver state, and standalone-fallback gateway PID files.

| Flag                  | Effect                                                                             |
| --------------------- | ---------------------------------------------------------------------------------- |
| `--yes`               | Skip the confirmation prompt                                                       |
| `--keep-openshell`    | Leave OpenShell binaries installed                                                 |
| `--delete-models`     | Also remove NemoClaw-pulled Ollama models                                          |
| `--destroy-user-data` | Also remove preserved user data (`rebuild-backups/`, `backups/`, `sandboxes.json`) |
| `--gateway <name>`    | Override the gateway name to remove (default: `nemo-deepagents`)                   |

```bash
nemo-deepagents uninstall [--yes] [--keep-openshell] [--delete-models] [--destroy-user-data] [--gateway <name>]
```

##### User-data preservation under `~/.nemoclaw/`

To avoid uninstall destroying host-side user data, uninstall preserves the following entries under `~/.nemoclaw/` by default:

| Entry              | What it holds                                                                                                                                                                            |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rebuild-backups/` | Host-side snapshots that `nemo-deepagents <name> snapshot create` and `nemo-deepagents backup-all` write. `nemo-deepagents <name> snapshot restore` reads them back after you reinstall. |
| `backups/`         | Host-side workspace backups that `scripts/backup-workspace.sh` writes. Refer to [Backup and Restore](../manage-sandboxes/backup-restore).                                                |
| `sandboxes.json`   | Host-side sandbox registry. NemoClaw uses it to map sandbox names back to their persistence directories when you reinstall.                                                              |

Uninstall removes every other entry under `~/.nemoclaw/` (gateway source, runtime state, the Ollama auth proxy PID file, etc.).

`--yes` deliberately remains non-destructive for user data.
It only acknowledges the global `Proceed?` confirmation prompt and still preserves the listed entries.
Removing the preserved entries always requires an explicit opt-in flag (`--destroy-user-data`) or the matching env var (`NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1`).
Existing automation using `--yes` therefore retains its safe behaviour and never loses host-side state by accident.

Decision matrix:

| Context                                                                   | Behaviour                                                                                                                                                                    |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Interactive TTY, preserved entries present, no env override               | Prompts `Also remove them? [y/N]`. Default `N` keeps the entries.                                                                                                            |
| Interactive TTY, user answers `y`                                         | Removes everything under `~/.nemoclaw/` (the previous full-removal behaviour).                                                                                               |
| Non-interactive (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or non-TTY shell) | Preserves the entries and prints a one-line notice.                                                                                                                          |
| `--destroy-user-data`                                                     | Skips the secondary user-data prompt and removes the preserved entries under `~/.nemoclaw/`. The global `Proceed?` confirmation still applies unless `--yes` is also passed. |
| `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1`                                  | Skips the secondary user-data prompt and removes the preserved entries. The global `Proceed?` confirmation still applies unless `--yes` is also passed.                      |

The preserved entries survive uninstall as inert files on disk.
Reinstall NemoClaw and re-onboard the sandbox before `nemo-deepagents <name> snapshot restore` can use them.

#### `nemo-deepagents uninstall` vs. the hosted `uninstall.sh`

Both forms execute the same `uninstall.sh` with the same flags, but differ in where the script comes from and how much they trust the network.
Use `nemo-deepagents uninstall` by default.
Use the hosted `curl … | bash` form only when the CLI is broken or already partially removed.

|                          | `nemo-deepagents uninstall`                                                       | `curl … \| bash` (Quickstart)                                                         |
| ------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Source of the script** | Local `uninstall.sh` shipped with the installed npm package.                      | Pulled live from `refs/heads/main` on GitHub.                                         |
| **Version pinning**      | Pinned to the version of NemoClaw you installed.                                  | Whatever is on `main` right now; may be newer than your installed CLI.                |
| **Network trust**        | No network fetch at uninstall time; runs a vetted local file via `bash`.          | Pipes a remote script straight to `bash` with no review step.                         |
| **Robustness**           | Requires the npm package to be discoverable so the CLI can find the local script. | Works even if the `nemo-deepagents` CLI is missing, broken, or partially uninstalled. |
| **Recommended for**      | Routine uninstalls.                                                               | Recovery when the CLI is unavailable.                                                 |

## Internal Commands

NemoClaw registers a hidden `internal` command namespace. These commands are
compatibility entrypoints for repo-owned scripts, such as the installer, the
uninstaller, DNS setup, and developer tooling. They are not part of the
supported public CLI surface.

Each command class sets `hidden = true`, so the commands stay out of
`nemo-deepagents --help`. They remain registered and routable, which is why they are
listed here for reference. Treat their names, flags, and output as
implementation details. They exist to back `install.sh`, `uninstall.sh`, and
related automation, and they may change or be removed without notice. Most run
indirectly through those scripts rather than being typed by hand.

For contributor guidance on how these command files are structured, refer to
`src/commands/internal/README.md`.

| Command                                                  | Owning script context                        | Purpose                                                                                        |
| -------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `nemo-deepagents internal installer plan`                | `install.sh`                                 | Build a deterministic installer plan from environment and probe inputs without applying it.    |
| `nemo-deepagents internal installer normalize-env`       | `install.sh`                                 | Normalize installer ref and provider environment values without applying installation changes. |
| `nemo-deepagents internal installer resolve-release-tag` | `install.sh`                                 | Resolve the installer ref using the same precedence as `install.sh`.                           |
| `nemo-deepagents internal uninstall plan`                | `uninstall.sh` / `nemo-deepagents uninstall` | Build a deterministic uninstall plan without applying it.                                      |
| `nemo-deepagents internal uninstall run-plan`            | `uninstall.sh` / `nemo-deepagents uninstall` | Remove host-side NemoClaw resources from a previously built plan.                              |
| `nemo-deepagents internal uninstall classify-shim`       | `uninstall.sh` / `nemo-deepagents uninstall` | Classify whether a shim path is safe for the uninstaller to remove.                            |
| `nemo-deepagents internal dns setup-proxy`               | onboarding / sandbox setup                   | Configure the DNS forwarder bridge inside a sandbox pod.                                       |
| `nemo-deepagents internal dns fix-coredns`               | onboarding / sandbox setup                   | Patch CoreDNS to use a non-loopback upstream resolver.                                         |
| `nemo-deepagents internal dev npm-link-or-shim`          | `scripts/npm-link-or-shim.sh` (development)  | Run `npm link`, falling back to a user-local NemoClaw development shim.                        |

These commands do not appear in the command-level parity check, which compares
`nemo-deepagents --help` against the public command headings in this reference; hidden
commands are excluded from both. The table above is the canonical reference for
the family.

## Environment Variables

NemoClaw reads the following environment variables to configure service ports, onboarding behavior, and lifecycle defaults.
Set them before running `nemo-deepagents onboard` or any command that starts services.
All ports must be non-privileged integers between 1024 and 65535.

| Variable                        | Default   | Service                                                                                                                                        |
| ------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEMOCLAW_GATEWAY_PORT`         | 8080      | OpenShell gateway port                                                                                                                         |
| `NEMOCLAW_GATEWAY_BIND_ADDRESS` | 127.0.0.1 | The OpenShell gateway uses this bind address; Docker-driver gateways on OpenShell 0.0.72 keep it on loopback while gateway JWT auth is active. |
| `NEMOCLAW_VLLM_PORT`            | 8000      | vLLM / NIM inference                                                                                                                           |
| `NEMOCLAW_OLLAMA_PORT`          | 11434     | Ollama inference                                                                                                                               |
| `NEMOCLAW_OLLAMA_PROXY_PORT`    | 11435     | Ollama auth proxy                                                                                                                              |

If a port value is not a valid integer or falls outside the allowed range, the CLI exits with an error.
`NEMOCLAW_GATEWAY_PORT` also cannot overlap configured service, vLLM, Ollama, or Ollama proxy ports, and cannot use reserved auto-allocation ranges or the default inference/proxy ports `8000`, `11434`, and `11435`.
When you run multiple NemoClaw gateways with different `NEMOCLAW_GATEWAY_PORT` values, NemoClaw derives a separate gateway name, state directory, and compatibility container name from the port so one gateway does not tear down another.
On non-WSL hosts, `NEMOCLAW_OLLAMA_PORT` and `NEMOCLAW_OLLAMA_PROXY_PORT` must be different.
If you run Ollama on port 11435, set `NEMOCLAW_OLLAMA_PROXY_PORT` to another free port before onboarding.

`NEMOCLAW_GATEWAY_BIND_ADDRESS` accepts only `127.0.0.1` and `0.0.0.0`, but Docker-driver gateways on OpenShell 0.0.72 reject `0.0.0.0` while gateway JWT auth is active.

```bash
export NEMOCLAW_DASHBOARD_PORT=19000
nemo-deepagents onboard
```

These overrides apply to onboarding, status checks, health probes, and the uninstaller.
Defaults are unchanged when no variable is set.

### Onboarding Configuration

The following variables let you tune onboarding without editing the Dockerfile or passing repeated flags.
Set them before running `nemo-deepagents onboard`.

| Variable                        | Format                                                                                                                                                                                                                                        | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NEMOCLAW_PROVIDER`             | provider key (e.g. `build`, `openai`, `anthropic`, `anthropicCompatible`, `gemini`, `ollama`, `custom`, `vllm`, `nim-local`, `routed`, `hermes-provider`, `install-vllm`, `install-ollama`, `install-windows-ollama`, `start-windows-ollama`) | Selects the inference provider during onboarding. The wizard skips the provider menu in both interactive and non-interactive runs when this is set. Aliases: `cloud` → `build`, `nim` → `nim-local`, `hermes` / `nous` / `nous-portal` → `hermes-provider`, `anthropiccompatible` → `anthropicCompatible`. Invalid values fail fast with the list of accepted keys.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `NEMOCLAW_TOOL_DISCLOSURE`      | `progressive` or `direct`                                                                                                                                                                                                                     | Selects progressive tool discovery or the prior direct-exposure behavior. Defaults to `progressive`; `--tool-disclosure` takes precedence when both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `NEMOCLAW_ENDPOINT_URL`         | URL                                                                                                                                                                                                                                           | Custom endpoint URL. Used together with `NEMOCLAW_PROVIDER=custom` for OpenAI-compatible endpoints or `NEMOCLAW_PROVIDER=anthropicCompatible` for Anthropic-compatible endpoints.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `NEMOCLAW_PREFERRED_API`        | `completions` (currently the only honored value)                                                                                                                                                                                              | Forces the validation probe to use the `/v1/chat/completions` API path instead of the newer `/v1/responses` API.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `NEMOCLAW_INFERENCE_INPUTS`     | comma-separated list of `text` and/or `image`                                                                                                                                                                                                 | Declares model input modalities for vision-capable models. Validated strictly; unknown tokens are ignored.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `NEMOCLAW_OLLAMA_REQUIRE_TOOLS` | `0` to disable, anything else to keep the default                                                                                                                                                                                             | When set to `0`, skips the Ollama tool-calling capability check during local-inference onboarding.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `NEMOCLAW_OLLAMA_INSTALL_MODE`  | `system`, `user`, or empty/unset                                                                                                                                                                                                              | Pins the Linux Ollama install location. Refer to the Linux Ollama install mode details below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `NEMOCLAW_PROXY_HOST`           | hostname or IP                                                                                                                                                                                                                                | Overrides the sandbox-side outbound HTTP proxy host. Defaults to `10.200.0.1`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `NEMOCLAW_PROXY_PORT`           | integer port                                                                                                                                                                                                                                  | Overrides the sandbox-side outbound HTTP proxy port. Defaults to `3128`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `NEMOCLAW_OPENSHELL_BIN`        | path                                                                                                                                                                                                                                          | Overrides the `openshell` binary the CLI invokes. Defaults to `openshell` (resolved via `PATH`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `NEMOCLAW_SANDBOX_NAME`         | sandbox name                                                                                                                                                                                                                                  | Preferred environment override for the default sandbox. Used by onboarding defaults and host-level commands such as `list`, `status`, `tunnel`, `services`, and `debug`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `NEMOCLAW_SANDBOX`              | sandbox name                                                                                                                                                                                                                                  | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `SANDBOX_NAME`                  | sandbox name                                                                                                                                                                                                                                  | Compatibility spelling used after `NEMOCLAW_SANDBOX_NAME` and `NEMOCLAW_SANDBOX`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `NEMOCLAW_INSTALL_REF`          | git ref                                                                                                                                                                                                                                       | For internal installer commands: the git ref to install from. Overridden by the `--install-ref` flag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `NEMOCLAW_INSTALL_TAG`          | release tag                                                                                                                                                                                                                                   | For internal installer commands: the release tag to install. Defaults to the admin-promoted `lkg` tag when unset. Overridden by the `--install-tag` flag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `NEMOCLAW_VLLM_MODEL`           | registry slug or Hugging Face model id                                                                                                                                                                                                        | Selects the model the managed-vLLM install path serves. Recognised slugs: `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `deepseek-v4-flash`, `deepseek-r1-distill-70b`. Unset uses the per-platform profile default. Gated models (e.g. `deepseek-r1-distill-70b`) require `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` | JSON array of non-blank strings                                                                                                                                                                                                               | Appends advanced operator-owned tokens to the managed `vllm serve` command after NemoClaw's registry defaults. Example: `["--max-num-seqs","2"]`. Malformed JSON, non-string tokens, or blank tokens fail before Docker work starts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `NEMOCLAW_MODEL_ROUTER_PYTHON`  | absolute path                                                                                                                                                                                                                                 | Pins the host Python interpreter used to create the Model Router virtual environment. Strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to another python. Relative command names such as `python3.12` are rejected. When unset, NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, retains every interpreter whose version is in `[3.10, 3.14)` and whose `ensurepip`, `pyexpat`, `ssl`, and `venv` stdlib modules import cleanly, and tries `python -m venv` on each in priority order until one succeeds. Set the pin when the auto-discovered interpreter is broken (for example, Homebrew `python@3.14` with a `pyexpat` dlopen mismatch on macOS). |

#### Linux Ollama install mode details

Set `NEMOCLAW_OLLAMA_INSTALL_MODE=system` to run the official `https://ollama.com/install.sh` installer, which uses sudo, writes to `/usr/local`, and configures systemd.
Set `NEMOCLAW_OLLAMA_INSTALL_MODE=user` to extract the release tarball to `${HOME}/.local` without sudo and launch the daemon manually without systemd persistence.
Leave `NEMOCLAW_OLLAMA_INSTALL_MODE` empty or unset to let NemoClaw auto-detect the mode.
Auto-detection selects `system` when the current user is root or passwordless `sudo` works.
Auto-detection selects `user` in non-interactive runs without passwordless `sudo`.
An interactive shell falls back to `system` so the official installer can prompt for the password.
NemoClaw rejects any other value.
On upgrades, NemoClaw rejects `user` because a user-local install cannot replace the system daemon on `:11434`.
On upgrades, NemoClaw also rejects `system` under `NEMOCLAW_NON_INTERACTIVE=1` when passwordless `sudo` is unavailable because the installer would hang on a hidden sudo prompt.
The run exits with an actionable diagnostic instead.

### Onboarding Behavior Flags

The following flags toggle optional behaviors during onboarding.
Set them before running `nemo-deepagents onboard`.

| Variable                                     | Format                                                                                                    | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEMOCLAW_YES`                               | `1` to enable                                                                                             | Auto-accepts confirmation prompts (`--yes` equivalent) including in helpers like the Ollama proxy auth setup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `NEMOCLAW_OLLAMA_NO_AUTOSTART`               | `1` to enable                                                                                             | Skips the wizard's eager Ollama auto-start during inference-provider selection (equivalent to passing `--no-ollama-autostart`). When set and Ollama is not running on `localhost:11434`, the `nemo-deepagents onboard` Local Ollama path prints a warning and selects the default fallback model instead of spawning `ollama serve`. The flag covers only the provider-selection step; later setup steps (auth proxy, validation, model warm) still expect a reachable Ollama. On Linux hosts with a systemd Ollama unit, the loopback-override path may still restart the daemon before this gate runs. |
| `NEMOCLAW_NON_INTERACTIVE_SUDO_MODE`         | `prompt` or empty/unset                                                                                   | When set to `prompt`, allows non-interactive onboarding to use prompt-capable `sudo` for host setup steps that require elevation, which can ask for a password. Empty/unset is the default and uses `sudo -n`, which fails instead of asking for a password. Any other value is rejected.                                                                                                                                                                                                                                                                                                                |
| `NEMOCLAW_NO_EXPRESS`                        | `1` to enable                                                                                             | Installer-only. Skips the DGX Spark, DGX Station, and Windows WSL express install prompt and continues with the normal interactive onboarding flow.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `NEMOCLAW_EXPERIMENTAL`                      | `1` to enable                                                                                             | Surfaces experimental providers and flows in onboarding.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `NEMOCLAW_IGNORE_RUNTIME_RESOURCES`          | `1` to enable                                                                                             | Suppresses the under-provisioned runtime warning during preflight. Use only when you know the sandbox host meets the minimums.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `NEMOCLAW_DISABLE_OVERLAY_FIX`               | `1` to enable                                                                                             | Skips the Docker overlay-fix step during sandbox build. For environments where the fix is incompatible.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `NEMOCLAW_OVERLAY_SNAPSHOTTER`               | snapshotter name                                                                                          | Selects the containerd overlay snapshotter for sandbox builds. Empty (default) preserves containerd's choice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `NEMOCLAW_CONFIG_ACCEPT_NEW_PATH`            | `1` to enable                                                                                             | Accepts a new sandbox config path without an interactive prompt when the stored path differs from the discovered one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `NEMOCLAW_RESOURCE_PROFILE`                  | profile name or `default`                                                                                 | Selects a sandbox CPU/RAM resource profile from the blueprint during onboarding. `default` means no resource preference, so NemoClaw passes no OpenShell CPU or memory flags. Unknown names fail fast.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `NEMOCLAW_CPU`                               | percentage or Kubernetes CPU quantity                                                                     | Overrides the selected profile's CPU size passed to OpenShell `--cpu`. Percentages resolve against detected capacity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `NEMOCLAW_RAM`                               | percentage or Kubernetes memory quantity                                                                  | Overrides the selected profile's memory size passed to OpenShell `--memory`. Percentages resolve against detected capacity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `NEMOCLAW_SANDBOX_GPU`                       | `auto`, `1`, or `0`                                                                                       | Controls sandbox GPU passthrough during onboarding. `auto` enables GPU passthrough when an NVIDIA GPU is detected, `1` requires GPU passthrough, and `0` forces CPU-only sandbox creation.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `NEMOCLAW_SANDBOX_GPU_DEVICE`                | OpenShell GPU device selector                                                                             | Selects the GPU device passed with `openshell sandbox create --gpu-device`. Requires explicit sandbox GPU enablement with `NEMOCLAW_SANDBOX_GPU=1` (or `--sandbox-gpu` for CLI-driven onboarding); otherwise onboarding rejects the selector instead of treating it as an implicit opt-in.                                                                                                                                                                                                                                                                                                               |
| `NEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH`        | `1`, `true`, `yes`, or `on` to enable                                                                     | Bypasses recorded sandbox base-image resolution metadata during onboarding, recreation, and rebuild. NemoClaw reruns candidate resolution but can still use a compatible image from Docker's local image store. This setting does not discard onboarding session state.                                                                                                                                                                                                                                                                                                                                  |
| `NEMOCLAW_SANDBOX_BASE_LOCAL_BUILD`          | unset or `auto` (default); `1`, `true`, `yes`, or `on` to enable; `0`, `false`, `no`, or `off` to disable | Controls whether base-image resolution may build a compatible image locally. The default allows builds during normal CLI runs and disables them when `NODE_ENV=test` or `VITEST=true`. When source inputs require a fresh build, disabling local builds makes resolution fail instead of using an unproven image.                                                                                                                                                                                                                                                                                        |
| `NEMOCLAW_DOCKER_GPU_PATCH`                  | unset, `auto`, `1`, or `0`                                                                                | Selects Linux Docker-driver GPU routing. Unset or `auto` uses native OpenShell GPU injection on ordinary native Linux and the compatibility patch on Docker Desktop WSL and Jetson/Tegra. `1` forces the compatibility patch. `0` selects native injection on ordinary native Linux and Jetson/Tegra, but Docker Desktop WSL ignores it. On Jetson/Tegra, use `0` only for troubleshooting because it bypasses the device-group propagation needed for CUDA.                                                                                                                                             |
| `NEMOCLAW_OPENSHELL_GATEWAY_CONTAINER_PATCH` | `1` to enable; disabled by default                                                                        | This setting explicitly opts into the Linux gateway compatibility container for an older host ABI or a diagnostic run; use it only on a trusted local host because it uses host networking and mounts the Docker socket read-only even though the socket still exposes the privileged Docker API; prefer OpenShell 0.0.72's directly supported glibc 2.28+ path; see the [OpenShell 0.0.72 compatibility review](/user-guide/openclaw/security/openshell-0.0.72-compatibility-review#source-of-truth-boundaries) for details.                                                                            |
| `NEMOCLAW_OPENSHELL_GATEWAY_BIN`             | path                                                                                                      | Advanced override for the `openshell-gateway` binary used by the Linux Docker-driver standalone fallback. Defaults to the binary next to `openshell`, then common install paths.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `NEMOCLAW_OPENSHELL_SANDBOX_BIN`             | path                                                                                                      | Advanced override for the `openshell-sandbox` binary used by the Linux Docker-driver standalone fallback. Defaults to the binary next to `openshell`, then common install paths.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR`       | path                                                                                                      | Advanced override for the Linux Docker-driver gateway SQLite state directory and standalone-fallback PID file. Defaults to `~/.local/state/nemoclaw/openshell-docker-gateway`.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `NEMOCLAW_AUTO_FIX_FIREWALL`                 | `1` to enable                                                                                             | Opts in to automatic UFW remediation when Linux Docker-driver sandbox containers cannot reach the host gateway after a proven TCP failure. NemoClaw runs `sudo -n` only, validates the narrow Docker bridge subnet → gateway IP:port rule before invoking UFW, re-probes after applying it, and otherwise falls back to the printed manual command.                                                                                                                                                                                                                                                      |

### Onboard Profiling Traces

Set `NEMOCLAW_TRACE=1` before `nemo-deepagents onboard` to write an OpenTelemetry-style JSON trace for the run.
When no explicit path is provided, NemoClaw writes a timestamped file under `.e2e/traces/` in the current working directory.
Use `NEMOCLAW_TRACE_DIR` to choose the output directory, or `NEMOCLAW_TRACE_FILE` to choose the exact output file.

```bash
NEMOCLAW_TRACE=1 nemo-deepagents onboard
NEMOCLAW_TRACE_DIR=/tmp/nemoclaw-traces nemo-deepagents onboard
NEMOCLAW_TRACE_FILE=/tmp/nemoclaw-onboard-trace.json nemo-deepagents onboard
```

Trace artifacts include onboard phase timing, sandbox and service readiness waits, policy application, inference validation probes, curl probe results, and sandbox build progress events.
Secret-like metadata such as API keys, bearer tokens, cookies, and credentials is redacted before the file is written.

### Deep Agents Code OTLP Traces

Pass `--observability` during Deep Agents onboarding to enable backend-neutral runtime traces for Deep Agents Code.
This feature is separate from `NEMOCLAW_TRACE`, which records NemoClaw onboarding phases, and from the OpenClaw diagnostics plugin.

The sandbox sends OTLP/HTTP protobuf requests only to `http://host.openshell.internal:4318/v1/traces`.
The managed exporter uses standard OTLP transport headers but does not accept operator-supplied custom or authentication headers.
A host operator must run the receiver on port `4318` and configure any Jaeger, Phoenix, LangSmith, or other backend exporter on the collector side.
Changing the host collector's exporter does not require a sandbox rebuild or policy change.
Collector and exporter failures are non-fatal to agent work.

Native LangSmith tracing and ambient OTLP configuration remain disabled in the sandbox.
The explicit opt-in can export bounded prompts, responses, tool arguments, tool results, and operational metadata, so operators must treat trace payloads as sensitive application data.
The collector must enforce the operator's filtering and redaction requirements before remote forwarding because the local policy applies to the managed Python interpreter and does not provide authenticated tenant identity.
For the complete receiver contract and a runnable LangSmith collector setup, refer to [Quickstart with LangChain Deep Agents Code](/user-guide/deepagents/get-started/quickstart#export-traces-through-a-local-collector).

### Probe Timeouts

The following variables tune how long internal probes wait before giving up.
Defaults are sized for typical hardware; override only if you see false-positive timeouts.

| Variable                                     | Default                           | Effect                                                                                                                                                                                                      |
| -------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEMOCLAW_MCP_PROVIDER_SYNC_TIMEOUT_SECONDS` | `30`                              | Maximum time to wait for an OpenShell MCP provider credential revision to become active or fully revoked inside the sandbox. Integer seconds; raise only when provider synchronization is unusually slow.   |
| `NEMOCLAW_SANDBOX_EXEC_TIMEOUT_MS`           | per call site (typically `15000`) | Overrides the default timeout for `openshell sandbox exec` calls issued by recovery and lifecycle helpers. Integer milliseconds; non-positive or non-numeric values fall back to the per-call-site default. |
| `NEMOCLAW_STATUS_PROBE_TIMEOUT_MS`           | built-in default                  | Overrides the timeout for the OpenShell status probe used by `nemo-deepagents <name> status`. Integer milliseconds; non-positive or non-numeric values fall back to the default.                            |

### Onboard Timeouts

The following environment variables tune onboard-time wall-clock limits.
Set them before running `nemo-deepagents onboard` if a slow connection or large model pull risks tripping the default.

| Variable                                | Default             | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEMOCLAW_OLLAMA_PULL_TIMEOUT`          | `1800` (30 minutes) | Wall-clock timeout for `ollama pull` during onboard, in seconds. Accepts integer or float values. Already-downloaded layers are kept; re-running the pull resumes them.                                                                                                                                                                                                                                                                        |
| `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT`      | `180`               | Wall-clock timeout for the inference-server validation probe during onboard, in seconds. Raise on slow networks or for very large prompts.                                                                                                                                                                                                                                                                                                     |
| `NEMOCLAW_SANDBOX_READY_TIMEOUT`        | `180`               | Wall-clock timeout for the post-create readiness wait, in seconds. Raise when the sandbox image build, gateway upload, or in-sandbox boot exceeds the default (typical on 70B+ models, first-time gateway uploads over slow links, or DGX Station / remote-VM first runs). When the deadline expires onboarding deletes the orphaned sandbox and prints the retry hint.                                                                        |
| `NEMOCLAW_SANDBOX_READY_ERROR_DEBOUNCE` | `30`                | Consecutive `Error`-phase polls (2s apart, so \~60s by default) the post-create readiness wait tolerates before treating `Error` as terminal. The gateway can briefly report a just-created sandbox in `Error` while it re-registers the sandbox (seen on DGX Spark); the debounce lets that transient recover to `Ready`. `Failed` and `CrashLoopBackOff` always fail immediately. Set to `1` to restore fast-fail on the first `Error` poll. |

```bash
export NEMOCLAW_OLLAMA_PULL_TIMEOUT=3600
export NEMOCLAW_SANDBOX_READY_TIMEOUT=600
nemo-deepagents onboard
```

If a timeout fires, onboarding emits the elapsed budget plus a hint to raise the relevant variable.
The Ollama pull preserves its partial download for the next attempt.
The readiness wait deletes the orphaned sandbox first so the next `nemo-deepagents onboard` starts clean.

### Lifecycle Behavior Flags

The following flags change defaults for commands that manage existing sandboxes.

| Variable                                   | Format                                                            | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEMOCLAW_CLEANUP_GATEWAY`                 | `1`, `true`, or `yes` to enable; `0`, `false`, or `no` to disable | Sets the default for whether `nemo-deepagents <name> destroy` removes the shared gateway when destroying the last sandbox. Command-line `--cleanup-gateway` and `--no-cleanup-gateway` still take precedence.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `NEMOCLAW_CONFIRM_LEGACY_MANAGED_RECREATE` | Exact JSON array of sandbox names                                 | Confirms to the installer that the exact listed set of pre-fingerprint OpenClaw or Hermes sandboxes used NemoClaw-managed images, allowing recovery onto the current managed image. The normalized names must exactly match the installer's printed array. Set it only after verifying every named sandbox. Recorded custom-image evidence remains blocked.                                                                                                                                                                                                                                                                              |
| `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR`  | `1` to enable                                                     | Skips the automatic DNS-proxy repair for stale `inference.local` routes during `nemo-deepagents <name> connect` and `nemo-deepagents <name> connect --probe-only`. Use only as a troubleshooting escape hatch.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `NEMOCLAW_SHIELDS_ACCEPT_LEGACY_BASELINE`  | `1` to opt in                                                     | Allows advanced immutable-config verification to trust the current on-disk bytes for older or partial content baselines. Use only after you have rebuilt or manually inspected the sandbox state and accepted that the baseline is operator-approved.                                                                                                                                                                                                                                                                                                                                                                                    |
| `NEMOCLAW_SHIELDS_SETTLE_MS`               | milliseconds (default `750`, clamped to `0` to `10000`)           | Settle window NemoClaw waits after re-applying a config lockdown (during shields auto-restore and `nemo-deepagents <name> shields up` drift remediation) before re-confirming the lock still holds. Detects when an in-sandbox reconciler changes config file permissions after lockdown and re-applies the lock; if NemoClaw cannot re-confirm the lock within the retry budget, shields stay down. This narrows the window in which a reconciler can revert permissions rather than eliminating it. The best-effort `chattr +i` immutable bit remains the only fully durable lock. Raise it on hosts where the gateway settles slowly. |
| `NEMOCLAW_SKIP_UNREACHABLE_SANDBOX_BACKUP` | Exactly `1` to opt in (`true`, `yes`, `0` are not accepted)       | Applies to standalone `nemo-deepagents backup-all` runs. Skips running sandboxes whose in-sandbox SSH endpoint does not answer. It does not relax the installer's strict pre-upgrade backup, which still aborts if any registered sandbox is skipped or fails. Any uncommitted state since the last successful backup is not included in the skipped backup.                                                                                                                                                                                                                                                                             |
| `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA`     | `1` to opt in                                                     | Acknowledges data loss during `nemo-deepagents uninstall` and removes the otherwise-preserved entries (`rebuild-backups/`, `backups/`, `sandboxes.json`) under `~/.nemoclaw/`. Equivalent to passing the `--destroy-user-data` flag; the global `Proceed?` confirmation still applies unless `--yes` is also passed.                                                                                                                                                                                                                                                                                                                     |

### Legacy `nemo-deepagents setup`

Deprecated. Use `nemo-deepagents onboard` instead.
Running `nemo-deepagents setup` now delegates directly to `nemo-deepagents onboard`.

```bash
nemo-deepagents setup
```