diff --git a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md index 53257172d85..f943d1af667 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md @@ -6,8 +6,6 @@ license: "Apache-2.0" # Use a Local Inference Server -import { AgentOnly } from "../_components/AgentGuide"; - ## Gotchas - Ollama is convenient for local chat, but some model/template combinations can return tool calls as plain text under realistic agent load. @@ -17,17 +15,11 @@ import { AgentOnly } from "../_components/AgentGuide"; - NemoClaw installed. Refer to the Quickstart (use the `nemoclaw-user-get-started` skill) if you have not installed yet. - - - - - - NemoClaw installed. Refer to Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) if you have not installed yet. - - - - A local model server running, or a supported Ollama, vLLM, or NIM setup that the NemoClaw onboard wizard can use, start, or install. +import { AgentOnly } from "../_components/AgentGuide"; + NemoClaw can route inference to a model server running on your machine instead of a cloud API. This page covers Ollama, compatible-endpoint paths for other servers, and experimental managed options for vLLM and NVIDIA NIM. 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 48cf9b38c41..23f9b612926 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 @@ -13,7 +13,7 @@ When adapting an OpenClaw sub-agent setup, use these paths inside the sandbox: | Path | Purpose | |---|---| | `/sandbox/.openclaw/openclaw.json` | OpenClaw config, including `models.providers`, `agents.defaults`, and `agents.list`. | -| `/sandbox/.openclaw/.config-hash` | Hash for `openclaw.json`. Keep it in sync after manual config edits; it becomes a startup-enforced trust anchor only after the file is root-owned and read-only. | +| `/sandbox/.openclaw/.config-hash` | Hash for `openclaw.json`. Keep it in sync after manual config edits so OpenClaw can detect the updated config. | | `/sandbox/.openclaw/agents//agent/auth-profiles.json` | Per-agent provider credentials. Use this when a sub-agent calls an auxiliary provider directly. | | `/sandbox/.openclaw/workspace/` | Writable shared workspace path for files the primary agent passes to the sub-agent. | | `/tmp/gateway.log` | OpenClaw gateway log. Use it to confirm config reloads and diagnose sub-agent failures. | @@ -41,26 +41,30 @@ The primary orchestration model remains responsible for conversation, planning, ## Update the Sandbox Config Fetch the current OpenClaw config from the sandbox, patch it with your auxiliary provider and `agents.list` changes, then upload it back. +On Docker-driver sandboxes, run these commands from the host that owns the sandbox containers. +The container name includes a runtime suffix, so discover it from the OpenShell sandbox label: ```bash export SANDBOX=my-assistant -export DOCKER_CTR=openshell-cluster-nemoclaw -docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json +export SANDBOX_CTR=$(docker ps --filter "label=openshell.ai/sandbox-name=$SANDBOX" --format "{{.Names}}" | sed -n '1p') +docker exec --user root "$SANDBOX_CTR" cat /sandbox/.openclaw/openclaw.json > /tmp/openclaw.json ``` Create `/tmp/openclaw.updated.json` with the OpenClaw sub-agent config. For the Omni example, the demo provides `vlm-demo/vlm-subagent/openclaw-patch.py`. Upload the patched config and refresh the hash. -In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof; lock the config root-owned and read-only afterward if the sandbox should enforce config integrity at startup. +In the default mutable state, this keeps the local hash consistent but does not make it tamper-proof. +Use NemoClaw runtime controls when the sandbox needs a hardened config posture after the manual edit. ```bash -docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/openclaw.json -docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 644 /sandbox/.openclaw/.config-hash -cat /tmp/openclaw.updated.json | docker exec -i "$DOCKER_CTR" kubectl exec -i -n openshell "$SANDBOX" -c agent -- sh -c 'cat > /sandbox/.openclaw/openclaw.json' -docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- /bin/bash -c "cd /sandbox/.openclaw && sha256sum openclaw.json > .config-hash" -docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/openclaw.json -docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chmod 444 /sandbox/.openclaw/.config-hash +docker exec --user root "$SANDBOX_CTR" chmod 644 /sandbox/.openclaw/openclaw.json +docker exec --user root "$SANDBOX_CTR" chmod 644 /sandbox/.openclaw/.config-hash +docker exec --user root -i "$SANDBOX_CTR" sh -c 'cat > /sandbox/.openclaw/openclaw.json' < /tmp/openclaw.updated.json +docker exec --user root "$SANDBOX_CTR" /bin/bash -c "cd /sandbox/.openclaw && sha256sum openclaw.json > .config-hash" +docker exec --user root "$SANDBOX_CTR" chown sandbox:sandbox /sandbox/.openclaw/openclaw.json /sandbox/.openclaw/.config-hash +docker exec --user root "$SANDBOX_CTR" chmod 444 /sandbox/.openclaw/openclaw.json +docker exec --user root "$SANDBOX_CTR" chmod 444 /sandbox/.openclaw/.config-hash ``` Check `/tmp/gateway.log` after upload and confirm the gateway hot-reloaded the provider or `agents.list` change. @@ -78,7 +82,7 @@ Use the same provider ID that appears in `models.providers`, such as `nvidia-omn After uploading the auth profile, make sure the sandbox user owns the sub-agent directory: ```bash -docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator +docker exec --user root "$SANDBOX_CTR" chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator ``` ## Allow Auxiliary Provider Egress diff --git a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md index 9885238e642..67bbe967f34 100644 --- a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md +++ b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md @@ -13,7 +13,8 @@ license: "Apache-2.0" ## Prerequisites -- The [Brev CLI](https://brev.nvidia.com) installed and authenticated. +- Access to a remote GPU VM that can run Docker and the NVIDIA Container Toolkit. +- The [Brev CLI](https://brev.nvidia.com) installed and authenticated if you provision the VM with Brev. - A provider credential for the inference backend you want to use during onboarding. - `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN` exported when your remote vLLM or Hugging Face workflow needs access to gated models. - NemoClaw installed locally if you plan to use the deprecated `nemoclaw deploy` wrapper. Otherwise, install NemoClaw directly on the remote host after provisioning it. @@ -21,14 +22,50 @@ license: "Apache-2.0" Run NemoClaw on a remote GPU instance through [Brev](https://brev.nvidia.com). The preferred path is to provision the VM, run the standard NemoClaw installer on that host, and then run `nemoclaw onboard`. -## Deploy the Instance +## Preferred Deployment Path + +Provision the remote GPU VM first, then run the normal installer and onboard flow on that VM. +For Brev, `` is the instance name and SSH alias created by the Brev CLI. +For another cloud provider, replace the provisioning and SSH commands with that provider's console or CLI workflow. + +```bash +# On your local machine +brev create --gpu +brev ssh +``` + +If `brev` is missing or unauthenticated, install or log in to the Brev CLI first, or provision the VM through your cloud console and connect with `ssh @`. + +Run the installer on the remote VM: + +```bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +``` + +Set any remote-only environment variables on the VM before onboarding. +For example, set the browser origin if you will open the dashboard through a Brev public URL, and raise the first-run readiness budget on cold cloud hosts: + +```bash +export CHAT_UI_URL="https://openclaw0-.brevlab.com" +export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 +nemoclaw onboard +``` + +After successful onboarding, you should see output that reports a ready sandbox and the next command to connect: + +```text +✓ Sandbox '' is ready +Next: nemoclaw connect +``` + +## Legacy Brev Compatibility **Warning:** The `nemoclaw deploy` command is deprecated. Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `nemoclaw onboard` on that host. -Create a Brev instance and run the legacy compatibility flow: +Use the legacy compatibility wrapper only when you need the older Brev-specific bootstrap flow: ```bash nemoclaw deploy @@ -51,38 +88,40 @@ If you export `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`, the wrapper forwards those ## Connect to the Remote Sandbox -After deployment finishes, the deploy command opens an interactive shell inside the remote sandbox. -To reconnect after closing the session, run the command again: +After onboarding finishes, run the host CLI on the remote VM: ```bash -nemoclaw deploy +nemoclaw connect ``` +If you used the deprecated Brev compatibility wrapper, the wrapper opens an interactive shell inside the remote sandbox. +To reconnect through that legacy flow, run `nemoclaw deploy ` again. + ## Monitor the Remote Sandbox -SSH to the instance and run the OpenShell TUI to monitor activity and approve network requests: +SSH to the instance and run the OpenShell TUI on the remote VM to monitor activity and approve network requests: ```bash -ssh 'cd ~/nemoclaw && set -a && . .env && set +a && openshell term' +ssh 'openshell term' ``` ## Verify Inference -Run a test agent prompt inside the remote sandbox: +Run a test agent prompt from the remote VM host: ```bash -openclaw agent --agent main -m "Hello from the remote sandbox" --session-id test +nemoclaw exec -- openclaw agent --agent main -m "Hello from the remote sandbox" --session-id test ``` ## Remote Dashboard Access The NemoClaw dashboard validates the browser origin against an allowlist baked into the sandbox image at build time. By default, the allowlist only contains `http://127.0.0.1:18789`. -When you access the dashboard from a remote browser, for example through a Brev public URL or an SSH port-forward, set `CHAT_UI_URL` to the origin the browser uses before running setup: +When you access the dashboard from a remote browser, for example through a Brev public URL or an SSH port-forward, set `CHAT_UI_URL` to the origin the browser uses before running `nemoclaw onboard` on the remote VM: ```bash export CHAT_UI_URL="https://openclaw0-.brevlab.com" -nemoclaw deploy +nemoclaw onboard ``` For SSH port-forwarding, the origin is typically the default `http://127.0.0.1:18789`, so you do not need extra configuration. @@ -134,9 +173,11 @@ Changing the proxy after onboarding requires re-running `nemoclaw onboard`. ## GPU Configuration -The deploy script uses the `NEMOCLAW_GPU` environment variable to select the GPU type. +The deprecated Brev compatibility wrapper uses the `NEMOCLAW_GPU` environment variable to select the GPU type. The default value is `a2-highgpu-1g:nvidia-tesla-a100:1`. -Set this variable before running `nemoclaw deploy` to use a different GPU configuration: +That value is specific to GCP-backed Brev instances. +Other Brev providers or cloud consoles use different GPU type strings. +Set this variable before running the deprecated wrapper to use a different GPU configuration: ```bash export NEMOCLAW_GPU="a2-highgpu-1g:nvidia-tesla-a100:2" diff --git a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md index 52be8190dea..1a098d710b8 100644 --- a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md @@ -159,12 +159,9 @@ openshell policy set --policy live-policy.yaml my-assistant Dynamic changes apply only to the current session. When the sandbox stops, the running policy resets to the baseline policy plus the presets recorded for the sandbox. - -To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above; the file under `presets/` persists) or edit `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. - - -To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above; the file under `presets/` persists) or edit the Hermes policy additions and re-run `nemoclaw onboard`. - +Custom presets applied through `nemoclaw policy-add --from-file` or `--from-dir` are recorded with the sandbox, including their full YAML content. +Snapshot restore and rebuild replay those recorded presets, so they survive sandbox recreation even if the original files are no longer on disk. +For permanent baseline changes that apply to every future sandbox, edit the source policy for the target agent and re-run `nemoclaw onboard`. ### Approve Requests Interactively diff --git a/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md b/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md index f28f5dff5f2..bc2182bea5c 100644 --- a/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md +++ b/.agents/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md @@ -4,6 +4,7 @@ import { AgentOnly } from "../_components/AgentGuide"; Use these examples when a sandbox is already installed and an integration needs network access. This page covers only integrations that NemoClaw currently ships as maintained policy preset YAML under `nemoclaw-blueprint/policies/presets/`. +For complete blueprint examples that combine a model, agent harness, OpenShell policy, and integration workflow, see [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community). Integration setup usually has two separate parts: - Configure the integration itself, such as a bot token, OAuth credential, or agent plugin setting. diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md b/.agents/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md index d4cb90d3e12..66a09957ecf 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md @@ -31,6 +31,8 @@ Snapshots capture all workspace state directories defined in the agent manifest Agent manifests can also declare durable top-level state files. For Hermes, snapshots include `SOUL.md` and the SQLite database behind `.hermes/state.db` using SQLite's online backup API, then restore that database through SQLite instead of copying a live raw database file. Treat snapshot directories as private local data: the Hermes database can contain session metadata and message history needed for a faithful restore. +Snapshots also preserve sandbox registry metadata that affects rebuild behavior, including custom policy presets applied with `policy-add --from-file` or `policy-add --from-dir`. +When you restore a snapshot, NemoClaw replays those recorded custom presets with their stored YAML content, so you do not need the original preset files on disk for the restored sandbox to keep the same policy state. ```bash nemoclaw my-assistant snapshot create diff --git a/.agents/skills/nemoclaw-user-overview/references/ecosystem-hermes.md b/.agents/skills/nemoclaw-user-overview/references/ecosystem-hermes.md index ae660f0ad68..0d644a1adbb 100644 --- a/.agents/skills/nemoclaw-user-overview/references/ecosystem-hermes.md +++ b/.agents/skills/nemoclaw-user-overview/references/ecosystem-hermes.md @@ -91,3 +91,4 @@ Use the following table to decide when to use NemoHermes versus OpenShell alone. - [How It Works](how-it-works.md) describes how NemoClaw runs, the blueprint, sandbox creation, routing, and protection layers for Hermes. - Architecture (use the `nemoclaw-user-reference` skill) shows the repository structure and technical diagrams. - Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) installs NemoClaw and launches your first Hermes sandbox. +- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) collects community-driven examples, showcases, and integrations that demonstrate complete blueprint patterns. diff --git a/.agents/skills/nemoclaw-user-overview/references/ecosystem.md b/.agents/skills/nemoclaw-user-overview/references/ecosystem.md index a5a11e289c3..ee7c25cdf70 100644 --- a/.agents/skills/nemoclaw-user-overview/references/ecosystem.md +++ b/.agents/skills/nemoclaw-user-overview/references/ecosystem.md @@ -90,3 +90,4 @@ Use the following table to decide when to use NemoClaw versus OpenShell. - [Overview](overview.md) describes what NemoClaw is, including capabilities, benefits, and use cases. - [How It Works](how-it-works.md) describes how NemoClaw runs, including the plugin, blueprint, sandbox creation, routing, and protection layers. - Architecture (use the `nemoclaw-user-reference` skill) shows the repository structure and technical diagrams. +- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) collects community-driven examples, showcases, and integrations that demonstrate complete blueprint patterns. diff --git a/.agents/skills/nemoclaw-user-overview/references/overview.md b/.agents/skills/nemoclaw-user-overview/references/overview.md index a5dc5d525f4..87d325c07ad 100644 --- a/.agents/skills/nemoclaw-user-overview/references/overview.md +++ b/.agents/skills/nemoclaw-user-overview/references/overview.md @@ -65,6 +65,7 @@ Navigate to the following topics to learn more about NemoClaw and how to install - [Ecosystem](ecosystem.md) to understand how your agent, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. - Quickstart with OpenClaw (use the `nemoclaw-user-get-started` skill) to install NemoClaw and run your first OpenClaw sandbox. - Agent Skills (use the `nemoclaw-user-agent-skills` skill) to load NemoClaw guidance into an AI coding assistant. +- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) to explore community-driven blueprint examples, showcases, and integrations. - Inference Options (use the `nemoclaw-user-configure-inference` skill) to check the inference providers that NemoClaw supports and how inference routing works. @@ -74,6 +75,7 @@ Navigate to the following topics to learn more about NemoClaw and how to install - [Ecosystem](ecosystem.md) to understand how Hermes, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. - Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) to install NemoClaw and run your first Hermes sandbox with `nemoclaw`. - Agent Skills (use the `nemoclaw-user-agent-skills` skill) to load NemoClaw guidance into an AI coding assistant. +- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) to explore community-driven blueprint examples, showcases, and integrations. - Inference Options (use the `nemoclaw-user-configure-inference` skill) to check the inference providers that NemoClaw supports and how inference routing works. diff --git a/.agents/skills/nemoclaw-user-overview/references/release-notes.md b/.agents/skills/nemoclaw-user-overview/references/release-notes.md index 52703842e5f..2ff2cc4e67c 100644 --- a/.agents/skills/nemoclaw-user-overview/references/release-notes.md +++ b/.agents/skills/nemoclaw-user-overview/references/release-notes.md @@ -6,6 +6,16 @@ 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.64 + +NemoClaw v0.0.64 improves sandbox restore, onboarding stability, inference routing, messaging setup, and release validation: + +- Snapshot restore preserves custom policy presets applied with `policy-add --from-file` or `policy-add --from-dir`, so restored sandboxes keep the custom egress rules that were recorded with the source sandbox. For more information, refer to Backup and Restore (use the `nemoclaw-user-manage-sandboxes` skill) and Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill). +- 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 NemoClaw v0.0.63 improves sandbox recovery, OpenClaw configuration restore safety, local inference onboarding, messaging safeguards, and release validation: diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md index b8c9a0348d6..6b9d7de6979 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands.md +++ b/.agents/skills/nemoclaw-user-reference/references/commands.md @@ -224,6 +224,8 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOC 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 Brave Search in non-interactive mode, set: ```bash @@ -233,7 +235,17 @@ BRAVE_API_KEY=... \ `BRAVE_API_KEY` enables Brave Search in non-interactive mode and also enables `web_fetch`. If Brave Search key validation fails in non-interactive mode, onboarding prints a warning, skips web search setup, and continues with the rest of the sandbox setup. -After fixing the key, re-enable web search with `nemoclaw config web-search`. +After fixing the key, rerun onboarding with `BRAVE_API_KEY` set so NemoClaw can validate the key, register the Brave Search provider, and apply the `brave` policy preset. +If the sandbox already exists without web search, accept the recreate prompt or pass `--recreate-sandbox`. + + + + +Hermes does not use NemoClaw's OpenClaw Brave Search setup. +If you authenticate Hermes through Nous Portal OAuth, the wizard can prompt for managed Nous tool gateways such as web search. +API-key mode is inference-only and does not enable managed tool gateways. + + 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. @@ -496,6 +508,44 @@ 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) | +### 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 config get` + +Read the sanitized agent configuration from a sandbox. +The output removes credential-bearing sections such as the OpenClaw gateway token before printing. +Use `--key` to read one dotpath and `--format` to choose JSON or YAML output. + +```bash +nemoclaw my-assistant config get +nemoclaw my-assistant config get --key model --format yaml +``` + +| Flag | Description | +|------|-------------| +| `--key ` | Print one value from the sanitized config | +| `--format json\|yaml` | Output format. Defaults to JSON | + +#### `nemoclaw shields` + +Manage the sandbox config lockdown posture from the host. +Use `shields status` to inspect the current state, `shields up` to lock the sandbox config and restore the captured restrictive policy, and `shields down` to temporarily unlock the config for maintenance. +For the full mutability matrix, see Runtime Controls (use the `nemoclaw-user-manage-sandboxes` skill). + +```bash +nemoclaw my-assistant shields status +nemoclaw my-assistant shields up +nemoclaw my-assistant shields down --timeout 5m --reason "maintenance" +``` + +| Subcommand | Description | +|------|-------------| +| `shields status` | Show whether lockdown is configured, active, temporarily unlocked, or in error | +| `shields up` | Lock the sandbox config and restore the saved restrictive policy | +| `shields down` | Temporarily unlock the sandbox config. Supports `--timeout`, `--reason`, and `--policy` | + ### `nemoclaw recover` Restart the in-sandbox gateway and re-establish the host-side dashboard port-forward without opening an SSH session. @@ -1222,6 +1272,55 @@ nemoclaw my-assistant sessions delete agent:main:slack:c-9 --json | `--json` | Print the delete result as JSON. | | `--verbose` | Print the gateway entry payload after a successful delete. | +### `nemoclaw sessions export [keys...]` + +Export the OpenClaw session JSONL from a running sandbox to the host, replacing the two-hop `docker exec kubectl cp` plus `docker cp` workaround. + +The command always enumerates the session store through `openclaw sessions list --agent --json` and copies only the matching `.jsonl` (plus optional `.trajectory.jsonl`) files, so the export 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 session for the agent. +Pass one or more keys (alias or canonical `agent::`) to filter. + +```bash +nemoclaw my-assistant sessions export +nemoclaw my-assistant sessions export main --agent main +nemoclaw my-assistant sessions export agent:work:telegram:t-1 --include-trajectory +nemoclaw my-assistant sessions export --format tar --out ./bundles/alpha.tgz --json +``` + +| Flag | Description | +|------|-------------| +| `--agent ` | Agent id when `` are aliases rather than the canonical `agent::` form. | +| `--format ` | `dir` (default) writes a directory of session files; `tar` writes a single `.tgz` bundle for sharing/upload. | +| `--out ` | Host destination. Defaults to `./sessions-/` for `dir`, or `./sessions--.tgz` for `tar`. | +| `--include-trajectory` | Include the (large) `*.trajectory.jsonl` files in the export. Excluded by default. | +| `--json` | Print the export manifest as JSON instead of a status line. | + +Mismatched `--agent` plus canonical-key combinations are refused before any download runs. +Session keys that begin with `-` are rejected at the command boundary instead of being silently dropped. +Session JSONL can contain pasted secrets (API keys, tokens), so exported files are written owner-only (`0600`); for `tar` format the in-sandbox staging tarball is additionally created with `umask 077` and removed after the host download completes. + +### `nemoclaw download [host-dest]` + +Host-side wrapper around `openshell sandbox download` that adds a live-sandbox readiness check. +The source path inside the sandbox and the host destination are forwarded to OpenShell verbatim, so the file-system semantics (single-file vs directory copy, trailing-slash handling, overwrite behaviour) follow the OpenShell transport. +With no `host-dest` the destination defaults to the current directory. + +```bash +nemoclaw my-assistant download /sandbox/.openclaw/workspace/SOUL.md ./ +nemoclaw my-assistant download /sandbox/.openclaw/agents/main/sessions/ ./sessions/ +``` + +### `nemoclaw upload [sandbox-dest]` + +Host-side wrapper around `openshell sandbox upload`, symmetric to the download wrapper. +With no `sandbox-dest` the destination defaults to `/sandbox/` inside the sandbox. + +```bash +nemoclaw my-assistant upload ./local-file /sandbox/ +nemoclaw my-assistant upload ./backups/SOUL.md /sandbox/.openclaw/workspace/SOUL.md +``` + ### `nemoclaw rebuild` Upgrade a sandbox to the current agent version while preserving workspace state. @@ -1549,7 +1648,7 @@ nemoclaw status --json When at least one sandbox is registered and the named NemoClaw gateway is unreachable, unhealthy, or attached to a different sandbox, the command prints a `gateway: down [state] (reason)` line between the sandbox list and the host-service list. The command classifies the failing layer when possible: the named gateway port is not accepting connections, the named gateway is running but not Connected, the active OpenShell gateway points at a different name, or the named gateway is not configured at all. -It then suggests `openshell gateway start --name nemoclaw` or `nemoclaw onboard --resume` to recover. +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. diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index 62dc86fa0b5..e5aa968086a 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -369,10 +369,9 @@ nemoclaw onboard `nemoclaw connect` checks the OpenShell gateway before it tries dashboard forwarding, SSH, or inference repair. If the gateway is not reachable, the command exits early and prints recovery guidance. -Start the gateway or resume onboarding, then retry: +Resume onboarding so NemoClaw recreates or reconnects the managed gateway, then retry: ```bash -openshell gateway start --name nemoclaw nemoclaw onboard --resume nemoclaw connect ``` @@ -550,12 +549,12 @@ Follow these steps to reconnect. If the sandbox shows `Ready`, skip to step 4. -1. Restart the gateway (if needed). +1. Recover the managed gateway (if needed). - If the sandbox is not listed or the command fails, restart the OpenShell gateway: + If the sandbox is not listed or the command fails, let NemoClaw recover the managed gateway and sandbox registration: ```bash - openshell gateway start --name nemoclaw + nemoclaw onboard --resume ``` Wait a few seconds, then re-check with `openshell sandbox list`. @@ -648,11 +647,11 @@ nemoclaw rebuild ### Sandbox creation reports a TLS certificate mismatch -If sandbox creation reports a TLS or certificate mismatch, the OpenShell gateway certificate may have changed since the CLI last trusted it. -Refresh the gateway trust and then resume onboarding: +If sandbox creation reports a TLS or certificate mismatch, the OpenShell gateway certificate may have changed since the CLI last registered it. +Remove the stale local gateway registration and then resume onboarding so NemoClaw refreshes the registration: ```bash -openshell gateway trust -g nemoclaw +openshell gateway remove nemoclaw nemoclaw onboard --resume ``` @@ -1376,6 +1375,12 @@ openshell sandbox delete Fix the NVIDIA Container Toolkit or CDI configuration reported in the diagnostics, clean up the failed sandbox, then rerun onboarding. If you do not need GPU access inside the sandbox, rerun with `--no-sandbox-gpu`. Set `NEMOCLAW_DOCKER_GPU_PATCH=0` only when you need to bypass this compatibility path during troubleshooting. +On Docker Desktop WSL the patch is required for GPU passthrough — `NEMOCLAW_DOCKER_GPU_PATCH=0` is ignored on that runtime, and onboarding logs a warning when it is set there. +To skip GPU passthrough entirely on Docker Desktop WSL, rerun with `--no-gpu` or set `NEMOCLAW_SANDBOX_GPU=0`. + +If sandbox creation fails with `CDI device injection failed: unresolvable CDI devices nvidia.com/gpu=all`, the OpenShell gateway tried `docker create --device nvidia.com/gpu=all` and Docker could not resolve the CDI spec. +This injection happens inside the gateway, so `NEMOCLAW_DOCKER_GPU_PATCH=0` does not bypass it. +Rerun with `--no-gpu`, or set `NEMOCLAW_SANDBOX_GPU=0` and resume onboarding. If onboarding reports `OpenShell supervisor did not reconnect to the GPU-enabled container.` even though the diagnostic bundle shows the patched container is running and healthy, the supervisor-reconnect wait is treating a transient Error phase (reported while the OpenShell host re-registers the new container) as fatal. The reconnect wait debounces consecutive Error-phase polls before fast-failing, defaulting to fifteen consecutive polls of about 30 seconds in total. diff --git a/.github/workflows/pr.yaml b/.github/workflows/pr.yaml index 856fedd828d..da60bd16259 100644 --- a/.github/workflows/pr.yaml +++ b/.github/workflows/pr.yaml @@ -60,11 +60,15 @@ jobs: - name: Install docs-only check dependencies run: npm install --ignore-scripts - - name: Fetch base commit for docs-only checks - run: git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.sha }}" + - name: Fetch checked-out merge base for docs-only checks + shell: bash + run: | + DOCS_ONLY_FROM_REF="$(git rev-parse HEAD^1)" + git fetch --no-tags --depth=1 origin "$DOCS_ONLY_FROM_REF" + echo "DOCS_ONLY_FROM_REF=$DOCS_ONLY_FROM_REF" >> "$GITHUB_ENV" - name: Run docs-only hook checks - run: npx prek run --from-ref "${{ github.event.pull_request.base.sha }}" --to-ref HEAD + run: npx prek run --from-ref "$DOCS_ONLY_FROM_REF" --to-ref HEAD - name: Verify platform matrix is in sync run: python3 scripts/generate-platform-docs.py --check diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index 87f3657d0cd..03c40c9e2df 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -15,6 +15,15 @@ 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.64 + +NemoClaw v0.0.64 improves sandbox restore, onboarding stability, inference routing, messaging setup, and release validation: + +- Snapshot restore preserves custom policy presets applied with `policy-add --from-file` or `policy-add --from-dir`, so restored sandboxes keep the custom egress rules that were recorded with the source sandbox. For more information, refer to [Backup and Restore](../manage-sandboxes/backup-restore) and [Customize the Network Policy](../network-policy/customize-network-policy). +- 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](../reference/commands). +- 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](../inference/inference-options). +- 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](../manage-sandboxes/messaging-channels). + ## v0.0.63 NemoClaw v0.0.63 improves sandbox recovery, OpenClaw configuration restore safety, local inference onboarding, messaging safeguards, and release validation: diff --git a/docs/manage-sandboxes/backup-restore.mdx b/docs/manage-sandboxes/backup-restore.mdx index 3d8949b1408..0d9b5c558ad 100644 --- a/docs/manage-sandboxes/backup-restore.mdx +++ b/docs/manage-sandboxes/backup-restore.mdx @@ -42,6 +42,8 @@ Snapshots capture all workspace state directories defined in the agent manifest Agent manifests can also declare durable top-level state files. For Hermes, snapshots include `SOUL.md` and the SQLite database behind `.hermes/state.db` using SQLite's online backup API, then restore that database through SQLite instead of copying a live raw database file. Treat snapshot directories as private local data: the Hermes database can contain session metadata and message history needed for a faithful restore. +Snapshots also preserve sandbox registry metadata that affects rebuild behavior, including custom policy presets applied with `policy-add --from-file` or `policy-add --from-dir`. +When you restore a snapshot, NemoClaw replays those recorded custom presets with their stored YAML content, so you do not need the original preset files on disk for the restored sandbox to keep the same policy state. ```bash $$nemoclaw my-assistant snapshot create diff --git a/docs/network-policy/customize-network-policy.mdx b/docs/network-policy/customize-network-policy.mdx index d553f70894d..6d03d85711f 100644 --- a/docs/network-policy/customize-network-policy.mdx +++ b/docs/network-policy/customize-network-policy.mdx @@ -164,12 +164,9 @@ openshell policy set --policy live-policy.yaml my-assistant Dynamic changes apply only to the current session. When the sandbox stops, the running policy resets to the baseline policy plus the presets recorded for the sandbox. - -To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above; the file under `presets/` persists) or edit `openclaw-sandbox.yaml` and re-run `$$nemoclaw onboard`. - - -To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above; the file under `presets/` persists) or edit the Hermes policy additions and re-run `$$nemoclaw onboard`. - +Custom presets applied through `$$nemoclaw policy-add --from-file` or `--from-dir` are recorded with the sandbox, including their full YAML content. +Snapshot restore and rebuild replay those recorded presets, so they survive sandbox recreation even if the original files are no longer on disk. +For permanent baseline changes that apply to every future sandbox, edit the source policy for the target agent and re-run `$$nemoclaw onboard`. ### Approve Requests Interactively diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index 33e2b09c362..caabe5b7064 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -437,7 +437,7 @@ nemohermes my-assistant config get --key model --format yaml | Flag | Description | |------|-------------| | `--key ` | Print one value from the sanitized config | -| `--format json|yaml` | Output format. Defaults to JSON | +| `--format json\|yaml` | Output format. Defaults to JSON | #### `nemohermes shields` diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index a5ad39c341e..6f0e4b105e0 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -535,7 +535,7 @@ $$nemoclaw my-assistant config get --key model --format yaml | Flag | Description | |------|-------------| | `--key ` | Print one value from the sanitized config | -| `--format json|yaml` | Output format. Defaults to JSON | +| `--format json\|yaml` | Output format. Defaults to JSON | #### `$$nemoclaw shields`