diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md index 8676c24ee82..634b4c6c43e 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -53,7 +53,7 @@ The managed install/start vLLM entry appears by default on DGX Spark and DGX Sta | Option | Description | Curated models | |--------|-------------|----------------| -| NVIDIA Endpoints | Routes to models hosted on [build.nvidia.com](https://build.nvidia.com). You can also enter any model ID from the catalog. Set `NVIDIA_API_KEY`. | Nemotron 3 Super 120B, Nemotron 3 Ultra 550B, GLM-5.1, MiniMax M2.7, GPT-OSS 120B, DeepSeek V4 Pro | +| NVIDIA Endpoints | Routes to models hosted on [build.nvidia.com](https://build.nvidia.com). You can also enter any model ID from the catalog. Set `NVIDIA_INFERENCE_API_KEY`. | Nemotron 3 Super 120B, Nemotron 3 Ultra 550B, GLM-5.1, MiniMax M2.7, GPT-OSS 120B, DeepSeek V4 Pro | | OpenAI | Routes to the OpenAI API. Set `OPENAI_API_KEY`. | `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.4-pro-2026-03-05` | | Other OpenAI-compatible endpoint | Routes to any server that implements `/v1/chat/completions`. NemoClaw uses `/v1/chat/completions` at runtime by default; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` for proxies that implement it, such as some llama.cpp builds. The wizard prompts for a base URL and model name. Works with OpenRouter, LocalAI, llama.cpp, or any compatible proxy. When you enable Telegram messaging, onboarding also runs a bounded sandbox-side smoke check through `https://inference.local/v1/chat/completions`. Set `COMPATIBLE_API_KEY`. | You provide the model name. | | Anthropic | Routes to the Anthropic Messages API. Set `ANTHROPIC_API_KEY`. | `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-6` | @@ -98,12 +98,12 @@ models: - name: nano litellm_model: "openai/nvidia/nvidia/Nemotron-3-Nano-30B-A3B" cost_per_m_input_tokens: 0.05 - api_base: "https://inference-api.nvidia.com" + api_base: "https://integrate.api.nvidia.com" - name: super - litellm_model: "openai/nvidia/nvidia/nemotron-3-super-v3" + litellm_model: "openai/nvidia/nemotron-3-super-120b-a12b" cost_per_m_input_tokens: 0.10 - api_base: "https://inference-api.nvidia.com" + api_base: "https://integrate.api.nvidia.com" ``` The `tolerance` parameter controls the accuracy-cost tradeoff. @@ -127,7 +127,7 @@ The sandbox never sees raw API keys. To use the router in scripted setup, set: ```bash -NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive +NEMOCLAW_PROVIDER=routed NVIDIA_INFERENCE_API_KEY= nemoclaw onboard --non-interactive ``` ### Host Python Requirement @@ -171,7 +171,7 @@ For setup instructions, refer to [Use a Local Inference Server](../SKILL.md). NemoClaw validates the selected provider and model before creating the sandbox. If credential validation fails, the wizard asks whether to re-enter the API key, choose a different provider, retry, or exit. The wizard retries transient upstream validation failures before it reports a provider failure. -The `nvapi-` prefix check applies only to `NVIDIA_API_KEY`. +The `nvapi-` prefix check applies only to `NVIDIA_INFERENCE_API_KEY`. Other provider credentials, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, and compatible endpoint keys, use provider-aware validation during retry. | Provider type | Validation method | @@ -369,6 +369,20 @@ NEMOCLAW_PROVIDER=install-vllm \ NemoClaw accepts `HUGGING_FACE_HUB_TOKEN` as an alternative. The token check runs on the host before any docker pull, so a missing or empty token aborts onboarding before bandwidth is spent on a 401. +### Add Managed-vLLM Serve Arguments + +For advanced vLLM options that are not in the NemoClaw registry yet, export `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` as a JSON array of individual non-blank `vllm serve` tokens. +NemoClaw trims and validates the array before pulling images or downloading models, shell-quotes each token, and appends the tokens after the registry defaults. + +```bash +NEMOCLAW_PROVIDER=install-vllm \ + NEMOCLAW_VLLM_EXTRA_ARGS_JSON='["--max-num-seqs","2","--disable-log-requests"]' \ + nemoclaw onboard --non-interactive +``` + +Use this for operator-owned tuning only. +If the selected vLLM image does not support an argument, the managed container exits and NemoClaw prints the vLLM log tail. + ## NVIDIA NIM (Experimental) NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable NVIDIA GPU. @@ -390,7 +404,7 @@ NVIDIA hosts NIM container images on `nvcr.io`, and `docker pull` requires NGC r If Docker is not already logged in to `nvcr.io`, onboard prompts for an [NGC API key](https://org.ngc.nvidia.com/setup/api-key) and runs `docker login nvcr.io` over `--password-stdin` so the key is never written to disk or shell history. The prompt masks the key during input and retries one time on a bad key before failing. In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemoclaw onboard --non-interactive`. -If `NGC_API_KEY` or `NVIDIA_API_KEY` is already exported, NemoClaw passes it into the managed NIM container through the process environment instead of command-line arguments. +If `NGC_API_KEY` or `NVIDIA_INFERENCE_API_KEY` is already exported, NemoClaw passes it into the managed NIM container through the process environment instead of command-line arguments. If the NIM container exits before the health endpoint becomes ready, onboarding stops early and prints the last container log lines. After NIM becomes healthy, NemoClaw reads `/v1/models` and uses the served model id for validation when it differs from the catalog name. Unsafe served ids are rejected instead of being written into the sandbox config. diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md b/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md index 23f9b612926..a6e1133cabf 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md @@ -92,6 +92,19 @@ In the Omni demo, the OpenClaw gateway runs as `/usr/local/bin/node`, so the NVI Refer to Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for policy update workflows. +## Sub-Agent Gateway Connectivity + +Spawned sub-agents connect back to the OpenClaw gateway over WebSocket at `OPENCLAW_GATEWAY_URL`. +Inside the sandbox this connection runs through the enforced process tree, where the OpenShell proxy always blocks loopback destinations. +NemoClaw therefore points `OPENCLAW_GATEWAY_URL` at the sandbox's own interface address (for example `ws://10.200.0.2:18790`) and allowlists that endpoint in the base sandbox policy (`openclaw_gateway_dialback`). + +If `sessions_spawn` returns `gateway closed (1006 abnormal closure (no close frame))` and the gateway log shows no connection attempt, the dial-back path is blocked. +Check the following: + +1. `OPENCLAW_GATEWAY_URL` in the gateway process environment targets the sandbox interface address, not `127.0.0.1`. +2. The active policy allows that address and port. Custom `NEMOCLAW_DASHBOARD_PORT` or proxy subnet values need a matching `openshell policy update`. +3. Do not point the dial-back at `127.0.0.1` — the proxy denies loopback regardless of policy. + ## Add Delegation Instructions OpenClaw handles `sessions_spawn`, but the primary agent still needs task instructions. diff --git a/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md b/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md index 26dc213e61b..5d69d5ea04c 100644 --- a/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md +++ b/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md @@ -44,7 +44,7 @@ That directory is created with mode `0700` and contains no credential material. When a NemoClaw command needs a credential value during a single run (for example to forward it to an `openshell provider` registration), it reads from `process.env` first. This means you can: -- Prefix any command with the credential to override the gateway-stored value: `NVIDIA_API_KEY=nvapi-... nemoclaw onboard` +- Prefix any command with the credential to override the gateway-stored value: `NVIDIA_INFERENCE_API_KEY=nvapi-... nemoclaw onboard` - Use short-lived or rotated credentials in CI by exporting them once per pipeline run - Avoid registering credentials in the gateway entirely if your environment supplies them @@ -57,7 +57,7 @@ Export the credential only when you want to create, replace, or rotate the store A typical deploy invocation looks like: ```bash -NVIDIA_API_KEY=nvapi-... \ +NVIDIA_INFERENCE_API_KEY=nvapi-... \ HF_TOKEN=hf_... \ TELEGRAM_BOT_TOKEN=... \ nemoclaw deploy my-instance @@ -98,7 +98,7 @@ If `~/.nemoclaw/credentials.json` remains after a rebuild or other credential lo The simplest way to replace a stored value is to rerun onboarding with the new value in your environment: ```bash -NVIDIA_API_KEY=nvapi-new-value nemoclaw onboard +NVIDIA_INFERENCE_API_KEY=nvapi-new-value nemoclaw onboard ``` To remove a credential from the gateway entirely: diff --git a/.agents/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md b/.agents/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md index 6f8e721920b..272bd831230 100644 --- a/.agents/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md +++ b/.agents/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md @@ -55,6 +55,48 @@ nemoclaw onboard --from ./my-plugin-sandbox/Dockerfile If you need a second sandbox alongside an existing one, use a dedicated build directory and rerun onboarding with the sandbox name and ports you intend to use. +## Build Performance + +Custom plugin images are normal Docker builds, so build time depends on the build context size and the Docker layer cache rather than on NemoClaw. + +Keep the build context small and dedicated. +The Dockerfile's parent directory is staged as the build context before the Docker build starts, so a broad directory can make onboarding look stuck while Docker is only preparing context. +A small build directory stages quickly: + +```text +my-plugin-sandbox/ # fast: only what the image needs +├── Dockerfile +├── .dockerignore +└── my-plugin/ +``` + +A Dockerfile placed in a large tree stages slowly: + +```text +~/ # slow: stages the whole home directory +├── Dockerfile +├── Downloads/ +├── datasets/ +└── models/ +``` + +Distinguish cold builds from warm rebuilds. +The first build on a fresh host is a cold build that downloads the base image and package indexes, so it is the slowest run. +Later warm rebuilds reuse cached layers when the base image and earlier layers are unchanged. + +Order Dockerfile instructions from least-changing to most-changing so warm rebuilds reuse cached dependency layers: + +1. Base image. +2. System package installs. +3. Dependency manifests such as `package.json`. +4. Dependency install such as `npm ci`. +5. Application source. + +Pin the base image to an explicit tag or digest so warm rebuilds resolve the same cached base instead of pulling a new one. + +When a build feels slow, set `NEMOCLAW_TRACE=1` before onboarding to capture phase timings that separate context staging, Docker build, image upload, and sandbox readiness. +For the full `--from` build-context rules and trace details, refer to CLI Commands Reference (use the `nemoclaw-user-reference` skill). + ## Network Access Plugins still run inside the sandbox policy boundary. diff --git a/.agents/skills/nemoclaw-user-get-started/SKILL.md b/.agents/skills/nemoclaw-user-get-started/SKILL.md index 3056b491cd5..0447987d369 100644 --- a/.agents/skills/nemoclaw-user-get-started/SKILL.md +++ b/.agents/skills/nemoclaw-user-get-started/SKILL.md @@ -115,7 +115,7 @@ A configured blueprint router profile makes the Model Router option appear. **Tip:** Export the API key before launching the installer so the wizard does not have to ask for it. -For example, run `export NVIDIA_API_KEY=` before `curl ... | bash`. +For example, run `export NVIDIA_INFERENCE_API_KEY=` before `curl ... | bash`. If you entered a key incorrectly, refer to Reset a Stored Credential (use the `nemoclaw-user-manage-sandboxes` skill) to clear and re-enter it. ### Choose an Inference Provider @@ -126,14 +126,14 @@ For Ollama, vLLM, NIM, and compatible local servers, refer to Use a Local Infere | Option | Use when | Credential variable | |---|---|---| -| NVIDIA Endpoints | You want hosted models from `build.nvidia.com`, including hosted Nemotron models. | `NVIDIA_API_KEY` | +| NVIDIA Endpoints | You want hosted models from `build.nvidia.com`, including hosted Nemotron models. | `NVIDIA_INFERENCE_API_KEY` | | OpenAI | You want the OpenAI API at `https://api.openai.com/v1`. | `OPENAI_API_KEY` | | Other OpenAI-compatible endpoint | You have OpenRouter, LocalAI, llama.cpp, vLLM, NIM, SGLang, an enterprise gateway, or another `/v1/chat/completions` endpoint. | `COMPATIBLE_API_KEY` | | Anthropic | You want the Anthropic Messages API. | `ANTHROPIC_API_KEY` | | Other Anthropic-compatible endpoint | You have a Claude proxy, Bedrock-compatible gateway, or self-hosted `/v1/messages` endpoint. | `COMPATIBLE_ANTHROPIC_API_KEY` | | Google Gemini | You want Google's OpenAI-compatible Gemini endpoint. | `GEMINI_API_KEY` | | Local Ollama | You want a host-local Ollama model. | None | -| Model Router | You want NemoClaw to start the host-side model router. | `NVIDIA_API_KEY` | +| Model Router | You want NemoClaw to start the host-side model router. | `NVIDIA_INFERENCE_API_KEY` | Export the relevant key before launching the installer when possible. If your compatible endpoint does not require authentication, set its credential variable to any non-empty placeholder. diff --git a/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md b/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md index b080ffea60b..e4737e98f01 100644 --- a/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md +++ b/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md @@ -82,7 +82,7 @@ export NEMOCLAW_AGENT=hermes export NEMOCLAW_NON_INTERACTIVE=1 export NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 export NEMOCLAW_SANDBOX_NAME=my-hermes -export NVIDIA_API_KEY= +export NVIDIA_INFERENCE_API_KEY= curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` @@ -90,9 +90,9 @@ Use the provider variables from Inference Options (use the `nemoclaw-user-config ## Connect to Hermes -When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle commands, and Hermes dashboard URL. +When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle commands, the Hermes dashboard URL, and the OpenAI-compatible API URL. Hermes exposes its built-in browser dashboard on port `18789`. -NemoClaw also forwards the OpenAI-compatible API on port `8642` for local clients. +NemoClaw also forwards the OpenAI-compatible API on port `8642` for local clients, and the summary now announces both URLs. NemoClaw builds the Hermes dashboard assets into the sandbox image, so the dashboard starts without running `npm` as the sandbox user under `/opt/hermes`. Dashboard chat uses the prebuilt `/opt/hermes/ui-tui` bundle. If you need to recover the Hermes dashboard manually, use `hermes dashboard --tui --skip-build` so recovery does not try to rebuild assets under root-owned install paths. @@ -111,6 +111,10 @@ Access Port 18789 must be forwarded before opening this URL. http://127.0.0.1:18789/ + Hermes Agent OpenAI-compatible API + Port 8642 must be forwarded before connecting. + http://127.0.0.1:8642/v1 + Terminal: nemohermes my-hermes connect diff --git a/.agents/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md b/.agents/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md index 6c97de9f7c9..df42ed7fd18 100644 --- a/.agents/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md +++ b/.agents/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md @@ -53,7 +53,8 @@ From the NemoClaw repository root, run the walkthrough script after you have onb ``` This script opens a split tmux session with the TUI on the left and the agent on the right. -The walkthrough requires tmux and the `NVIDIA_API_KEY` environment variable, and it assumes an existing sandbox to attach to. +The walkthrough requires tmux and the `NVIDIA_INFERENCE_API_KEY` environment variable. +It assumes an existing sandbox to attach to. ## Related Topics diff --git a/.agents/skills/nemoclaw-user-overview/references/release-notes.md b/.agents/skills/nemoclaw-user-overview/references/release-notes.md index feb9e3ec372..990bc98b990 100644 --- a/.agents/skills/nemoclaw-user-overview/references/release-notes.md +++ b/.agents/skills/nemoclaw-user-overview/references/release-notes.md @@ -6,6 +6,17 @@ NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use this page to track the highlights of the latest release. For more detailed release notes, refer to the [NemoClaw GitHub announcements](https://github.com/NVIDIA/NemoClaw/discussions/categories/announcements?discussions_q=is%3Aopen+category%3AAnnouncements). +## v0.0.65 + +NemoClaw v0.0.65 improves gateway recovery, sandbox state restore, local inference setup, and messaging activation: + +- Gateway and sandbox recovery now wait for sustained serving state, recover sandboxes whose active gateway has lost its spec, preserve gateway routing state across more rebuilds, and allocate dashboard ports across multiple NemoClaw gateways. For more information, refer to Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill) and Troubleshooting (use the `nemoclaw-user-reference` skill). +- Rebuild and restore flows preserve more OpenClaw and registry state. Config restore fails closed when a merge cannot be applied safely, reporter-owned model metadata survives rebuild restore, Shields auto-restore locks are re-confirmed after settle, and persisted agents survive registry recovery. For more information, refer to Backup and Restore (use the `nemoclaw-user-manage-sandboxes` skill) and NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- Onboarding and inference setup fail earlier with clearer diagnostics. NemoClaw now handles Docker Desktop WSL CDI injection failures, surfaces silent OpenClaw runtime fallback, preflights managed vLLM model selection before side effects, accepts managed vLLM extra serve arguments, bounds compatible-endpoint probes, summarizes inference validation failures, and recomputes context windows after runtime model switches. For more information, refer to Troubleshooting (use the `nemoclaw-user-reference` skill), NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill), and Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill). +- Day-two CLI operations gained safer file and session workflows. `nemoclaw download`, `nemoclaw upload`, and `nemoclaw sessions export` wrap the underlying sandbox file transfer and OpenClaw session export paths, while uninstall handles TTY confirmation and model-router teardown more predictably. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill) and Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill). +- Messaging activation stores and exposes less credential-adjacent state. NemoClaw avoids logging WeChat QR poll tokens, resolves Discord per-account proxy settings for gateway WebSocket connections, compacts persisted messaging plans, completes manifest-based channel migration, and removes provider credential hashes from sandbox registry entries. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) and Credential Storage (use the `nemoclaw-user-configure-security` skill). +- Hermes defaults and sandbox compatibility are narrower and easier to recover. The Hermes baseline policy no longer includes GitHub by default, NemoClaw reserves Hermes port `8642` across agent variants, and spawned OpenClaw sub-agents dial back through the sandbox interface instead of blocked loopback paths. For more information, refer to Network Policies (use the `nemoclaw-user-reference` skill), NemoClaw Quickstart with Hermes (use the `nemoclaw-user-get-started` skill), and Set Up Task-Specific Sub-Agents (use the `nemoclaw-user-configure-inference` skill). + ## v0.0.64 NemoClaw v0.0.64 improves sandbox restore, onboarding stability, inference routing, messaging setup, and release validation: @@ -14,7 +25,6 @@ NemoClaw v0.0.64 improves sandbox restore, onboarding stability, inference routi - OpenClaw onboarding keeps Brave Search pinned to the NemoClaw-managed runtime and preserves the `BRAVE_API_KEY` placeholder through build doctor. Docker-driver gateway health checks now follow the entrypoint path that actually launches the in-container gateway, which avoids misleading health reports on host-gateway setups. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). - Inference routes choose chat completions for providers that do not expose `/v1/responses`, including NVIDIA Endpoints, NVIDIA NIM, and Gemini-compatible routes. NemoClaw also adds a targeted Nemotron Ultra 550B compatibility fix for tool-less requests. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill). - Messaging setup refreshes stale render plans during rebuild, recovers replaced OpenClaw scope-upgrade approvals, and preinstalls Hermes WhatsApp bridge dependencies when the upstream lockfile is present. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). -- Release validation expands live Vitest coverage for rebuild, sandbox operations, network policy, credential migration, inference routing, Hermes, WhatsApp QR, dashboard binding, VM driver, docs validation, token rotation, and launch smoke paths. ## v0.0.63 @@ -124,7 +134,7 @@ NemoClaw v0.0.54 updates messaging activation, Windows WSL onboarding, NemoHerme - The Windows bootstrap flow waits for Ubuntu account creation before touching Docker settings, enables Docker Desktop WSL integration for the target distro, avoids changing the global WSL default distro, and adds WSL-specific Docker reachability hints during onboarding. For more information, refer to Prepare Windows for NemoClaw. - Windows-host Ollama setup inside WSL now requires the Docker Desktop WSL integration path. NemoClaw still shows Windows-host Ollama options when it detects them, but labels the Docker Desktop requirement and blocks unsupported native Docker-in-WSL selections before it tries to start or install Ollama. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). - NemoHermes can expose the optional native Hermes web dashboard separately from the OpenAI-compatible API. Set `NEMOCLAW_HERMES_DASHBOARD=1` before onboarding to start and forward the dashboard on port `9119`, with `NEMOCLAW_HERMES_DASHBOARD_PORT` and `NEMOCLAW_HERMES_DASHBOARD_TUI` available for port and TUI tab control. For more information, refer to NemoClaw Quickstart with Hermes. -- Onboarding diagnostics include more copy-paste-ready recovery hints. Invalid sandbox names now include a `Try: ` line when NemoClaw can derive a valid name, and non-interactive NVIDIA Endpoints setup prints the exact `export NVIDIA_API_KEY=nvapi-...` shape when the key is missing. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- Onboarding diagnostics include more copy-paste-ready recovery hints. Invalid sandbox names now include a `Try: ` line when NemoClaw can derive a valid name, and non-interactive NVIDIA Endpoints setup prints the exact `export NVIDIA_INFERENCE_API_KEY=nvapi-...` shape when the key is missing. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). - Homebrew stays on the Linuxbrew prefix while exposing installed formula commands in sandbox shell sessions, the `/nemoclaw` slash command activates at OpenClaw startup again, Hermes rebuilds tolerate older release tarballs that lack optional UI package lockfiles, and device scope-upgrade approvals recover without being pinned to the old gateway-scoped request. For more information, refer to Common NemoClaw Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill). - The host-gateway allowance for OpenClaw `web_fetch` is confined to the trusted proxy path, while strict and direct paths continue to block host-gateway names. Hermes Provider onboarding skips the host-side smoke probe only for OAuth-backed setup and keeps direct validation for Nous API key setup. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill). @@ -320,7 +330,7 @@ NemoClaw v0.0.39 improves several day-two workflows: - `nemoclaw destroy` preserves the shared gateway by default unless `--cleanup-gateway` is selected. - `nemoclaw connect` repairs stale `inference.local` DNS proxy routes before opening the session. - Windows-host Ollama onboarding relaunches the daemon with the reachable binding after install or restart. -- Local NVIDIA NIM onboarding passes `NGC_API_KEY` or `NVIDIA_API_KEY` into the managed container without putting the secret in process arguments, detects early container exits during health checks, and prints a per-GPU preflight breakdown on mixed-model hosts. +- Local NVIDIA NIM onboarding passes `NGC_API_KEY` or `NVIDIA_INFERENCE_API_KEY` into the managed container without putting the secret in process arguments, detects early container exits during health checks, and prints a per-GPU preflight breakdown on mixed-model hosts. - The sandbox startup path strips additional Linux capabilities before and during privilege step-down. - OpenClaw workspace template files are seeded when bootstrap is skipped and the workspace is still empty. - Kimi K2.6 and related NVIDIA-hosted chat-completions paths include model-specific compatibility handling for reasoning output. diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md index 6b9d7de6979..338cbeb2dbf 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands.md +++ b/.agents/skills/nemoclaw-user-reference/references/commands.md @@ -332,6 +332,7 @@ NemoClaw also applies additional secret-safety exclusions that override `.docker 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. ```bash @@ -350,6 +351,18 @@ build-dir/ └── files-used-by-COPY/ ``` +For faster custom builds, plan for Docker cache behavior: + +- Treat the first build on a fresh host as a cold build. + Cold builds download the base image and package indexes, so they take longer than later warm rebuilds even when NemoClaw is healthy. +- A warm rebuild reuses cached layers when the base image and earlier layers are unchanged, so it is much faster than the first build. +- Order Dockerfile instructions from least-changing to most-changing: base image, system packages, dependency manifests, dependency install, then application source. + This lets warm rebuilds reuse cached dependency layers instead of reinstalling on every source change. +- Pin the base image to an explicit tag or digest so warm rebuilds resolve the same cached base instead of pulling a new one. + +To diagnose where a slow build spends time, set `NEMOCLAW_TRACE=1` and read the phase timings in [Onboard Profiling Traces](#onboard-profiling-traces). +NemoClaw does not guarantee exact build timings. + All NemoClaw build arguments (`NEMOCLAW_MODEL`, `NEMOCLAW_PROVIDER_KEY`, `NEMOCLAW_INFERENCE_BASE_URL`, etc.) are injected as `ARG` overrides at build time, so declare them in your Dockerfile if you need to reference them. In non-interactive mode, the path can also be supplied via the `NEMOCLAW_FROM_DOCKERFILE` environment variable. @@ -453,9 +466,9 @@ Set `NEMOCLAW_NO_CONNECT_HINT=1` to suppress the hint in scripted workflows. If the sandbox is running an outdated agent version, a non-blocking warning prints before connecting with a `nemoclaw rebuild` hint. If another terminal is already connected to the sandbox, `connect` prints a note with the number of existing sessions before proceeding. Multiple concurrent sessions are allowed. -`connect` does not pull or serve a model itself, but it does inspect `NEMOCLAW_VLLM_MODEL` if you exported it for the managed-vLLM install path. -An unknown slug 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 variable, or supply the missing token, before retrying. +`connect` does not pull or serve a model itself, but it does inspect managed-vLLM install variables such as `NEMOCLAW_VLLM_MODEL` and `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` if you exported them in the same shell. +An unknown model slug, malformed extra-args JSON, or a gated model (for example `deepseek-r1-distill-70b`) with no `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN` exits non-zero with the same error the installer would emit, before any sandbox readiness probe or SSH attach. +Unset the managed-vLLM variable, or fix the value, before retrying. When the live OpenShell gateway inference route differs from the route recorded in the NemoClaw registry, `connect` prints an explicit warning and realigns the shared gateway to the recorded route. Use `nemoclaw inference set --provider --model ` to make an intentional route change. @@ -508,6 +521,43 @@ The exit code is the remote command's exit code. | `--tty` / `--no-tty` | Allocate a pseudo-terminal; defaults to auto-detection (on when stdin and stdout are terminals) | | `--timeout ` | Timeout in seconds (`0` means no timeout) | +### `nemoclaw agent` + +Run one OpenClaw agent turn non-interactively in a running sandbox. +This command forwards every argument verbatim to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. +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 in-sandbox OpenClaw CLI are forwarded verbatim, so the upstream surface stays the single source of truth. + +```bash +nemoclaw my-assistant agent -m "Summarise README.md" +nemoclaw my-assistant agent --agent work -m "Status update?" +nemoclaw my-assistant agent --session-id review-42 -m "Any new findings?" +nemoclaw my-assistant agent --json -m 'ping' +``` + +The wrapper inherits the remote command's exit code, so host-side pipelines can branch on it. Streaming forwards whatever `openclaw agent` already emits on `stdout`; the wrapper adds no buffering. + +Common upstream flags include `-m `, `--session-id `, `--agent `, `--model `, `--thinking `, `--json`, `--deliver`, `--reply-channel `, and `--timeout `. Run `nemoclaw agent --help` for the wrapper-level summary, or invoke `nemoclaw exec -- openclaw agent --help` to view the upstream OpenClaw help text directly. + + + + +Only OpenClaw sandboxes support the `agent` wrapper today; Hermes sandboxes already expose an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. + +Forward the port and POST chat completions directly: + +```bash +openshell forward start --background 8642 my-hermes +curl -sN http://127.0.0.1:8642/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -d '{"model":"","messages":[{"role":"user","content":"What is 2+2?"}],"stream":true}' +``` + + + ### 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. @@ -1895,6 +1945,7 @@ All ports must be non-privileged integers between 1024 and 65535. | `NEMOCLAW_OLLAMA_PORT` | 11434 | Ollama inference | | `NEMOCLAW_OLLAMA_PROXY_PORT` | 11435 | Ollama auth proxy | | `NEMOCLAW_DASHBOARD_BIND` | *unset* (loopback) | Dashboard or API forward bind address. Set to `0.0.0.0` to opt in to remote bind for SSH-deployed hosts. | +| `NEMOCLAW_GATEWAY_WS_HOST` | *unset* (auto-derived inside the sandbox; loopback elsewhere) | Host used for the in-sandbox `OPENCLAW_GATEWAY_URL`; inside the sandbox it defaults to the primary interface address so `sessions_spawn` sub-agents can dial the gateway through the enforced network path. | 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 the configured dashboard, vLLM, Ollama, or Ollama proxy ports, and cannot use the dashboard auto-allocation range `18789` through `18799` or the default inference/proxy ports `8000`, `11434`, and `11435`. @@ -1974,6 +2025,7 @@ Set them before running `nemoclaw onboard`. | `NEMOCLAW_INSTALL_REF` | git ref | For internal installer commands: the git ref to install from. Overridden by the `--install-ref` flag. | | `NEMOCLAW_INSTALL_TAG` | release tag | For internal installer commands: the release tag to install. Defaults to the admin-promoted `lkg` tag when unset. Overridden by the `--install-tag` flag. | | `NEMOCLAW_VLLM_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `deepseek-v4-flash`, `deepseek-r1-distill-70b`. Unset uses the per-platform profile default. Gated models (e.g. `deepseek-r1-distill-70b`) require `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`. | +| `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` | JSON array of non-blank strings | Appends advanced operator-owned tokens to the managed `vllm serve` command after NemoClaw's registry defaults. Example: `["--max-num-seqs","2"]`. Malformed JSON, non-string tokens, or blank tokens fail before Docker work starts. | | `NEMOCLAW_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; see Runtime Controls (use the `nemoclaw-user-manage-sandboxes` skill). | | `NEMOCLAW_MODEL_ROUTER_PYTHON` | absolute path | Pins the host Python interpreter used to create the Model Router virtual environment. Strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to another python. Relative command names such as `python3.12` are rejected. When unset, NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, retains every interpreter whose version is in `[3.10, 3.14)` and whose `ensurepip`, `pyexpat`, `ssl`, and `venv` stdlib modules import cleanly, and tries `python -m venv` on each in priority order until one succeeds. Set the pin when the auto-discovered interpreter is broken (for example, Homebrew `python@3.14` with a `pyexpat` dlopen mismatch on macOS). | @@ -2195,6 +2247,7 @@ These flags change defaults for commands that manage existing sandboxes. | `NEMOCLAW_CLEANUP_GATEWAY` | `1`, `true`, or `yes` to enable; `0`, `false`, or `no` to disable | Sets the default for whether `nemoclaw destroy` removes the shared gateway when destroying the last sandbox. Command-line `--cleanup-gateway` and `--no-cleanup-gateway` still take precedence. | | `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR` | `1` to enable | Skips the automatic DNS-proxy repair for stale `inference.local` routes during `nemoclaw connect` and `nemoclaw connect --probe-only`. Use only as a troubleshooting escape hatch. | | `NEMOCLAW_SHIELDS_ACCEPT_LEGACY_BASELINE` | `1` to opt in | Allows advanced immutable-config verification to trust the current on-disk bytes for older or partial content baselines. Use only after you have rebuilt or manually inspected the sandbox state and accepted that the baseline is operator-approved. | +| `NEMOCLAW_SHIELDS_SETTLE_MS` | milliseconds (default `750`, clamped to `0`–`10000`) | Settle window NemoClaw waits after re-applying a config lockdown (during shields auto-restore and `nemoclaw shields up` drift remediation) before re-confirming the lock still holds. Detects when an in-sandbox reconciler changes config file permissions after lockdown and re-applies the lock; if NemoClaw cannot re-confirm the lock within the retry budget, shields stay down. This narrows the window in which a reconciler can revert permissions rather than eliminating it — the best-effort `chattr +i` immutable bit remains the only fully durable lock. Raise it on hosts where the gateway settles slowly. | ### Remote Deployment diff --git a/.agents/skills/nemoclaw-user-reference/references/network-policies.md b/.agents/skills/nemoclaw-user-reference/references/network-policies.md index fdc19f68135..7ddf32c6b76 100644 --- a/.agents/skills/nemoclaw-user-reference/references/network-policies.md +++ b/.agents/skills/nemoclaw-user-reference/references/network-policies.md @@ -32,7 +32,7 @@ The following endpoint groups are allowed by default: | Policy | Endpoints | Binaries | Rules | | --- | --- | --- | --- | -| `nvidia` | `integrate.api.nvidia.com:443`, `inference-api.nvidia.com:443` | `/usr/local/bin/openclaw` | POST to inference and embedding paths, GET to model listings | +| `nvidia` | `integrate.api.nvidia.com:443` | `/usr/local/bin/openclaw` | POST to inference and embedding paths, GET to model listings | | `clawhub` | `clawhub.ai:443` | `/usr/local/bin/openclaw`, `/usr/local/bin/node` | GET, POST | | `openclaw_api` | `openclaw.ai:443` | `/usr/local/bin/openclaw`, `/usr/local/bin/node` | GET, POST | | `openclaw_docs` | `docs.openclaw.ai:443` | `/usr/local/bin/openclaw` | GET only | diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index e5aa968086a..297e4f8ff9f 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -1609,6 +1609,20 @@ Expected output: Point an OpenAI-compatible client at `http://127.0.0.1:8642/v1` for chat completions. For terminal use, run `nemohermes connect` and then `hermes` inside the sandbox. +### `docker port` shows no mapping for 8642 even though forwarding works + +OpenShell port forwards are host-side relays managed by the OpenShell gateway process, not Docker `-p` publish mappings on the sandbox container. +`docker port openshell-hermes-` reflects only Docker-published ports, so it returns nothing for OpenShell-managed forwards even when the host bind is live. + +Use OpenShell's own view as the supported acceptance signal: + +```bash +openshell forward list # shows the host bind for each forwarded port +curl -sf http://127.0.0.1:8642/health # confirms the relayed endpoint answers +``` + +If `openshell forward list` does not show port `8642`, run `nemohermes connect --probe-only` (or `nemohermes recover`) to ask the recovery path to re-establish every manifest-declared agent forward port that has gone missing. + ### `nemohermes` reports `Sandbox 'X' already exists as OpenClaw` Each sandbox name maps to exactly one agent type. diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index 71e7e769014..ec0fe58995b 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -15,6 +15,17 @@ NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use this page to track the highlights of the latest release. For more detailed release notes, refer to the [NemoClaw GitHub announcements](https://github.com/NVIDIA/NemoClaw/discussions/categories/announcements?discussions_q=is%3Aopen+category%3AAnnouncements). +## v0.0.65 + +NemoClaw v0.0.65 improves gateway recovery, sandbox state restore, local inference setup, and messaging activation: + +- Gateway and sandbox recovery now wait for sustained serving state, recover sandboxes whose active gateway has lost its spec, preserve gateway routing state across more rebuilds, and allocate dashboard ports across multiple NemoClaw gateways. For more information, refer to [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle) and [Troubleshooting](../reference/troubleshooting). +- Rebuild and restore flows preserve more OpenClaw and registry state. Config restore fails closed when a merge cannot be applied safely, reporter-owned model metadata survives rebuild restore, Shields auto-restore locks are re-confirmed after settle, and persisted agents survive registry recovery. For more information, refer to [Backup and Restore](../manage-sandboxes/backup-restore) and [NemoClaw CLI Commands Reference](../reference/commands). +- Onboarding and inference setup fail earlier with clearer diagnostics. NemoClaw now handles Docker Desktop WSL CDI injection failures, surfaces silent OpenClaw runtime fallback, preflights managed vLLM model selection before side effects, accepts managed vLLM extra serve arguments, bounds compatible-endpoint probes, summarizes inference validation failures, and recomputes context windows after runtime model switches. For more information, refer to [Troubleshooting](../reference/troubleshooting), [NemoClaw Inference Options](../inference/inference-options), and [Switch Inference Providers](../inference/switch-inference-providers). +- Day-two CLI operations gained safer file and session workflows. `$$nemoclaw download`, `$$nemoclaw upload`, and `$$nemoclaw sessions export` wrap the underlying sandbox file transfer and OpenClaw session export paths, while uninstall handles TTY confirmation and model-router teardown more predictably. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands) and [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle). +- Messaging activation stores and exposes less credential-adjacent state. NemoClaw avoids logging WeChat QR poll tokens, resolves Discord per-account proxy settings for gateway WebSocket connections, compacts persisted messaging plans, completes manifest-based channel migration, and removes provider credential hashes from sandbox registry entries. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels) and [Credential Storage](../security/credential-storage). +- Hermes defaults and sandbox compatibility are narrower and easier to recover. The Hermes baseline policy no longer includes GitHub by default, NemoClaw reserves Hermes port `8642` across agent variants, and spawned OpenClaw sub-agents dial back through the sandbox interface instead of blocked loopback paths. For more information, refer to [Network Policies](../reference/network-policies), [NemoClaw Quickstart with Hermes](../get-started/quickstart-hermes), and [Set Up Task-Specific Sub-Agents](../inference/set-up-sub-agent). + ## v0.0.64 NemoClaw v0.0.64 improves sandbox restore, onboarding stability, inference routing, messaging setup, and release validation: diff --git a/fern/fern.config.json b/fern/fern.config.json index 37536b72aa2..956e0bab392 100644 --- a/fern/fern.config.json +++ b/fern/fern.config.json @@ -1,4 +1,4 @@ { "organization": "nvidia", - "version": "5.45.0" + "version": "5.49.2" }