NemoClaw CLI Commands Reference
The nemoclaw CLI is the primary interface for managing NemoClaw sandboxes.
It is installed automatically by the installer (curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash).
For guidance on when to use nemoclaw versus the underlying openshell CLI, refer to CLI Selection Guide.
Agent Selection
Use nemoclaw for the OpenClaw variant.
OpenClaw is the default agent for nemoclaw onboard unless you pass --agent hermes or set NEMOCLAW_AGENT=hermes.
OpenClaw-specific sections below describe the /nemoclaw slash command, the OpenClaw dashboard URL, the OpenClaw gateway token, and OpenClaw config paths under /sandbox/.openclaw.
In-Sandbox Commands
The /nemoclaw slash command is available inside the OpenClaw chat interface for quick actions:
Use host-side nemoclaw <sandbox> shields status|up|down commands to inspect or change shields posture.
Standalone Host Commands
The CLI handles host-side operations that run outside the selected agent runtime.
nemoclaw help, nemoclaw --help, nemoclaw -h
Show the top-level usage summary and command groups.
Running nemoclaw with no arguments shows the same help output.
nemoclaw --version, nemoclaw -v
Print the installed NemoClaw CLI version.
nemoclaw completion
Generate a tab-completion script for Bash, Zsh, or Fish from the commands and flags available in the installed CLI.
The script completes public global commands, the sandbox-first nemoclaw <name> ... grammar, flags, shell choices, and locally registered sandbox names.
If you omit the shell name, nemoclaw completion detects the target from $SHELL and defaults to Bash when it cannot identify Zsh or Fish.
The generated script is bound to the CLI name that created it, so install a separate script for each CLI alias you use.
It loads sandbox names from the local registry the first time completion runs and caches them for the rest of that shell session.
For Bash, source the generated script and add the same line to ~/.bashrc for future sessions.
For Zsh, source the generated script and add the same line to ~/.zshrc for future sessions.
For Fish, write the generated script to Fish’s completions directory.
Start a new shell session to refresh the cached sandbox names after creating or removing a sandbox.
nemoclaw resources
Display host hardware inventory and configured sandbox resource profiles.
Use --json for machine-readable CPU, memory, GPU, Kubernetes allocatable-capacity, and profile data.
If the gateway is not running, Kubernetes allocatable fields are omitted and host CPU/RAM totals are still shown.
nemoclaw agents list
List the installed agent runtimes that can be selected with nemoclaw onboard --agent <name>.
Use this global command when you need valid runtime names before creating or recreating a sandbox.
It lists runtime names with the descriptions from their installed manifests.
Expected output:
nemoclaw onboard
Run the interactive setup wizard (recommended for new installs). The wizard creates an OpenShell gateway, registers inference providers, builds the sandbox image, and creates the sandbox. Use this command for new installs and for recreating a sandbox after changes to policy or configuration.
--agent accepts the canonical manifest names from nemoclaw agents list plus common aliases.
For example, nemohermes resolves to hermes, while dcode, deepagents, deepagents-code, and langchain resolve to langchain-deepagents-code.
--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.
OpenClaw sessions also record the web search selection, messaging selection and non-secret settings, and resource profile. When the saved session includes prompt checkpoints, resume skips each completed group and continues at the first incomplete choice. Legacy sessions without those checkpoints may repeat choices whose completion cannot be proven. Raw web search and messaging credentials are never written to the onboarding session. Resume skips their secret prompts when the same session recorded a successful OpenShell provider registration and OpenShell still reports the exact expected name, type, and credential keys. If the session lacks that registration receipt, the provider is missing, or its binding does not match, interactive resume requests the credential again; non-interactive resume preserves the completed choice, reports the required environment variable, and exits so you can export it before retrying.
Completed onboarding sessions are not resumable.
Use --resume only for resumable interrupted or failed sessions, not to change provider, model, agent, or sandbox recreation settings after onboarding has completed.
During resume, NemoClaw reruns preflight, gateway, provider, and sandbox repair checks even when the saved session has already reached a later nonterminal onboarding phase.
If the recorded session conflicts with flags you pass on the recovery run, NemoClaw exits and tells you to either rerun with the original settings or start over.
Use --fresh to discard the saved onboarding session and start the wizard from the beginning.
This clears stale or failed session state before NemoClaw creates a new session record.
It also bypasses locally recorded sandbox base-image resolution metadata and reruns normal candidate resolution.
--fresh takes precedence over a base-image hint carried from a rebuild, so NemoClaw does not use that recorded hint.
The installer also accepts --fresh and forwards it to nemoclaw onboard, which skips automatic resume detection.
--resume and --fresh are mutually exclusive.
For an existing completed sandbox, use --fresh --name <sandbox-name> --recreate-sandbox when you intentionally want onboarding to replace that sandbox with a new provider, model, agent, or build-time setting.
Use nemoclaw <sandbox-name> rebuild when you want NemoClaw to recreate the sandbox from its recorded registry metadata without changing those selections.
--tool-disclosure <progressive|direct>
Choose how the selected agent presents its session-authorized tools to the model.
progressive is the default: OpenClaw and Hermes use their native Tool Search implementations, while Deep Agents Code initially shows its core tools plus search_tools after at least one MCP tool loads successfully.
direct restores the previous behavior and presents all registered tools directly.
This setting changes model context only; it does not bypass OpenShell policy, credentials, approvals, hooks, or sandbox controls.
The flag takes precedence over NEMOCLAW_TOOL_DISCLOSURE.
A new sandbox defaults to progressive when neither is set.
NemoClaw records the selected value with the onboarding session and sandbox so rebuilds preserve it and ambient shell variables cannot silently change an internal rebuild.
Model-specific compatibility safeguards may downgrade a selected progressive mode to direct exposure for that model without changing the recorded preference.
To change an existing sandbox, recreate it explicitly:
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.
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:
Base-image selection follows this precedence:
--freshorNEMOCLAW_SANDBOX_BASE_IMAGE_REFRESH=1bypasses recorded metadata and reruns normal candidate resolution. These controls are equivalent for base-image selection.- Without a bypass, NemoClaw validates and reuses the recorded hint when possible.
- When the hint is absent or no longer valid, NemoClaw performs normal resolution.
After a cache miss, source checkouts require a fresh local build before candidate selection when base-image inputs have dirty or staged changes, or Git cannot inspect the worktree safely.
For a clean release checkout or versioned install, NemoClaw first accepts the exact release-version image.
If that tag exists locally but fails compatibility validation, NemoClaw refreshes the same tag from the registry once and validates it again.
If the release-version image is missing or still incompatible, NemoClaw builds a compatible local base instead of falling back to mutable :latest.
For unversioned development checkouts, NemoClaw tries the image tagged with the newest reachable release version from origin before source-commit images, and only uses :latest when no version tag is discoverable.
When a stable tag and a prerelease tag share the same version, NemoClaw prefers the stable tag.
If origin tag lookup is unavailable, NemoClaw uses the newest reachable local release tag as a fallback.
If that nearest release-version image is missing or incompatible, NemoClaw builds a compatible local base instead of falling back to mutable :latest.
The required-build path does not reuse an older local tag.
If local builds are disabled or the build fails, resolution stops instead of selecting a stale image.
When the OpenShell sandbox ABI is required, NemoClaw also rejects a built image that does not report a compatible glibc version.
Explicit base-image overrides are exact: NemoClaw validates the requested ref and fails closed when it cannot be pulled or does not satisfy required ABI, agent runtime, or dependency checks.
Otherwise, normal resolution checks compatible images in Docker’s local image store before attempting to pull a missing published candidate.
For warm-hint reuse and unversioned development resolution, NemoClaw can reuse another validated local fallback when published candidates are unavailable or incompatible.
When the OpenShell sandbox ABI is required, that local fallback must be ABI-compatible.
An offline warm recreate or rebuild can therefore continue when the recorded image or another compatible candidate is available locally.
When source inputs require a fresh local build, NemoClaw fails the operation if that build cannot be produced and validated instead of substituting an older local tag.
When the OpenShell sandbox ABI is required, resolution also fails if no ABI-compatible image can be resolved instead of falling back to an unvalidated cached :latest image.
Bypassing the recorded hint does not clear Docker’s local image store or require a network pull.
Only --fresh also discards the saved onboarding session; the refresh environment variable affects base-image selection only.
For NemoClaw-managed environments, use nemoclaw onboard when you need to create or recreate the OpenShell gateway or sandbox.
Avoid openshell self-update, npm update -g openshell, openshell gateway start --recreate, or openshell sandbox create directly unless you intend to manage OpenShell separately and then rerun nemoclaw onboard.
Use --fresh to ignore any saved onboarding session and restart the wizard from scratch. This is useful after an interrupted nemoclaw onboard run when you want to discard saved state instead of continuing it with --resume.
The installer detects existing sandbox sessions before onboarding and prints a warning if any are found.
To make the installer abort instead of continuing, set NEMOCLAW_SINGLE_SESSION=1:
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 an installed gateway whose OpenShell version is outside the current release’s supported range, install the supported OpenShell release, and recover the existing sandboxes.
The installer reads that supported range from the prepared current source and stops without retiring the gateway if the installed version is unknown or the range is missing or invalid.
When the installed OpenShell version is already supported, the installer keeps the running gateway through the host update.
If an out-of-range gateway cannot be retired through a supported lifecycle command or the verified NemoClaw-owned gateway PID, the installer stops after backup with the sandbox backups preserved.
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, OpenRouter, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints.
Credentials are registered with the OpenShell gateway and never persisted to host disk.
Refer to Credential Storage for details on inspection, rotation, and migration from earlier releases.
The legacy nemoclaw setup command is deprecated; use nemoclaw 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 and messaging channels, builds and starts the sandbox, and asks for a policy tier that controls the default set of network policy presets applied to the sandbox. Three tiers are available:
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. 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):
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 nemoclaw <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.
OpenClaw onboarding supports Brave Search and Tavily Search.
NemoClaw registers a sandbox-scoped OpenShell provider and keeps openclaw.json on an OpenShell credential placeholder.
At egress, OpenShell rewrites Brave’s X-Subscription-Token header with BRAVE_API_KEY or Tavily’s Authorization header with TAVILY_API_KEY.
Treat web search as an explicit opt-in and use a dedicated low-privilege key.
For non-interactive onboarding, you must explicitly accept the third-party software notice:
or:
For scripted installer runs, pass explicit acceptance to the bash side of the installer pipe:
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.
To enable Tavily Search in non-interactive mode, set the provider and matching key.
Use NEMOCLAW_WEB_SEARCH_PROVIDER=brave with BRAVE_API_KEY for Brave Search, or set the provider to none to disable web search explicitly.
When the provider selector is unset, NemoClaw chooses Brave Search when BRAVE_API_KEY is available, then Tavily Search when only TAVILY_API_KEY is available.
Brave Search wins when both keys are available to preserve the historical non-interactive behavior.
An explicit provider with no matching key exits before sandbox creation.
A provider key that fails validation prints a warning, disables web search for that run, and lets the rest of onboarding continue.
After fixing the key, rerun onboarding so NemoClaw can validate it, register the selected provider, and apply the matching policy preset.
Changing or disabling the selected provider recreates the sandbox because the plugin configuration and credential attachment are part of the image.
Accept the recreate prompt or pass --recreate-sandbox.
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 nemoclaw onboard --help output lists installed runtime names inline, and nemoclaw agents list shows the same runtimes with manifest descriptions.
Use --agents <agents.yaml> to declare secondary OpenClaw agents, agents.defaults, and main-agent overrides in a checked-in manifest that NemoClaw bakes into the sandbox image at build time.
Refer to Declarative Multi-Agent Manifest for the schema and OpenClaw-native sub-agent field semantics.
Use --control-ui-port <N> to choose the host dashboard port for a sandbox.
The value must be an integer from 1024 through 65535.
This flag takes precedence over CHAT_UI_URL, NEMOCLAW_DASHBOARD_PORT, the previous registry value, and the default port.
For Hermes sandboxes, do not use port 8642; NemoClaw reserves it for the Hermes OpenAI-compatible API and rejects it as a dashboard port before sandbox creation.
If you enable Slack during onboarding, the wizard collects both the Bot Token (SLACK_BOT_TOKEN) and the App-Level Token (SLACK_APP_TOKEN).
Socket Mode requires both tokens.
The app-level token is stored in a dedicated slack-app OpenShell provider and forwarded to the sandbox alongside the bot token.
The wizard also accepts optional SLACK_ALLOWED_USERS and SLACK_ALLOWED_CHANNELS values so you can restrict Slack DMs, channel @mention users, and channel IDs before the sandbox image is built.
If you enable Discord during onboarding, the wizard can also prompt for a Discord Server ID, whether the bot should reply only to @mentions or to all messages in that server, and an optional Discord User ID.
NemoClaw bakes those values into the sandbox image as Discord guild workspace config so the bot can respond in the selected server, not just in DMs.
If you leave the Discord User ID blank, the guild config omits the user allowlist and any member of the configured server can message the bot.
Guild responses remain mention-gated by default unless you opt into all-message replies.
If DISCORD_SERVER_ID is set and DISCORD_REQUIRE_MENTION is unset, NemoClaw records the existing mention-only default (DISCORD_REQUIRE_MENTION=1).
If you enable Telegram during onboarding, the wizard can also prompt for whether group chats should reply only to @mentions or to all group messages.
Mention-only group replies are the default.
Set TELEGRAM_REQUIRE_MENTION=0 for non-interactive onboarding when you want all group messages to trigger replies.
For OpenClaw, Telegram group access defaults to TELEGRAM_GROUP_POLICY=open; set TELEGRAM_GROUP_POLICY=allowlist or TELEGRAM_GROUP_POLICY=disabled before non-interactive onboarding when you want stricter group access.
Hermes does not have an equivalent disable-groups policy; TELEGRAM_ALLOWED_IDS maps to Hermes TELEGRAM_ALLOWED_USERS, which authorizes those users across DMs, groups, and forums.
Pairing and TELEGRAM_ALLOWED_IDS still govern direct messages.
If you cancel a brand-new onboarding run at the policy preset step, NemoClaw rolls back the sandbox, registry entry, and onboarding session instead of leaving a default sandbox with unfinished policy state. Existing live sandboxes are not deleted by this cancel rollback path.
If you run onboarding again with the same sandbox name and choose a different inference provider or model, NemoClaw detects the drift and recreates the sandbox so the running agent config matches your selection.
In interactive mode, the wizard asks for confirmation before delete and recreate.
In non-interactive mode, NemoClaw recreates automatically when the stored selection is readable and differs.
For managed Deep Agents Code sandboxes, NemoClaw also recreates when the live dcode identity selection is unreadable; other agent paths continue to reuse by default when their stored selection cannot be read.
Set NEMOCLAW_RECREATE_SANDBOX=1 to force recreation even when no drift is detected.
Before deleting an existing sandbox during recreation, NemoClaw backs up the workspace state declared by the selected agent profile and restores it into the new sandbox once it is live.
This applies whether the existing sandbox is ready or marked not-ready, so cross-version upgrades that pass NEMOCLAW_RECREATE_SANDBOX=1 no longer drop user files from the selected agent workspace.
The behaviour matches nemoclaw <name> rebuild --force.
NemoClaw aborts the recreate when the backup cannot complete in full, including when individual state directories or files fail mid-backup, so failed entries are not silently dropped on delete.
Set NEMOCLAW_RECREATE_WITHOUT_BACKUP=1 to skip the pre-recreate backup.
The destination sandbox starts with a fresh workspace.
For OpenClaw, the backed-up paths include agents, extensions, workspace, skills, hooks, identity, devices, canvas, cron, memory, telegram, wechat, credentials, and /sandbox/.openclaw/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 nemoclaw 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 supplied Dockerfile defines the complete sandbox image, and NemoClaw does not layer it on top of the stock managed runtime.
The entire parent directory of the specified file is used as the Docker build context, so any files your Dockerfile references (scripts, config, etc.) must live alongside it.
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.
The Dockerfile path must exist. Missing paths fail during command parsing before preflight, gateway setup, inference setup, or sandbox creation starts.
If deployment verification cannot reach the gateway for a custom OpenClaw image, NemoClaw checks for /tmp/gateway.log, /usr/local/bin/nemoclaw-start, and /sandbox/.openclaw/openclaw.json.
When all three paths are absent, onboarding reports that the custom image lacks the managed runtime instead of treating repeated port-forward retries as the recovery path.
For the version-matched full-runtime plugin workflow, refer to Install OpenClaw Plugins.
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:
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.
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:
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.
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.
The flag wins over NEMOCLAW_SANDBOX_NAME.
When prompting is possible, NEMOCLAW_SANDBOX_NAME fills the interactive default so you can press Enter to accept it.
When prompting is impossible (no TTY or --non-interactive), the env var is also honoured so existing CI scripts keep working.
Combining --from <Dockerfile> with non-interactive onboarding requires one of --name or NEMOCLAW_SANDBOX_NAME; otherwise onboarding exits rather than silently defaulting to my-assistant and clobbering the default sandbox.
nemoclaw onboard --from
Use a custom Dockerfile for the sandbox image.
This variant of nemoclaw onboard accepts a --from <Dockerfile> argument to build the sandbox from a user-supplied Dockerfile instead of the default NemoClaw image.
The user-supplied context uses the OpenShell gateway builder instead of NemoClaw’s host-side local BuildKit prebuild.
GPU passthrough
When nemoclaw onboard detects an NVIDIA GPU on the host, it enables OpenShell GPU passthrough at both the gateway and sandbox level by default.
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, NemoClaw uses native OpenShell GPU injection by default and never broadens confinement automatically.
Set NEMOCLAW_DOCKER_GPU_PATCH=fallback to explicitly authorize one native attempt followed by one compatibility retry.
NemoClaw permits the retry only after it confirms either a trusted host-side GPU routing failure or an explicit driver proof plus exact-container host configuration showing that no GPU was attached.
It then saves redacted diagnostics and removes the incomplete sandbox before retrying.
Sandbox-reported CUDA output alone never authorizes the broader compatibility envelope, even when the operator enabled fallback.
That case fails closed and points to the explicit NEMOCLAW_DOCKER_GPU_PATCH=1 compatibility-only control.
NemoClaw retries only after it verifies that no OpenShell-managed Docker container labeled for that sandbox remains; if cleanup cannot be proven safe, onboarding stops and prints cleanup guidance instead.
On Docker Desktop WSL and Jetson/Tegra, automatic GPU onboarding uses the compatibility path directly.
On ordinary native Linux, the compatibility path uses an available NVIDIA CDI spec before falling back to Docker --gpus all or the NVIDIA runtime.
On Docker Desktop WSL, the compatibility path skips CDI and tries Docker --gpus all before the NVIDIA runtime.
On Jetson/Tegra hosts, the compatibility path uses the NVIDIA runtime and adds the host group IDs that own /dev/nvmap and /dev/nvhost-* so the sandbox user can initialize CUDA.
If the compatibility attempt fails, onboarding keeps its diagnostics and the failed sandbox in place and prints a manual cleanup command.
Prerequisites:
- Ensure NVIDIA GPU drivers are installed and working.
- On generic NVIDIA hosts,
nvidia-smimust succeed. - On Jetson/Tegra hosts shipping without
nvidia-smi, the devicetree firmware fallback substitutes.
- On generic NVIDIA hosts,
- NVIDIA Container Toolkit configured for Docker.
When GPU passthrough is enabled and a gateway already exists without it, onboarding first checks whether replacing the CPU-only gateway is safe.
If no other registered sandbox depends on that gateway, or if --recreate-sandbox is recreating the only registered sandbox with the same name, onboarding cleans up the stale gateway and continues.
If other sandboxes depend on the gateway or Docker state is unclear, onboarding exits without cleanup and prints targeted destroy or gateway-removal guidance.
To add GPU to an existing sandbox, rerun with --recreate-sandbox.
Leave NEMOCLAW_DOCKER_GPU_PATCH unset or set it to auto for native-only GPU onboarding on ordinary native Linux.
Set NEMOCLAW_DOCKER_GPU_PATCH=fallback to explicitly opt into one bounded native-to-compatibility retry on ordinary native Linux.
Set NEMOCLAW_DOCKER_GPU_PATCH=0 to require native OpenShell GPU injection on ordinary native Linux or Jetson/Tegra.
Set NEMOCLAW_DOCKER_GPU_PATCH=1 to use only the compatibility path on ordinary native Linux.
Other legacy nonzero values keep that behavior through the v0.0.x release line and will be removed in v0.1.0.
Use NEMOCLAW_DOCKER_GPU_PATCH=0 on Jetson/Tegra only for troubleshooting because it bypasses Tegra device-group propagation and CUDA may not initialize.
Docker Desktop WSL ignores NEMOCLAW_DOCKER_GPU_PATCH=0 because GPU passthrough on that runtime requires the compatibility patch.
Use --no-sandbox-gpu, --no-gpu, or NEMOCLAW_SANDBOX_GPU=0 when you want to disable sandbox GPU passthrough on Docker Desktop WSL.
nemoclaw list
List all registered sandboxes with their model, provider, and policy presets.
Pass --json for machine-readable output that includes a schemaVersion, the default sandbox, recovery metadata, and the sandbox inventory.
Sandboxes with an active SSH session are marked with a ● indicator so you can tell at a glance which sandbox you are already connected to in another terminal.
When a sandbox has a recorded dashboard port, the output includes its local dashboard URL.
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.
nemoclaw use <name>
Promote a registered sandbox to the default.
This is the first-class replacement for hand-editing ~/.nemoclaw/sandboxes.json; it updates the registry through the same atomic, lock-guarded path that nemoclaw onboard uses for the initial default.
Subsequent commands and the NEMOCLAW_SANDBOX_NAME resolution order then pick up the new default automatically.
Pass --json to receive a machine-readable result indicating whether the registry was updated, the sandbox was already the default, or the name is unknown.
nemoclaw use is a thin selector and never mutates the sandbox itself.
It fails with a non-zero exit and a known-sandbox list when the requested name is not registered, so scripts can branch safely on the outcome.
nemoclaw deploy
The nemoclaw deploy command is deprecated.
Prefer provisioning the remote host separately, then running the standard NemoClaw installer and nemoclaw onboard on that host.
Deploy NemoClaw to a remote GPU instance through Brev.
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.
nemoclaw <name> connect
Connect to a sandbox by name.
Bare nemoclaw connect (no sandbox name) connects to the registry default.
NemoClaw uses the stored default when it names a non-pending registered sandbox, then falls back to the first non-pending registration.
If only pending registrations remain, the command exits non-zero and tells you to wait for onboarding or remove the incomplete sandbox.
If the registry remains empty after recovery, it tells you to run nemoclaw onboard.
A registered sandbox literally named connect keeps the name-first reading.
If the sandbox is not yet in the Ready phase, connect polls openshell sandbox list every few seconds and prints the current phase. This gives you progress output right after onboarding, when the 2.4 GB image is still pulling, instead of a silent hang.
Control the wait budget with NEMOCLAW_CONNECT_TIMEOUT (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 nemoclaw <name> rebuild hint.
If another terminal is already connected to the sandbox, connect prints a note with the number of existing sessions before proceeding. Multiple concurrent sessions are allowed.
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.
Before reading or changing the live OpenShell gateway inference route, connect verifies the shared provider and sandbox metadata.
When the live route differs and the metadata is compatible, connect warns and re-points the route to the target sandbox’s recorded provider and model.
Refer to Use Shared Gateway Routes for provider-global identity, route drift, and hard-error recovery.
Use nemoclaw inference set --provider <provider> --model <model> to make an intentional compatible route change outside the connect flow.
Before it opens SSH, connect probes https://inference.local/v1/models from inside the sandbox with the selected agent’s trusted CA and proxy context.
HTTP 200 through 499 confirms that the route is reachable.
When the probe returns a recognized broken result, connect attempts DNS or route repair and verifies the route again.
When the initial probe cannot return a trusted result, connect fails closed before health-driven repair and before opening SSH.
It prints a bounded, redacted last-probe detail and points you to nemoclaw <name> doctor.
If the sandbox is registered locally but missing from a healthy gateway, connect preserves the registry entry and points you to rebuild --yes, onboard, or destroy instead of deleting the metadata needed for recovery.
After a host reboot, the OpenShell gateway rotates its SSH host keys.
connect detects the resulting identity drift, prunes stale openshell-* entries from ~/.ssh/known_hosts, and retries automatically.
You no longer need to re-run nemoclaw onboard after a reboot in this case.
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.
nemoclaw <name> exec
Run a single command non-interactively in a running sandbox via the OpenShell exec endpoint.
The command runs as the sandbox user with HOME=/sandbox, so in-sandbox tooling resolves NemoClaw-provisioned config the same way it does for connect and openshell sandbox connect.
This is the supported substitute for docker exec on the sandbox container; raw docker exec runs as root and lands on HOME=/root, where the selected agent config is not present.
OpenClaw config resolves under /sandbox/.openclaw.
Everything after -- is forwarded verbatim to the sandbox command, including flags the inner command needs.
After an OpenClaw one-shot command exits, NemoClaw verifies and, when needed, restores the mutable config permission contract.
When cleanup succeeds, exec returns the remote command’s exit code.
If cleanup cannot inspect, restore, or verify that contract, it fails closed and prints OpenClaw permission cleanup failed (...) to stderr.
In that case, exec returns the cleanup failure instead of the remote command’s status.
By default, NemoClaw inherits caller stdin only when it is a terminal.
Non-terminal or unavailable stdin is closed so SSH, CI, and other one-shot commands cannot wait on an inherited pipe.
Pass --stdin to forward an intentional pipe, or --no-stdin to close terminal stdin explicitly.
OpenShell preserves line endings and quote characters inside each command argument, so inline scripts and heredocs can be passed as one argument after --.
For example, a shell variable keeps the multi-line script in one argv element:
NUL bytes are still rejected in command arguments.
Line breaks are accepted only in command argv: --workdir remains single-line, and NemoClaw does not expose OpenShell request-environment injection on this command.
nemoclaw <name> agent
Run one agent turn non-interactively in a running sandbox.
For OpenClaw sandboxes, this command forwards arguments to openclaw agent ... inside the sandbox via openshell sandbox exec, with HOME=/sandbox so the addressed agent profile resolves the same way as connect.
For terminal-runtime sandboxes, NemoClaw forwards arguments to the manifest-declared interactive command; LangChain Deep Agents Code sandboxes run dcode ....
Use this when driving the sandbox programmatically from another process (CI job, multi-agent platform, evaluation harness) rather than from an interactive terminal.
All flags accepted by the selected in-sandbox agent CLI are forwarded verbatim, so the upstream surface stays the single source of truth.
OpenClaw invocations must include at least one target selector: --agent, --session-id, --session-key, or --to.
This keeps the wrapper from falling back to the unspecified default-session behaviour.
Conflict resolution between multiple selectors is delegated to the in-sandbox openclaw agent argv contract; the host-side guard only checks presence.
When post-command permission cleanup succeeds, the wrapper inherits the remote command’s exit code so host-side pipelines can branch on it.
If cleanup fails closed, the wrapper prints the command and cleanup statuses to stderr and returns the cleanup failure.
For normal turns, streaming forwards whatever the in-sandbox agent command emits on stdout; the wrapper adds no buffering.
The in-sandbox NemoClaw plugin writes its registration banner to stderr, so the banner does not prefix the agent reply on stdout in non-JSON mode.
When the top-level OpenClaw --json output flag is present, the wrapper uses a captured no-TTY path with a 64 MiB buffer so stdout stays parseable JSON.
Raw stderr is forwarded, and failed-tool or untrusted-child provenance found in the stdout JSON is appended to stderr.
Literal --json values consumed by flags such as -m or --reply-channel, or arguments after --, stay on the normal passthrough path.
Documented value flags written as --flag=value, such as --session-id=s1, are recognized the same way as separated value flags.
If an unrecognized OpenClaw option appears before --json, NemoClaw also keeps the command on the normal passthrough path so OpenClaw remains the argv source of truth.
Common OpenClaw flags include -m <text>, --session-id <id>, --agent <id>, --model <id>, --thinking <level>, --json, --deliver, --reply-channel <channel>, and --timeout <seconds>.
For OpenClaw sandboxes and registry fallbacks, nemoclaw <name> agent --help prints the wrapper-level summary locally.
Invoke nemoclaw <name> exec -- openclaw agent --help to view the upstream OpenClaw help text directly.
For registered terminal-runtime sandboxes, bare invocations and --help are forwarded to the terminal command, so a LangChain Deep Agents Code sandbox receives dcode for nemoclaw <name> agent and dcode --help for nemoclaw <name> agent --help.
Host-side validation runs before the sandbox dispatch:
- OpenClaw sandboxes and registry fallbacks must include at least one target selector flag:
--agent,--session-id,--session-key, or--toin either--flag valueor--flag=valueform. OpenClaw invocations without a selector exit2and printNo target session selectedlocally, without paying the in-sandbox dispatch cost. Registered terminal-runtime sandboxes delegate bare invocations and help flags to the manifest command instead. - If the sandbox is registered but not in a
ReadyorRunningphase, the wrapper exits1and prints the documented recovery commands (nemoclaw <name> recover,nemoclaw <name> rebuild --yes,nemoclaw onboard --resume) rather than deferring the readiness rejection toopenshell sandbox exec. - If a recent timed shields window auto-restored before the one-shot OpenClaw command, the wrapper prints a stderr-only reminder such as
Shields auto-relockedwith the matchingnemoclaw <name> shields down --timeout ...command before dispatch. JSON stdout stays parseable, and the warning is advisory because current scope state still belongs to OpenClaw and OpenShell.
Advanced Sandbox Maintenance Commands
The following commands are available for targeted host-side maintenance, but they are not part of the top-level public command list.
nemoclaw <name> config get
Read the sanitized agent configuration from a sandbox.
The output removes credential-bearing sections before printing.
Use --key to read one dotpath and --format to choose JSON or YAML output.
nemoclaw <name> shields
Manage the sandbox config lockdown posture from the host.
Use shields status to inspect the current state, shields up to lock the sandbox config and restore the captured restrictive policy, and shields down to temporarily unlock the config for maintenance.
For the full mutability matrix, refer to Understand Runtime Changes.
If shields up reports that the config remains unlocked or drifted, confirm that the sandbox is running and ready, then retry nemoclaw <name> shields up.
If the retry still fails, rebuild a known-good baseline with nemoclaw <name> rebuild --yes.
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.
nemoclaw <name> recover
Repair a stopped in-sandbox gateway and re-establish host-side forwards without opening an SSH session.
Use this after a direct sandbox container restart, a sandbox crash, or whenever nemoclaw <name> status reports the gateway is not running but the sandbox is alive.
For built-in OpenClaw and Hermes sandboxes, recover sends an authenticated lifecycle request through registry-scoped privileged direct-container control.
The host selects the controller from the live container topology.
In a direct root-entrypoint container, the request reaches the root PID 1 supervisor.
In an OpenShell-managed container, the request enters the root-owned mode 0500 managed controller through a sanitized root exec while OpenShell remains PID 1.
It does not use ordinary openshell sandbox exec or an in-sandbox manual relaunch as a fallback.
When the root-owned managed controller attests two unchanged zero-supervisor process scans with a stable PID 1 and reports SUPERVISOR_NOT_RUNNING, a local Docker-driver sandbox with the legacy keepalive startup can enter a transactional container recreation.
The recreation uses a credential-free managed startup command, pins the registered container identity, retains the previous container for rollback, and commits only after managed gateway health and the settle check pass.
The recreation preserves mounted sandbox state, but a committed swap does not retain changes stored only in the previous container’s writable layer.
It is idempotent.
When recover repairs a stopped built-in OpenClaw or Hermes gateway, it repeats the recovery action only for an exit status of 1 with blank stdout and a sole nonblank stderr line equal to SUPERVISOR_BUSY, with at most three controller attempts.
The same result is inconclusive during managed settle confirmation and can be probed again only within the configured settle window.
NemoClaw treats SUPERVISOR_UNAVAILABLE as terminal because the managed controller uses it for integrity refusals, ambiguous discovery, and process-identity changes.
It does not repeat the recovery action or treat the settle probe as inconclusive, and instead prints host-side restart and rebuild guidance.
Other controller failures also stop immediately.
If the gateway is already running, the command exits zero without force-restarting it; it can still re-evaluate supported safety checks and check or recover host-side forwards.
Use nemoclaw <name> gateway restart when you deliberately need a running gateway to reload runtime configuration or plugins.
The privileged control path requires a running direct sandbox container that belongs to the named registry entry.
Supported built-in images use either a direct root entrypoint or the OpenShell-managed process shape with OpenShell as PID 1 and exactly one nonroot nemoclaw-start supervisor.
An arbitrary nonroot entrypoint that does not match the supported OpenShell-managed process shape fails with the privileged control unavailable failure layer.
Kubernetes and other deployments without a matching direct container also fail with that layer.
nemoclaw <name> gateway restart
Force-restart the supported in-sandbox gateway process through the controller for the live container topology.
Use this after runtime configuration or plugin changes that the agent reads only at gateway startup, such as Hermes Langfuse plugin settings.
Unlike recover, this command restarts a healthy gateway instead of exiting after the health probe.
On success, the command reports that the gateway was restarted, health passed, and forwards were checked or recovered.
It also checks the dashboard forward, messaging forward, and manifest-declared agent forwards.
--quiet suppresses progress lines but still prints refusal diagnostics.
In the direct root-entrypoint topology, PID 1 stops only the gateway child whose process ID and process start identity match the tracked child, applies the restart seal, and launches the replacement under the separate gateway UID.
In the OpenShell-managed topology, the installed root controller verifies a stable OpenShell to nemoclaw-start to gateway process shape, holds a root-only lifecycle lock, publishes one root-owned exit authorization bound to the exact gateway process ID, kernel start identity, and live controller identity, pidfd-targets the observed child, waits for the nonroot entrypoint supervisor to respawn it under the sandbox UID, and proves the replacement listener and HTTP health.
That managed process proof prevents PID reuse from redirecting the signal but cannot establish provenance against a malicious same-UID process or create gateway and agent UID isolation.
For Hermes, the entrypoint supervisor also owns the dashboard process, internal API relay, dashboard relay, and gateway log stream.
The managed nonroot supervisor continuously repairs those processes, stops an alive but deaf gateway after four consecutive failed health checks, and quarantines relaunch after five unexpected exits or failed replacement candidates within 60 seconds until sandbox recreation.
That authorization keeps an authenticated host-requested exit out of the crash budget while its exact root controller remains live; it records host intent for the exit but does not claim that the host signal was the only possible cause in the shared-UID topology.
The host repairs only the host-side OpenShell forwards after the supervisor reports a healthy gateway.
The command can fail at these layers: unsupported agent, privileged control unavailable, supervisor not running, secret-boundary refusal, unsafe config path, config hash mismatch when a strict hash is available, launch failure, health timeout, or forward recovery failure.
An older direct-container image without the matching supervisor or managed controller helper reports privileged control unavailable and requires nemoclaw <name> rebuild --yes.
Ordinary OpenShell exec and manual in-sandbox relaunch are not fallback paths.
Terminal agents do not have a gateway runtime and fail as unsupported.
nemoclaw <name> stop
Stop the sandbox’s Docker container while preserving all of its state.
Workspace files, credentials, network policies, the registry entry, and the OpenShell sandbox record stay in place; only the container stops running.
Use this to free CPU, memory, and GPU resources without destroying the sandbox; use nemoclaw <name> destroy when you want to delete it instead.
For OpenClaw-managed gateways, the command first asks the in-sandbox gateway to shut down its channels gracefully; agent-managed gateways (for example Hermes) are supervised inside the sandbox and shut down with the container’s stop signal. Then the container stops; a container stuck in a crash loop is stopped the same way, which also disarms its restart policy. The shared host gateway, tunnel services, and any local NIM inference container serve other sandboxes and keep running. Stopping an already-stopped sandbox succeeds without changes. The command controls the local container directly, so it is available for local-container drivers (the default Docker driver and the vm driver) and unavailable for remote drivers such as kubernetes; if the Docker daemon itself is unreachable, the command reports the outage instead of guessing at container state.
nemoclaw <name> start
Restart a sandbox container that was stopped with nemoclaw <name> stop or by a host reboot, then repair the in-sandbox gateway and host-side forwards the same way nemoclaw <name> recover does.
Starting an already-running sandbox skips the container start and still runs the gateway and forward health checks.
A paused container is unpaused.
If the container was removed entirely, start fails and points you to nemoclaw <name> rebuild.
nemoclaw <name> status
Show sandbox-scoped status, health, and inference configuration for one registered sandbox.
Use this form when you care about a specific sandbox’s live OpenShell state, agent runtime, inference health, GPU proof, permissions, and recovery hints.
Do not pass a sandbox name to nemoclaw status; that command is the global all-sandbox/service overview.
Pass --json to emit a structured per-sandbox report instead of the text renderer.
The JSON output includes at least schemaVersion, name, found, agent, agentDisplayName, agentRuntime, dcodeAutoApprovalMode, model, provider, recordedRoute, liveRoute, routeDrift, phase, gatewayState, inferenceHealth, rpcIssue, hostGpuDetected, sandboxGpuEnabled, sandboxGpuMode, sandboxGpuDevice, openshellDriver, openshellVersion, policies, failureLayer, terminalRuntimeHealth, and dockerPaused.
The schema-version 1 model and provider fields keep their established live-route meaning when the gateway route is readable.
Use recordedRoute for the sandbox’s durable provider and model and liveRoute for the gateway-global route.
When the live shared route differs, text output prints both routes and JSON output sets routeDrift.live, routeDrift.recorded, and routeDrift.canConnect.
When routeDrift.canConnect is false, connect cannot safely restore the recorded route because provider-global identity differs or required route or gateway metadata is incomplete.
Refer to Use Shared Gateway Routes for the route-sharing workflow.
openshellDriver and openshellVersion are always strings (falling back to "unknown" when the registry has no value), so consumers can rely on typeof checks.
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 nemoclaw <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, the authoritative in-sandbox inference route fails or cannot be probed, or a terminal runtime sandbox reports a recorded OOM kill.
The alias form nemoclaw <name> status --json requires the sandbox to be registered locally; the canonical form nemoclaw sandbox status <name> --json is the one to use from automation that may run against an unknown sandbox name, since it still emits a JSON document with found: false instead of a text error.
The command probes https://inference.local/v1/models from inside the sandbox as the authoritative inference health check.
This check exercises the same route that agent traffic uses.
The main Inference line reports one of these states:
An authentication response confirms that the route is reachable, not that provider credentials are valid.
The command can also print direct host-side provider checks such as Inference (upstream) and provider-specific subprobes.
These checks are diagnostic only and do not override the authoritative inference.local result or determine the command exit status.
Local providers add host-side backend diagnostics.
For Local Ollama, the command can also print an Inference (auth proxy) diagnostic when a proxy token is available.
Use these diagnostics to identify a failing auxiliary hop after checking the main Inference line.
For cloud-only providers, the output omits the NIM status line unless a NIM container is registered or an unexpected NIM container is running.
When the sandbox’s recorded driver is docker and the host Docker daemon is not reachable, the command prints the docker_unreachable failure layer with the message Docker daemon is not reachable. as the first line of stdout, suppresses the host-side Inference probe (which otherwise hits the remote provider directly and is misleading when the local stack is down), and exits with a non-zero status.
When the host Docker daemon is reachable but the per-sandbox container is stopped, the 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’s recorded dashboard port is also held by a foreign listener, the header escalates to the sandbox_dashboard_port_conflict failure layer with the message sandbox container is stopped and the dashboard port is held by a foreign listener. so the operator can recover the port before restarting the sandbox.
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.
Gateway and dashboard health checks treat HTTP 401 from device auth as a live service, not as an offline gateway.
When sandbox GPU passthrough is enabled, the Sandbox GPU line includes the last CUDA usability proof state.
It reports (CUDA verified), (CUDA unverified), or (last CUDA proof failed: <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 sandbox list in the status output includes the dashboard port suffix for sandboxes with a recorded dashboard port.
The Policy section displays the live enforced policy (fetched via openshell policy get --full), which reflects presets added or removed after sandbox creation.
When OpenShell reports an active policy version, the displayed YAML version line uses that active version instead of the static schema version.
If the sandbox is running an outdated agent version, the output includes an Update line with the available version and a nemoclaw <name> rebuild hint.
When other sandboxes have the same messaging channel enabled (Telegram, Discord, or Slack) with the same bot token, the output includes a cross-sandbox overlap warning so you can resolve the conflict before messages start dropping.
The command also tails /tmp/gateway.log inside the default sandbox and flags Telegram 409 Conflict errors that indicate a duplicate consumer for the bot token.
Checking the OpenClaw version
Refer to Update Sandboxes for the OpenClaw version pin and rebuild policy.
nemoclaw <name> status prints the running OpenClaw version on the Agent line:
Expected output:
If the sandbox is running an OpenClaw older than the version this NemoClaw release pins, status and connect add an Update line pointing at nemoclaw <name> rebuild to pick up the newer version.
The rebuild reuses the existing sandbox name and persisted credentials, so messaging tokens and provider keys carry over.
nemoclaw <name> doctor
Run a focused health check for one sandbox and the host services it depends on. The command checks the local CLI build, Docker daemon, OpenShell CLI, NemoClaw gateway container, gateway port mapping, live sandbox state, inference route, provider reachability, Ollama reachability, and the cloudflared tunnel state. For gateway-based agents, it also reports messaging channel conflicts.
For inference health, doctor treats the probe to https://inference.local/v1/models from inside the sandbox as authoritative.
HTTP responses from 200 through 499, including 401 and 403, pass this check.
HTTP 500 through 599, interim 100 through 199, transport failures with status 000, invalid status values, and an unavailable authoritative probe fail the check.
Direct provider and upstream probes are diagnostics only, so their failure does not fail doctor when the authoritative in-sandbox route is healthy.
Warnings do not make the command fail.
Failed checks, including a failed or unavailable authoritative inference route, exit non-zero so scripts can use doctor as a readiness gate.
Use --json for machine-readable output.
For OpenClaw sandboxes, doctor also checks the mutable config permission contract.
If openclaw doctor --fix was run inside the sandbox, it can tighten /sandbox/.openclaw and openclaw.json to a single-user 700/600 layout, which stops the gateway from persisting config changes.
doctor reports this as a Config permissions warning; pass --fix to restore the group-writable 2770/660 contract without rebuilding.
Restarting the sandbox repairs the same drift automatically.
nemoclaw <name> exec
Run a command non-interactively inside a running sandbox through the OpenShell exec endpoint.
The command runs as the sandbox user with HOME=/sandbox.
Use -- to separate exec options from the command you want to run inside the sandbox.
After the remote command exits, NemoClaw verifies and, when needed, restores the mutable OpenClaw config permission contract.
When cleanup succeeds, exec preserves the remote command’s exit code.
When cleanup fails closed, exec returns the cleanup failure and reports both statuses on stderr.
By default, NemoClaw inherits caller stdin only when it is a terminal.
Non-terminal or unavailable stdin is closed so SSH, CI, and other one-shot commands cannot wait on an inherited pipe.
Pass --stdin to forward an intentional pipe, or --no-stdin to close terminal stdin explicitly.
OpenShell preserves line endings and quote characters inside each command argument, so inline scripts and heredocs can be passed as one argument after --.
For example, a shell variable keeps the multi-line script in one argv element:
NUL bytes are still rejected in command arguments.
Line breaks are accepted only in command argv: --workdir remains single-line, and NemoClaw does not expose OpenShell request-environment injection on this command.
nemoclaw <name> logs
View sandbox logs.
Use --follow to stream output in real time.
Use --tail <lines> or -n <lines> to limit the number of returned lines.
Use --since <duration> to show recent logs only, such as 5m, 1h, or 30s.
The command reads both agent gateway output and OpenShell audit events, so policy denials appear alongside the gateway log stream.
If one log source is unavailable, NemoClaw prints a warning and keeps reading the remaining source.
NemoClaw’s --tail <lines> flag is a line-count flag; the lower-level openshell logs --tail flag means follow live output, so use openshell logs <sandbox> -n <lines> when running OpenShell directly for a fixed line count.
nemoclaw <name> dashboard-url
Print the browser dashboard URL for a running sandbox. For OpenClaw sandboxes this includes the authenticated URL fragment. For agent dashboards that manage their own session, such as Hermes Agent, this prints the plain dashboard URL. Use this when you are on a remote machine, using an SSH or reverse tunnel, or need a complete URL for a browser session.
The default output includes a label and a warning.
Pass --quiet or -q to print only the URL to stdout so scripts can capture it:
Treat the authenticated dashboard URL like a password. Do not log it, share it, or commit it to version control. This warning applies when the command prints an OpenClaw tokenized URL.
nemoclaw <name> gateway-token
Print the OpenClaw gateway auth token for a running sandbox to stdout.
The token is required by openclaw tui and the OpenClaw dashboard URL.
Use dashboard-url for browser access; use gateway-token only when automation needs the raw token.
Pipe it into automation or capture it into an environment variable:
The token is written to stdout with no surrounding text.
A one-line security warning is written to stderr; pass --quiet (or -q) to suppress it.
The command exits non-zero with a diagnostic on stderr when the sandbox is not registered or when the token cannot be retrieved (for example, if the sandbox is not running).
The token also authenticates the Control UI config endpoint served by the gateway on the forwarded dashboard port.
There is no controlui.bootstrap.config.json path; the supported endpoint is /__openclaw/control-ui-config.json, and it requires the token (unauthenticated requests return 401 with a JSON body):
Treat the gateway token like a password. Do not log it, share it, or commit it to version control.
nemoclaw <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 nemoclaw <name> snapshot create or refer to Create and Restore Snapshots.
If you want to upgrade the sandbox while preserving state, use nemoclaw <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, or set NEMOCLAW_NON_INTERACTIVE=1, to authorize deletion without prompting 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, unattended final-sandbox destroys (--yes, --force, or NEMOCLAW_NON_INTERACTIVE=1) remove the shared NemoClaw gateway on macOS so the host listener is released, while Linux preserves it for reuse.
Pass --cleanup-gateway to force removal, or --no-cleanup-gateway to force preservation.
These flags always override both NEMOCLAW_CLEANUP_GATEWAY and the platform default.
If the pre-delete workspace wipe cannot run, use a different sandbox name for a clean start.
Cleaning up the gateway after the last sandbox also purges the shared cluster volume that retains the per-name persistent volume.
If final gateway cleanup finds a live PID-file process whose command line does not prove it owns the target gateway, destroy exits non-zero after sandbox and registry deletion and skips gateway and volume removal.
NemoClaw preserves the per-gateway PID file and runtime marker so you can inspect the process.
Stop only the listener that matches the target gateway, then rerun destroy to converge cleanup.
If the OpenShell gateway is unreachable and the sandbox has no managed MCP ownership state, --force removes only NemoClaw’s local registry entry and local artifacts.
Gateway-side deletion remains unconfirmed, shared host-service and gateway teardown are skipped, and the sandbox and retained volume may still exist if the gateway returns.
Start the gateway with nemoclaw <name> status and retry destroy when you need a confirmed deletion.
Managed MCP ownership disables the local-only fallback because exact provider cleanup requires the retained ownership state, and other delete failures remain fatal.
nemoclaw <name> policy-get
Export the sandbox’s round-trippable OpenShell base policy as YAML.
The command runs openshell policy get --base, validates the returned policy, and strips the OpenShell metadata header.
The default output is suitable for review, editing, and later use with openshell policy set.
The command exits non-zero when OpenShell fails, returns an empty response, or returns content that is not valid policy YAML.
Use --raw only to inspect the unparsed OpenShell response, including its metadata header:
Do not pass --raw output to openshell policy set because the metadata header is not part of the policy document.
nemoclaw <name> policy-add
Add a policy preset to a sandbox. Presets extend the baseline network policy with additional endpoints. Before applying, the command shows which endpoints the preset would open and prompts for confirmation.
To apply a specific preset without the interactive picker, pass its name as a positional argument:
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 round-trippable base policy from OpenShell.
If the base policy read returns non-empty output that NemoClaw cannot parse, the command exits non-zero instead of overwriting the live policy with only the new preset.
Fix the gateway or policy read problem, then rerun the command.
For custom presets, the command also reports when the preset reached the gateway but NemoClaw could not record it in the local sandbox registry, because unrecorded custom presets will not appear in policy-list or status.
Recover or re-onboard the sandbox, then re-apply the custom preset.
Use --dry-run to audit a preset before applying it:
Apply a custom preset file when you need to grant access to an endpoint that is not covered by a built-in preset:
For batch workflows, apply all preset files from a directory:
Review every host in custom preset files before applying them. Custom presets bypass the built-in preset review process and can widen sandbox egress.
nemoclaw <name> policy-list
List available policy presets and show which ones are applied to the sandbox.
The available built-in rows are scoped to the sandbox’s active agent, so unsupported messaging channel policies are not listed for agents without matching channel policy files.
The command cross-references the local registry against the live gateway state (via openshell policy get), so it flags presets that are applied in one place but not the other.
This catches desync caused by external edits to the gateway policy or stale registry entries after a manual rollback.
Preset summaries come only from the YAML preset.description field.
NemoClaw does not render network-policy rule bodies as prose in policy-list output.
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).[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 throughpolicy-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.
nemoclaw <name> policy-remove
Remove a previously applied policy preset from a sandbox. The command lists only the presets currently applied, prompts you to select one, shows the endpoints that would be removed, and asks for confirmation before narrowing egress.
To remove a specific preset non-interactively, pass its name as a positional argument:
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.
Unchecking a preset in the onboard TUI checkbox also removes it from the sandbox.
nemoclaw <name> policy-explain
Print a redacted summary of the active policy context for a sandbox so an agent or operator can reason about what is allowed, what is blocked, and how to request a change. The output covers the recorded tier, 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.
Pass --json to emit the same context as a structured object for agent consumption:
NemoClaw refreshes the rendered context inside the sandbox at /sandbox/.openclaw/workspace/POLICY.md whenever a preset is added or removed, and once at the end of the onboarding policy step.
Pass --write to refresh that file on demand without changing the policy:
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.
nemoclaw <name> hosts-add
Add a host alias to the sandbox pod template.
Use this when a sandbox needs a stable LAN-only name, such as a local SearXNG or internal model endpoint, without dropping to docker exec and kubectl patch.
Host alias commands use the legacy Kubernetes gateway Sandbox resource path.
In that older topology, the openshell-cluster-nemoclaw container runs an embedded k3s cluster with a sandboxes.agents.x-k8s.io custom resource definition, and an agent-sandbox-controller reconciles each Sandbox resource into the agent pod.
They are not supported on Docker-driver or VM-driver sandboxes because those drivers do not run the gateway cluster container that owns this resource.
The command validates the hostname and IP address, rejects duplicate hostnames, and patches spec.podTemplate.spec.hostAliases on the sandbox resource.
nemoclaw <name> hosts-list
List host aliases configured on the sandbox resource.
nemoclaw <name> hosts-remove
Remove a hostname from the sandbox hostAliases list.
nemoclaw <name> channels list
List the messaging channels NemoClaw knows about (telegram, discord, slack, wechat, whatsapp) with a short description.
The command is a static reference; it does not consult credentials or the running sandbox.
WeChat and WhatsApp are experimental.
nemoclaw <name> channels add <channel>
Register a messaging channel with the sandbox and rebuild so the image picks up the new channel. Channels fall into three login modes:
- Token paste (
telegram,discord,slack): the command prompts for any missing token and registers it with the OpenShell gateway. - Host-side QR (
wechat, experimental): the command renders an iLink QR code on the host and you scan it from WeChat on your phone. On confirm, NemoClaw captures the bot token, registers it with the OpenShell gateway, and stores non-secret per-account metadata (WECHAT_ACCOUNT_ID,WECHAT_BASE_URL,WECHAT_USER_ID) for the in-sandbox bridge. NemoClaw automatically adds the scanning operator’s WeChat user ID toWECHAT_ALLOWED_IDS. Supply additional comma-separated IDs to authorize more DM senders. NemoClaw advertises WeChat for both OpenClaw (the@tencent-weixin/openclaw-weixinplugin) and Hermes (the built-in iLink WeChat adapter). - In-sandbox QR (
whatsapp, experimental): the command records the channel without a host-side token or OpenShell credential provider. NemoClaw advertises WhatsApp for OpenClaw and Hermes sandboxes; after rebuild, runopenclaw channels login --channel whatsappfor OpenClaw orhermes whatsappfor Hermes. This intentionally leaves QR-created mutable session state in the sandbox until you unpair it or clear the durable agent state.
After registering the channel, NemoClaw asks whether to rebuild immediately.
Running add for an already-configured channel overwrites the stored credentials where applicable.
The operation is idempotent.
Channel names are trimmed and lowercased before NemoClaw stores credentials, names bridge providers, or prints rebuild messages.
NemoClaw requires the matching built-in network policy preset YAML to be present.
A missing or malformed preset YAML (no network_policies: section) aborts channels add before any token prompt, registry write, or rebuild prompt.
With the preset file in place, NemoClaw applies it to the sandbox before the rebuild so the bridge has egress to its upstream API.
When the apply step itself fails after the registry write on a fresh add, NemoClaw attempts to roll back the bridge providers, the messagingChannels entry, and any staged environment credentials, then exits without prompting for a rebuild; if any gateway-side step (provider detach or delete) fails the rollback continues and prints a Rollback could not fully clean <surfaces> warning so the operator can clean up manually.
When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior messagingChannels entry, restores staged environment credentials when available, restores registry credential hashes, and attempts to re-upsert the prior bridge providers, but flags gateway-providers as residual because the in-flight upsert may have left the gateway with the new token; verify the gateway bridge before relying on the channel.
Restore the preset YAML and re-run nemoclaw <name> channels add <channel>.
For Telegram, Discord, and Slack, a rebuild triggered by channels add also verifies that the selected bridge starts and reports credential, startup, or plugin discovery warnings.
Slack requires both SLACK_BOT_TOKEN (bot user OAuth) and SLACK_APP_TOKEN (app-level Socket Mode token); the command prompts for each in turn.
Optional Slack allowlists come from SLACK_ALLOWED_USERS and SLACK_ALLOWED_CHANNELS at rebuild time.
Telegram and Discord mention mode default to 1 when no environment, session, or saved state value exists for that setting.
Discord applies that default only when a server ID is configured.
When NEMOCLAW_NON_INTERACTIVE=1 is set, any missing token fails fast and no rebuild prompt is shown.
Instead, the change is queued and you are told to run nemoclaw <name> rebuild manually.
If you omit the required <channel> argument, the CLI prints the channels add <channel> usage with the supported channel list instead of falling back to top-level help.
nemoclaw <name> channels remove <channel>
Clear the stored credentials for a messaging channel and rebuild the sandbox so the image drops the channel.
Running remove for a channel that was never configured is a no-op against the credentials file and still triggers the rebuild prompt.
When the bridge provider is attached to a live sandbox, NemoClaw detaches it before deleting the provider from the OpenShell gateway.
If the matching built-in policy preset is applied, such as telegram, discord, slack, wechat, or whatsapp, NemoClaw also removes that preset so the upstream API is no longer allow-listed after the channel is gone.
NemoClaw also strips the channel from session.policyPresets so a subsequent onboard --resume does not re-apply the preset on the next rebuild.
For QR-paired channels (today: WhatsApp), NemoClaw destructively clears the in-sandbox session directory before the rebuild so the state_dirs backup does not restore the auth blob and let the channel reconnect:
- OpenClaw:
/sandbox/.openclaw/<channel>/(for example/sandbox/.openclaw/whatsapp/). - Hermes:
/sandbox/.hermes/platforms/<channel>/(for example/sandbox/.hermes/platforms/whatsapp/).
The cleanup tries openshell sandbox exec first and falls back to SSH if the exec wrapper does not return the success sentinel. If both transports fail (the sandbox is stopped, the gateway is down, or SSH cannot reach it) the command refuses to proceed to the rebuild and asks you to start the sandbox and re-run, so a half-removed state cannot leave stale Baileys auth files behind for the next rebuild to restore.
As with channels add, NEMOCLAW_NON_INTERACTIVE=1 skips the rebuild prompt and queues the change for a manual nemoclaw <name> rebuild.
If you omit the required <channel> argument, the CLI prints the channels remove <channel> usage with the supported channel list.
Host-side removal is the supported path because agent channel config is baked into the container image at build time (/sandbox/.openclaw/openclaw.json for OpenClaw and /sandbox/.hermes/.env for Hermes); agent-specific channel removals inside the sandbox would modify the running config but not persist changes across rebuilds.
nemoclaw <name> channels stop <channel>
Pause a single messaging bridge (telegram, discord, slack, wechat, or whatsapp) without clearing its credentials.
The channel is marked disabled in the per-sandbox registry, and the sandbox is rebuilt so the onboard step skips registering the bridge with the gateway.
The provider stays registered with the OpenShell gateway, so a later channels start brings the bridge back without re-entering tokens.
Use channels stop instead of channels remove when you want to pause a bridge temporarily. channels remove is destructive to credentials; channels stop is not.
nemoclaw <name> channels start <channel>
Re-enable a channel previously paused with channels stop. The channel is removed from the disabled list, the sandbox is rebuilt, and the bridge registers with the gateway again using the stored credentials.
Before the rebuild, NemoClaw reapplies the matching built-in network policy preset so the restored bridge has egress to its upstream API.
If policy restoration fails, NemoClaw rolls the channel back to disabled and exits without rebuilding into a partially active state.
nemoclaw <name> channels status
Run messaging channel status checks.
Without --channel, the command prints a compact summary for every configured channel, including registration, policy coverage, and non-secret rendered config comparisons.
For channels that support a live health probe (WhatsApp, Telegram), the summary adds a Runtime health: not checked in summary view pointer instead of running the probe, so it never reads as healthy without an explicit check.
With --channel, it prints the detailed status for that channel.
For WhatsApp, --channel whatsapp also probes the sandbox to separately report pairing/session state, the Noise WebSocket connection, inbound event delivery, and policy coverage.
A paired channel with no observed inbound delivery exits non-zero with verdict idle so an unhealthy bridge cannot pass as healthy.
The detailed WhatsApp probe stays focused on QR/session runtime diagnostics and does not include rendered-config comparison lines.
For Telegram, --channel telegram probes the sandbox to report the gateway process, Bot API reachability, and inbound delivery alongside the config comparison, and classifies the current state into a verdict such as healthy, idle, unreachable (network or egress), token_rejected, or not_started.
It reads the gateway’s own startup and poll log breadcrumbs rather than issuing its own Bot API request, so the resolved bot token never leaves the gateway.
The verdict reflects the most recent evidence in the log window, so a bridge that recovered after a blocked start reports healthy while one blocked again reports unreachable.
Telegram health is probed only for OpenClaw sandboxes; a Hermes Telegram sandbox uses the basic config report.
For registered non-WhatsApp channel details and the compact summary, the status output compares non-secret config inputs from the sandbox registry against the values rendered into the agent config, such as Telegram group policy in openclaw.json or mention mode in Hermes config.
Secret inputs, including tokens, are not printed.
If the registry contains a non-secret expected value but NemoClaw cannot read or check the rendered source, the comparison is a warning and the detail includes (not checked).
Optional unset inputs remain informational.
Each probe is bounded by an in-sandbox openshell sandbox exec with a hard timeout and returns only matched bridge/gateway log lines (e.g. connection.open, 401 unauthorized, qr expired, or [telegram] startup breadcrumbs) to the host, where NemoClaw reduces them to fixed classifications; the raw lines are never rendered, so the diagnostic output carries only those classifications, never message bodies or tokens.
nemoclaw <name> mcp list
List MCP servers configured for a sandbox. The command reports the selected agent’s MCP support status and, for each configured server, whether the generated OpenShell provider, policy, and agent adapter are present.
nemoclaw <name> mcp add
Add an MCP Streamable HTTP server to a sandbox.
Pass --url for the MCP endpoint and the required single --env KEY bearer credential for the sandbox-side MCP client.
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.85 evaluates that policy before replacing the attached provider placeholder in the allowed request header.
Static provider placeholders are sandbox-scoped rather than endpoint-exclusive, so do not grant broader inspected-HTTP routes to the same adapter runtime and credential key.
The sandbox client connects directly through OpenShell’s existing egress path, and NemoClaw does not run a host-side MCP data-plane bridge, proxy, relay, or listener.
After the add commits, NemoClaw freshly verifies the exact generated policy, expected provider attachment, recorded provider ID, generic type, valid resource version, and exactly one credential key matching the recorded key.
If those readiness checks pass, it sends a differential pair of wire-level MCP initialize requests from inside the sandbox — one with the placeholder header and one with an unresolvable control bearer — to verify that OpenShell resolves the credential on egress; otherwise it reports an inconclusive probe skipped result and sends no request.
Neither outcome fails the committed add, and --no-probe skips this check.
For full setup details, see Add an MCP Server.
nemoclaw <name> mcp status
Inspect MCP server state for one server or for all configured servers.
Status includes OpenShell provider presence and credential-key shape, provider attachment, generated policy content match, adapter registration, current host-variable availability, and the selected agent’s MCP support mode.
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.
nemoclaw <name> mcp restart
Refresh one MCP server registration, or every server on the sandbox when no server is supplied. Restart reapplies the generated policy, reattaches the OpenShell provider when needed, and refreshes the sandbox agent adapter registration. 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.
nemoclaw <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.85 mutates providers by name, so do not concurrently replace a managed provider through another OpenShell client during this command.
When an interrupted destroy leaves a prepared-only transaction, deletion is not durably confirmed.
If the sandbox is still live, run nemoclaw <name> mcp remove <server> --force with the affected server name.
NemoClaw clears the prepared marker only after cleanup succeeds without residuals and no bridge entries remain.
A failed cleanup, a wrong server name, residual resources, or any remaining bridge entry preserves the marker for another retry.
A pending marker, including a transaction with both prepared and pending markers, means the registry records that OpenShell deletion was already confirmed.
mcp remove --force refuses this state.
Run nemoclaw <name> destroy to finish the idempotent provider and policy cleanup.
nemoclaw <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.
The skill directory must contain a SKILL.md file with YAML frontmatter that includes a name field.
Skill names must contain only alphanumeric characters, dots, hyphens, and underscores.
OpenClaw plugins are a different kind of extension.
To install an OpenClaw plugin, refer to Install OpenClaw Plugins.
For OpenClaw, the command uploads the skill to the OpenClaw state directory and mirrors it into $HOME/.openclaw/skills/<name> when the agent home directory differs from the state directory.
That mirror makes skills listed by openclaw skills list available at session startup.
If mirror creation fails, NemoClaw prints a warning so you can reinstall or inspect the home directory permissions.
Run nemoclaw <name> skill install --help to print usage for this subcommand.
If you pass a plugin-shaped directory to skill install, the CLI prints a plugin-specific hint instead of treating it as a missing skill file.
Files with names starting with . (dotfiles) are skipped and listed in the output.
Files with unsafe path characters are rejected to prevent shell injection.
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.
nemoclaw <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 OpenClaw, the command also removes the OpenClaw home-directory mirror when present.
Use the skill name from the SKILL.md frontmatter, not the local directory name.
Skill names must contain only alphanumeric characters, dots, hyphens, and underscores, and cannot be . or ...
nemoclaw <name> agents list
List the OpenClaw agents configured in the sandbox.
This is a thin pass-through to openclaw agents list via openshell sandbox exec; the OpenClaw CLI owns the gateway agents.list call, output formatting, and binding summaries.
Flags accepted by the in-sandbox CLI (--json, --bindings) are forwarded verbatim.
nemoclaw <name> agents add
Run the OpenClaw interactive add wizard inside the sandbox.
This is a thin pass-through to openclaw agents add via openshell sandbox exec; flags accepted by the in-sandbox CLI are forwarded verbatim.
nemoclaw <name> agents delete <agent-id>
Remove an OpenClaw agent from the sandbox.
This is a thin pass-through to openclaw agents delete <id> via openshell sandbox exec; the OpenClaw CLI owns gateway dispatch (agents.delete), host-side workspace removal, and config edits.
Flags accepted by the in-sandbox CLI (--force, --json) are forwarded verbatim.
nemoclaw <name> agents apply
Reconcile the live sandbox roster against a declarative agents.yaml manifest.
The verb lists current agents via openclaw agents list --json, diffs them against the manifest, and adds missing secondaries or deletes orphan ones through openclaw agents add|delete.
Per-agent model, subagents.*, tools, top-level defaults, and main overrides need a sandbox rebuild and are surfaced as warnings rather than silently dropped; rerun nemoclaw onboard --agents <agents.yaml> --recreate-sandbox to bake those fields.
When the diff removes orphan agents, NemoClaw invokes OpenClaw’s confirmation-skipping delete mode internally.
--non-interactive controls the host-side agents apply prompt and is not forwarded to OpenClaw’s delete command.
Pass -f / --file <agents.yaml> to point at the manifest; --yes confirms the roster diff above; --non-interactive fails fast when --yes is absent so scripted callers cannot accidentally hang on a missing prompt.
nemoclaw <name> sessions
List OpenClaw conversation sessions in the sandbox.
With no subcommand the in-sandbox CLI lists stored sessions for the configured default agent.
NemoClaw invokes openclaw sessions via openshell sandbox exec and forwards OpenClaw flags verbatim, but filters default list output so internal nemoclaw-onboard-warmup-* sessions created during onboarding are hidden from user-facing output.
nemoclaw <name> sessions list
Invoke openclaw sessions list inside the sandbox.
NemoClaw forwards every flag the in-sandbox CLI accepts (--agent, --all-agents, --active, --limit, --json, --store, --verbose) and filters the resulting default table or JSON so internal nemoclaw-onboard-warmup-* sessions are hidden.
nemoclaw <name> sessions reset <key>
Archive a session and rebind its key to a fresh sessionId by invoking the OpenClaw gateway sessions.reset RPC inside the sandbox.
Goes through openshell sandbox exec -> openclaw gateway call sessions.reset, so the gateway owns archival, lock handling, and lifecycle events; the host never edits sessions.json directly.
The <key> argument accepts an alias (e.g. main, telegram:t-1) or the canonical agent:<id>:<rest> form.
Mismatched --agent plus canonical-key combinations are refused before the gateway is invoked.
nemoclaw <name> sessions delete <key>
Remove a session entry by invoking the OpenClaw gateway sessions.delete RPC inside the sandbox.
The gateway refuses to remove the agent’s main session.
The transcript on disk is removed by default; pass --keep-transcript to retain it.
nemoclaw <name> sessions export [keys...]
Export an OpenClaw sandbox’s session history from the running sandbox to the host.
The command enumerates the session store through openclaw sessions list --agent <id> --json and copies only the matching <sessionId>.jsonl files, plus optional <sessionId>.trajectory.jsonl files.
It never picks up sessions.json, stale .jsonl.lock files, or other store bookkeeping.
By default it writes a browsable directory of session files (dir format); pass --format tar for a single .tgz bundle suited to sharing or upload.
With no positional keys, the command exports every non-internal session for the agent; if only internal warm-up sessions exist, the command reports that there are no sessions to bundle and writes no artifact.
Internal nemoclaw-onboard-warmup-* sessions are excluded from export-all output, but passing an explicit warm-up session key still exports that session for debugging.
Pass one or more keys, as aliases or canonical agent:<id>:<rest> keys, to filter.
Mismatched --agent plus canonical-key combinations are refused before any download runs.
Session keys that begin with - are rejected at the command boundary instead of being silently dropped.
Session JSONL can contain pasted secrets, such as API keys or tokens, so exported files are written owner-only (0600).
The in-sandbox staging artefact is additionally created with umask 077 and removed after the host download completes.
nemoclaw <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.
nemoclaw <name> upload <host-path> [sandbox-dest]
Host-side wrapper around openshell sandbox upload, symmetric to the download wrapper.
With no sandbox-dest the destination defaults to /sandbox/ inside the sandbox.
nemoclaw <name> rebuild
Upgrade a sandbox to the current agent version while preserving workspace state.
The command backs up workspace state, destroys the old sandbox (including its host-side Docker image), recreates it with the current image via onboard --resume, and restores workspace state into the new sandbox.
Credentials are stripped from backups before storage.
Policy presets applied to the old sandbox are reapplied to the new one so your egress rules survive the rebuild.
The replacement uses the recorded compatible-endpoint reasoning mode and web search selection instead of ambient shell values.
Rebuild preserves the recorded sandbox GPU enablement mode and, for an explicitly enabled sandbox, its recorded device selector.
It re-resolves the Docker-driver GPU route from the current host and current NEMOCLAW_DOCKER_GPU_PATCH value, so native-only, explicitly authorized native-with-fallback, and compatibility-only routing may differ from the original onboarding run.
A rebuild preserves the recorded tool-disclosure mode unless --tool-disclosure explicitly changes it; it ignores an ambient NEMOCLAW_TOOL_DISCLOSURE value while recreating the sandbox.
A rebuild preserves the recorded Deep Agents Code observability choice and matching local OTLP policy state unless --observability or --no-observability explicitly changes them.
A rebuild preserves the recorded Deep Agents Code auto-approval capability unless --dcode-auto-approval explicitly changes it.
A sandbox onboarded with an explicit GPU opt-out (stored as sandboxGpuMode: "0", plus legacy registry entries that only record gpuEnabled: false) is recreated with the same opt-out, so the inner onboard --resume skips the Docker CDI GPU preflight on hosts without an NVIDIA GPU.
Auto-mode sandboxes remain auto.
If another terminal has an active SSH session to the sandbox, rebuild prints an active-session warning and requires confirmation before destroying the sandbox.
Pass --yes, -y, or --force to skip the prompt in scripted workflows.
The sandbox normally must be reachable for the backup step to succeed.
If an archive command preserves at least one state directory, rebuild keeps the captured backup entries and reports the manifest-defined paths that could not be archived.
If every state directory fails, rebuild exits before destroying the original sandbox even when it captured loose files, unless you explicitly pass --force.
With --force, NemoClaw preserves any captured loose files in the partial manifest and restores them after recreation.
If the backup produced nothing usable, it continues from recorded registry metadata without restoring prior sandbox state.
Use this recovery path only when losing the state that could not be backed up is acceptable.
Before backup or deletion, rebuild also refuses an incomplete MCP destroy transaction.
For a prepared-only transaction, the redacted diagnostic points to nemoclaw <name> mcp remove <server> --force when the sandbox is still live.
For a pending or both-marker transaction, it points to nemoclaw <name> destroy because the registry records that OpenShell deletion was already confirmed.
Before backup or deletion, rebuild checks the staged messaging configuration 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 runs openclaw doctor --fix for cross-version structure repair.
nemoclaw update
Check for a NemoClaw CLI update and, when requested, run the maintained installer flow. This command is a discoverable CLI wrapper around the supported installer path:
nemoclaw update updates the host-side NemoClaw installation.
The maintained installer flow follows the admin-promoted lkg release tag by default, so it may trail the newest semver or latest tag while validation completes.
It does not replace nemoclaw upgrade-sandboxes; use that command to inspect or rebuild existing sandboxes after the CLI has been updated.
When the command is running from a source checkout, it reports that state and does not replace the checkout with a global package install.
nemoclaw upgrade-sandboxes
Rebuild sandboxes whose base image is older than the one currently pinned by NemoClaw.
NemoClaw resolves the digest of ghcr.io/nvidia/nemoclaw/sandbox-base:latest from the registry, then compares it against the digest each sandbox was created with.
Sandboxes that match the current digest are left alone.
NemoClaw also checks the build fingerprint recorded on each managed sandbox image.
A sandbox needs upgrade when its agent version is stale, when its recorded NemoClaw image fingerprint differs from the running CLI, or both.
When the target version is older than the recorded one (for example after reinstalling with an older NEMOCLAW_INSTALL_TAG), the stale listing marks the change with a (downgrade) suffix instead of framing it as a routine upgrade.
Custom Dockerfile sandboxes are not classified by image drift because rebuilding them onto the default image would drop the custom image.
Legacy sandboxes without a recorded fingerprint opt into this check after their next rebuild.
A recorded sandbox that is not observed in any phase on its own recorded gateway is reported as not found there, with remediation guidance — this typically means its gateway registration or Docker image was removed (for example by nemoclaw uninstall, which preserves sandboxes.json but removes both).
Each rebuild reuses the same workspace backup-and-restore flow as nemoclaw <name> rebuild, so workspace files survive the upgrade.
If the registry is unreachable (offline or firewalled hosts), NemoClaw falls back to the unpinned :latest tag and reports that the digest could not be resolved instead of failing.
During installer recovery, a registered sandbox that is not Ready can also be rebuilt from its validated latest backup.
That recovery requires a NemoClaw-managed image fingerprint or the installer’s explicit confirmation for a listed pre-fingerprint OpenClaw or Hermes entry.
The legacy confirmation never overrides recorded custom-image evidence.
A custom OpenClaw sandbox is recoverable only when the selected backup independently carries complete authoritative image-plugin provenance.
nemoclaw backup-all
Back up registered sandboxes that are running or have an eligible stopped Docker-driver container to ~/.nemoclaw/rebuild-backups/.
A registered docker-driver sandbox whose container is stopped is started for the duration of the backup and returned to its stopped state afterward.
If the container cannot be returned to the stopped state, the command fails and reports that the container was left running.
Sandboxes that are not running and cannot be started this way are skipped with remediation guidance.
Before an OpenShell upgrade, the installer prepares the current release CLI and uses it to run backup-all in strict mode.
Strict mode requires every registered sandbox to produce a fresh backup and aborts before gateway changes if any sandbox is skipped or fails.
When strict mode reports a skipped sandbox, start that sandbox or its container and rerun the installer or nemoclaw backup-all.
A running sandbox whose in-sandbox SSH endpoint does not answer fails its backup and aborts the run.
For a standalone nemoclaw backup-all run, set NEMOCLAW_SKIP_UNREACHABLE_SANDBOX_BACKUP=1 exactly to skip such sandboxes instead of failing.
Other values such as true, yes, or 0 are not accepted.
This variable does not weaken the installer’s strict pre-upgrade requirement.
A skipped sandbox’s uncommitted state is not included in its last successful backup.
nemoclaw <name> snapshot create
Create a timestamped snapshot of sandbox state.
Snapshots are stored in ~/.nemoclaw/rebuild-backups/<name>/.
The command requires shields to be down and keeps the shields check and backup under one per-sandbox transition.
An expired auto-restore timer can interrupt a long-running backup and restore lockdown.
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.
nemoclaw <name> snapshot list
List available snapshots for a sandbox as a table of version, name, timestamp, and path.
Versions (v1, v2, …) are computed on read from timestamp-ascending order, so v1 is the oldest snapshot and vN is the newest. Snapshots created before this feature landed are numbered retroactively.
nemoclaw <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) fromsnapshot 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.
When --to names an existing sandbox, restore refuses to overwrite it unless you pass --force.
With --force, NemoClaw confirms the destructive restore unless you also pass --yes or run with NEMOCLAW_NON_INTERACTIVE=1.
Use this path only when the destination sandbox can be replaced by the selected snapshot.
nemoclaw <name> share mount
Mount the sandbox filesystem on the host machine via SSHFS for bidirectional file sharing. Files edited on the host appear instantly inside the sandbox, and vice versa.
Expected output:
Prerequisites:
sshfsmust be installed on the host (sudo apt-get install sshfson Linux,brew install macfuse && brew install sshfson macOS).- The sandbox must be running.
- The remote sandbox path must exist. NemoClaw verifies it against the target sandbox before invoking
sshfsand prints aconnect, thenls <path>check when the probe fails. - Sandboxes created before the
openssh-sftp-serverbase image update must be rebuilt withnemoclaw <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.
nemoclaw <name> share unmount
Unmount a previously mounted sandbox filesystem.
nemoclaw <name> share status
Check whether the sandbox filesystem is currently mounted.
Expected output:
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.
For a remote Brev instance, SSH to the instance and run openshell term there, or use a port-forward to the gateway.
nemoclaw tunnel start
Start optional host auxiliary services.
This is the cloudflared tunnel when cloudflared is installed, which exposes the dashboard with a public URL.
Channel messaging (Telegram, Discord, Slack) is not started here; it is configured during nemoclaw onboard and runs through OpenShell-managed constructs.
By default, NemoClaw starts a Cloudflare quick tunnel and prints the generated *.trycloudflare.com URL when cloudflared reports it.
Set CLOUDFLARE_TUNNEL_TOKEN to start a Cloudflare named tunnel instead.
The named tunnel hostname and localhost:<dashboard-port> route must already be configured in the Cloudflare dashboard.
NemoClaw passes the token to cloudflared through the TUNNEL_TOKEN environment variable, so the token does not appear in the cloudflared command-line arguments.
nemoclaw start remains as a deprecated alias that prints a warning and delegates to tunnel start.
nemoclaw tunnel stop
Stop host auxiliary services that nemoclaw tunnel start started (for example cloudflared).
Use nemoclaw <name> channels stop <channel> when you only want to pause one messaging bridge.
The command asks NemoClaw to stop an in-sandbox gateway only when NemoClaw directly owns that process. Supervisor-owned agent runtime processes remain managed inside their sandbox. The command leaves agent-owned host forwards and the managed OpenShell gateway port available.
nemoclaw stop remains as a deprecated legacy full stop.
In addition to stopping tunnel services, it attempts to stop the selected agent’s host forwards when the sandbox uses a manifest-resolved non-OpenClaw agent.
It also attempts to safely release an unshared OpenShell gateway port whose ownership NemoClaw can verify.
Shared gateways remain running, and ambiguous ownership fails closed without releasing the port.
Use nemoclaw tunnel stop when the shared gateway should remain available.
nemoclaw tunnel status
Show the current cloudflared public-URL tunnel status for the selected or default sandbox dashboard.
The output reports whether cloudflared is running, stopped, or stale, and includes the same recovery hint used by nemoclaw status.
Selection honors NEMOCLAW_SANDBOX_NAME, then NEMOCLAW_SANDBOX, then SANDBOX_NAME, then the registry default.
nemoclaw start
Deprecated. Use nemoclaw tunnel start instead.
This command remains as a compatibility alias to nemoclaw tunnel start.
nemoclaw stop
Deprecated legacy full stop.
Use nemoclaw tunnel stop when the shared gateway should remain available.
This command stops tunnel services and, for a manifest-resolved non-OpenClaw agent, attempts to stop the selected agent’s host forwards.
It attempts to release the managed OpenShell gateway port only when the gateway is unshared and ownership is safely resolved; otherwise it preserves the gateway.
For manifest-resolved non-OpenClaw agents, it also requests cleanup of host-forwarding resources that nemoclaw tunnel stop leaves running.
The command is retained for compatibility with full-stop automation.
Supervisor-owned agent runtime processes remain managed inside their sandbox.
nemoclaw status
Show the global sandbox list and the status of host auxiliary services (for example cloudflared).
This command is host-wide. It summarizes registered sandboxes, the default sandbox’s live inference route, gateway health, and host services.
For gateway-based messaging agents, it also reports messaging overlap warnings.
Use nemoclaw <name> status when you need one sandbox’s live health and recovery guidance.
Pass --json for machine-readable output with registered sandboxes, service state, inference routes, and health details.
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.
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 nemoclaw 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 nemoclaw tunnel start as the recovery command.
nemoclaw inference get
Show the active live inference provider and model from the NemoClaw-managed OpenShell gateway.
Use this command when you want the direct runtime route without the rest of the sandbox status output.
It is also available in sandbox-first form as nemoclaw <name> inference get.
The sandbox-first grammar nemoclaw <name> inference get is also accepted and reads the same gateway-wide route, so it stays symmetric with nemoclaw <name> inference set.
nemoclaw inference set
Switch the active inference provider or model for a NemoClaw-managed OpenClaw sandbox.
The command updates the OpenShell gateway route, patches the selected running agent config so it matches the route, recomputes the config hash, and updates the NemoClaw registry.
It is also available in sandbox-first form as nemoclaw <name> inference set --provider <provider> --model <model>.
For OpenClaw, the patch updates the OpenClaw config provider namespace and selected model.
Same-API-family changes hot-reload without replacing the gateway process.
When the API family changes, NemoClaw commits the config and integrity hash, then uses the managed supervisor to restart only the OpenClaw gateway and verify its health and forwards.
The sandbox remains running, but agent requests are briefly interrupted.
If the restart fails, the route and config remain committed; run nemoclaw <name> gateway restart to finish applying the switch.
By default, the command syncs the default registered sandbox.
The command refuses before changing the OpenShell route when the selected sandbox has shields up.
Run nemoclaw <name> shields down, apply the inference change, then run nemoclaw <name> shields up again.
Each OpenShell gateway exposes one inference route to every sandbox registered on that gateway. Before changing the route, NemoClaw compares the requested provider and model with every same-gateway registry entry, including stopped sandboxes. Custom compatible routes must also have matching normalized endpoint URLs and API families. Provider-global credential environment-variable names must also match for the same provider name. If a route conflicts or a legacy custom route lacks enough endpoint or API-family metadata to prove compatibility, the command exits non-zero before changing the OpenShell route, agent config, or host registry and names the conflicting sandboxes. Align those sandboxes to the same route or remove a conflicting sandbox that you no longer need.
Onboarding and connect can time-share compatible provider and model routes without replacing provider-global configuration.
Refer to Use Shared Gateway Routes for the onboarding warnings, compatibility fields, and status drift report.
You can also name the sandbox in sandbox-first position instead of passing --sandbox.
nemoclaw <name> inference set --provider <provider> --model <model> targets <name> directly and is equivalent to nemoclaw inference set --provider <provider> --model <model> --sandbox <name>.
Pass both --provider and --model when you want NemoClaw to update the OpenShell inference route and sync the selected sandbox’s agent config.
NemoClaw resolves the OpenShell gateway from the target sandbox’s recorded gateway binding, including non-default NEMOCLAW_GATEWAY_PORT deployments.
Do not run openshell inference set directly on a shared NemoClaw gateway because that bypasses registry compatibility checks and can break other sandboxes.
When either flag is missing, nemoclaw inference set reports both required flags without suggesting a raw OpenShell command.
The command updates the host registry immediately after the gateway route changes.
If the in-sandbox config sync fails, NemoClaw keeps the gateway and registry aligned, warns that the running image may still need a rebuild, and points you to nemoclaw <name> rebuild.
Supported provider names are nvidia-prod, nvidia-nim, nvidia-router, openai-api, anthropic-prod, compatible-anthropic-endpoint, gemini-api, compatible-endpoint, hermes-provider, ollama-local, and vllm-local.
Use --no-verify only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential.
When switching to compatible-endpoint or compatible-anthropic-endpoint from a different provider family, pass --endpoint-url with the trusted custom provider URL and, except for the Hermes case below, --inference-api with its API family so NemoClaw can persist a complete route identity for rebuild and shared-gateway checks.
For a Hermes compatible-anthropic-endpoint target, --inference-api may be omitted because NemoClaw deterministically selects openai-completions; an explicit different API family is rejected.
NemoClaw rejects loopback, link-local, private, and internal endpoint addresses, including public hostnames that resolve to a private address.
For public HTTP URLs, NemoClaw stores the validated IP address to prevent DNS rebinding.
DNS-backed HTTPS URLs are rejected because NemoClaw cannot pin the downstream peer address while preserving TLS SNI and host validation across the OpenShell runtime boundary; HTTPS IP-literal URLs remain supported.
NemoClaw accepts http://host.openshell.internal:<port> only with an explicit port from 1024 through 65535; this narrow exception supports NemoClaw’s sandbox-to-host inference routes and is not a general private-endpoint bypass.
--credential-env may also be supplied for compatible provider metadata; supported --inference-api values are openai-completions, anthropic-messages, and openai-responses.
nemoclaw setup
The nemoclaw setup command is deprecated.
Use nemoclaw onboard instead.
This command remains as a compatibility alias to nemoclaw 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.
nemoclaw setup-spark
The nemoclaw setup-spark command is deprecated.
Use the standard installer and run nemoclaw onboard instead, because current OpenShell releases handle the older DGX Spark cgroup behavior.
This command remains as a compatibility alias to nemoclaw 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.
nemoclaw debug
Collect diagnostics for bug reports.
Gathers system info, Docker state, gateway logs, and sandbox status into a summary or tarball.
Use --sandbox <name> to target a specific sandbox, --quick for a smaller snapshot, or --output <path> to save a tarball that you can attach to an issue.
If --output is set and the tarball cannot be written (for example, the destination directory is missing or read-only), the command exits non-zero so scripts can detect the failure.
The tarball is written to a temporary sibling and renamed on success, so a pre-existing file at --output is preserved when tar fails.
When --sandbox is supplied explicitly through the flag or one of NEMOCLAW_SANDBOX_NAME, NEMOCLAW_SANDBOX, or SANDBOX_NAME, the name must match a registered sandbox.
The flag wins, then the env vars in that order.
If openshell sandbox list succeeds, the sandbox must also appear in the live gateway.
An unknown or stale name exits non-zero with an actionable error that names the sandbox and reports the source env var when applicable, and no tarball is written.
Without an explicit name, nemoclaw debug falls back to the registry’s default sandbox and warns if that default is stale.
nemoclaw credentials list
List the provider credentials registered with the OpenShell gateway. Values are not printed.
nemoclaw credentials add <PROVIDER>
Register a provider credential with the OpenShell gateway by name and type.
Each --credential takes the env variable name whose value the gateway should read; export the value first so it is not placed in argv.
Pass either repeatable --credential <ENV_NAME> or --from-existing, but do not combine them.
After the gateway accepts the provider, rebuild the target sandbox so the new provider is attached.
Registered providers attach to every sandbox you build or rebuild after the call (the gateway is one process serving all sandboxes).
If you want a provider available to only some sandboxes, scope it with nemoclaw credentials reset <PROVIDER> once those sandboxes finish using it.
nemoclaw credentials reset <PROVIDER>
Remove a provider credential from the OpenShell gateway by provider name.
After removal, re-running nemoclaw onboard re-prompts for that provider’s credential.
Run nemoclaw credentials list first if you are not sure of the provider name.
nemoclaw gc
Remove orphaned sandbox Docker images from the host.
Sandbox creation can build images in the gateway-managed openshell/sandbox-from repository or the locally prebuilt nemoclaw-sandbox-local repository.
The destroy and rebuild commands clean up the image automatically, but images from older NemoClaw versions or interrupted operations may remain.
This command lists images from both repositories, cross-references the sandbox registry, and removes any that are no longer associated with a registered sandbox.
nemoclaw 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.
NEMOCLAW_GATEWAY_PORT selects the gateway instance and state root to uninstall.
Port 8080 selects nemoclaw and the shared ~/.nemoclaw/ root; a non-default port selects nemoclaw-<port> and ~/.nemoclaw/gateways/<port>/.
For example, NEMOCLAW_GATEWAY_PORT=9123 nemoclaw uninstall selects nemoclaw-9123.
The compatibility --gateway flag cannot select another instance: when present, it must match the name derived from NEMOCLAW_GATEWAY_PORT, or uninstall exits before cleanup.
User-data preservation under ~/.nemoclaw/
To avoid uninstall destroying host-side user data, uninstall preserves the following entries in the selected gateway’s state root by default.
The default gateway uses ~/.nemoclaw/; a non-default gateway uses ~/.nemoclaw/gateways/<port>/.
When no sibling gateways remain, uninstall also removes shared host resources such as the gateway source clone, runtime state, and the Ollama auth proxy PID file. When sibling gateways remain, it removes only the selected gateway’s resources and port-scoped state while preserving those shared host resources.
--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:
The preserved entries survive uninstall as inert files on disk.
Reinstall NemoClaw and re-onboard the sandbox before nemoclaw <name> snapshot restore can use them.
Preserving sandboxes.json does not make the recorded sandboxes recoverable on their own: uninstall removes the gateway registration, provider registrations, and Docker image those records depend on.
Uninstall warns about this at preserve time.
After reinstalling, the installer reports such records as not found on their recorded gateway instead of claiming they were recovered; run nemoclaw <name> destroy to clear a stranded record, then nemoclaw onboard to rebuild it.
Pass --destroy-user-data at uninstall time if you prefer to purge the registry along with its dependencies.
nemoclaw uninstall vs. the hosted uninstall.sh
Both forms execute the same uninstall.sh with the same flags, but differ in where the script comes from and how much they trust the network.
Use nemoclaw uninstall by default.
Use the hosted curl … | bash form only when the CLI is broken or already partially removed.
Internal Commands
NemoClaw registers a hidden internal command namespace. These commands are
compatibility entrypoints for repo-owned scripts, such as the installer, the
uninstaller, DNS setup, and developer tooling. They are not part of the
supported public CLI surface.
Each command class sets hidden = true, so the commands stay out of
nemoclaw --help. They remain registered and routable, which is why they are
listed here for reference. Treat their names, flags, and output as
implementation details. They exist to back install.sh, uninstall.sh, and
related automation, and they may change or be removed without notice. Most run
indirectly through those scripts rather than being typed by hand.
For contributor guidance on how these command files are structured, refer to
src/commands/internal/README.md.
These commands do not appear in the command-level parity check, which compares
nemoclaw --help against the public command headings in this reference; hidden
commands are excluded from both. The table above is the canonical reference for
the family.
Environment Variables
NemoClaw reads the following environment variables to configure service ports, onboarding behavior, and lifecycle defaults.
Set them before running nemoclaw onboard or any command that starts services.
All ports must be non-privileged integers between 1024 and 65535.
CLI Logging
The centralized CLI logger writes its output to stderr and uses info verbosity by default.
These controls affect leveled logger output; they do not suppress command results or command-specific output that has not migrated to the centralized logger.
The environment precedence is NEMOCLAW_LOG_LEVEL, then NEMOCLAW_DEBUG, followed by the default info level.
The error level prints errors only, warn also prints warnings, info also prints informational messages, and debug prints all levels with timestamps.
Use these NemoClaw-specific variables instead of the generic DEBUG variable. DEBUG is not a NemoClaw logger control and can enable dependency diagnostics that include raw command arguments.
Commands whose parser owns the base logging options also accept the hidden long-form --debug and --quiet flags, even though these options do not appear in command help.
The flags are mutually exclusive.
--debug overrides the environment-derived threshold and selects debug, while --quiet caps verbosity at warn without increasing an environment-derived error threshold.
There is no global -q logging shorthand.
Passthrough commands do not consume flags intended for the downstream command as host logging options, so use the environment variables when you need unambiguous host logging around a passthrough invocation.
If a port value is not a valid integer or falls outside the allowed range, the CLI exits with an error.
NEMOCLAW_GATEWAY_PORT also cannot overlap configured service, vLLM, Ollama, Ollama proxy, or OpenRouter runtime adapter ports, and cannot use reserved auto-allocation ranges or the default inference/proxy ports 8000, 11434, 11435, and 11437.
When you select OpenRouter, NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT must also be distinct from the gateway, vLLM, Ollama, and Ollama proxy ports.
When you run multiple NemoClaw gateways with different NEMOCLAW_GATEWAY_PORT values, NemoClaw derives a separate gateway name, state directory, and compatibility container name from the port so one gateway does not tear down another.
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.85 reject 0.0.0.0 while gateway JWT auth is active.
Keep the OpenShell gateway on loopback and use NEMOCLAW_DASHBOARD_BIND when you need remote browser/API access.
NEMOCLAW_DASHBOARD_BIND controls the dashboard or API port forward bind address.
Outside WSL, the forward stays on 127.0.0.1 (loopback only) by default.
On WSL, NemoClaw binds the host-side forward on all interfaces so the Windows host can reach it, while the ready summary continues to print a loopback dashboard URL.
On non-WSL SSH-deployed hosts, set NEMOCLAW_DASHBOARD_BIND=0.0.0.0 before nemoclaw onboard to prepare the sandbox for remote exposure and bind the forward on all interfaces.
Use the same setting for later nemoclaw <sandbox> connect calls.
A sandbox created without this opt-in must be recreated with NEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemoclaw onboard --recreate-sandbox before a remote-bind connect is allowed.
Only 0.0.0.0 enables the remote bind; onboarding rejects any other non-empty value.
When the remote bind is opted in, the dashboard auth flow accepts non-loopback origins.
These overrides apply to onboarding, status checks, health probes, and the uninstaller.
Defaults are unchanged when no variable is set.
If NEMOCLAW_DASHBOARD_PORT or the port from CHAT_UI_URL is already occupied by another sandbox, onboarding scans 18789 through 18799 and uses the next free dashboard port.
Pass --control-ui-port <N> to require a specific port.
For OpenClaw, NEMOCLAW_DASHBOARD_PORT controls the OpenClaw dashboard forward.
Onboarding Configuration
The following variables let you tune onboarding without editing the Dockerfile or passing repeated flags.
Set them before running nemoclaw onboard.
OpenClaw-specific onboarding configuration:
Extra OpenClaw agents
Set NEMOCLAW_EXTRA_AGENTS_JSON to either a JSON array of secondary-agent entries, or an object payload of the form {"agents": [...], "defaults": {...}, "main": {...}}, to bake them into agents.list[] at image build time.
Each entry must declare id and tools; workspace, agentDir, subagents, description, and model are optional.
The generator always writes the canonical main entry first with default: true, so secondary agents cannot displace the primary agent.
Malformed JSON or invalid entries fail the image build with a structured error.
Field rules:
idmust match^[a-z][a-z0-9_-]{0,31}$and must not bemain.workspacedefaults to/sandbox/.openclaw/workspace-<id>; when set, it must be an absolute path that resolves to that value.agentDirdefaults to/sandbox/.openclaw/agents/<id>; when set, it must be an absolute path that resolves to that value.toolsmust declare a non-emptyallow[]ordeny[]; nothing is implicitly granted.model, when set, must be a"provider/model"string whose provider portion matches the primary onboard provider.default: trueis rejected because the primary agent is the only default.- Allowed entry fields:
id,workspace,agentDir,tools,subagents,description,model. Any other key fails the image build (no implicit credential or env pass-through). - Allowed
toolsfields:profile,allow,deny. Allowed per-agentsubagentsfields:delegationMode,allowAgents,model,thinking,requireAgentId. Any other nested key fails the image build.
OpenClaw accepts subagents.maxSpawnDepth only on agents.defaults.subagents, never inside a per-agent subagents object.
The value must be an integer between 1 and 5 (OpenClaw’s accepted range); to set it, use the object payload shape and pass it under defaults:
Array-shape example (paths defaulted):
Linux Ollama install mode details
Set NEMOCLAW_OLLAMA_INSTALL_MODE=system to run the official https://ollama.com/install.sh installer, which uses sudo, writes to /usr/local, and configures systemd.
Set NEMOCLAW_OLLAMA_INSTALL_MODE=user to extract the release tarball to ${HOME}/.local without sudo and launch the daemon manually without systemd persistence.
Leave NEMOCLAW_OLLAMA_INSTALL_MODE empty or unset to let NemoClaw auto-detect the mode.
Auto-detection selects system when the current user is root or passwordless sudo works.
Auto-detection selects user in non-interactive runs without passwordless sudo.
An interactive shell falls back to system so the official installer can prompt for the password.
NemoClaw rejects any other value.
On upgrades, NemoClaw rejects user because a user-local install cannot replace the system daemon on :11434.
On upgrades, NemoClaw also rejects system under NEMOCLAW_NON_INTERACTIVE=1 when passwordless sudo is unavailable because the installer would hang on a hidden sudo prompt.
The run exits with an actionable diagnostic instead.
Onboarding Behavior Flags
The following flags toggle optional behaviors during onboarding.
Set them before running nemoclaw onboard.
Set NEMOCLAW_SANDBOX_BASE_IMAGE_REF to an OpenClaw sandbox-base tag or digest to override base-image resolution during onboarding.
Use a release-matched tag or immutable digest for a source-based custom image; NemoClaw resolves the reference and pins a repository digest into a stock-style ARG BASE_IMAGE declaration when possible.
Onboard Profiling Traces
Set NEMOCLAW_TRACE=1 before nemoclaw 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.
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.
OpenClaw Conversation OTEL Diagnostics
Set NEMOCLAW_OPENCLAW_OTEL=1 before onboarding or rebuilding an OpenClaw sandbox to enable runtime conversation traces through OpenClaw’s diagnostics-otel plugin.
This is separate from NEMOCLAW_TRACE, which records NemoClaw onboarding phases to a local JSON file.
NemoClaw configures OpenClaw for OTLP/HTTP protobuf traces only by default: metrics and logs are disabled, and prompt/tool content capture is not enabled.
For a local Jaeger collector:
Onboarding automatically applies the openclaw-diagnostics-otel-local preset at sandbox create and again during the policy step when NEMOCLAW_OPENCLAW_OTEL=1, so OTLP export is allowed before the gateway’s first trace flush. If you enabled OTEL after an existing sandbox was created, run nemoclaw <sandbox-name> policy-add openclaw-diagnostics-otel-local --yes or recreate the sandbox with OTEL enabled at build time.
Then open http://localhost:16686 and select the openclaw-gateway service.
The built-in openclaw-diagnostics-otel-local preset allows only POST /v1/traces (and subpaths) to host.openshell.internal:4318 from openclaw and node.
For a remote collector, create a custom preset for the collector host and port instead of using the local host-gateway preset.
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.
Onboard Timeouts
The following environment variables tune onboard-time wall-clock limits.
Set them before running nemoclaw onboard if a slow connection or large model pull risks tripping the default.
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 nemoclaw onboard starts clean.
Lifecycle Behavior Flags
The following flags change defaults for commands that manage existing sandboxes.
Remote Deployment
The following variables seed defaults for nemoclaw deploy and nemoclaw onboard --remote, which provision a sandbox on a Brev instance.
Each has a flag equivalent on deploy; the env var lets non-interactive runs skip the prompt.
For narrative how-to coverage of NEMOCLAW_BREV_PROVIDER and NEMOCLAW_GPU, refer to Deploy to Remote GPU.
Legacy nemoclaw setup
Deprecated. Use nemoclaw onboard instead.
Running nemoclaw setup now delegates directly to nemoclaw onboard.